Committing Changes

This skill guides you through the complete commit process for the Torrust Tracker Deployer project, including conventional commit format, pre-commit checks, and quality standards.

Quick Reference

# 1. Run pre-commit checks (MANDATORY)
./scripts/pre-commit.sh

# 2. Stage changes
git add <files>

# 3. Commit with conventional format
git commit -m "{type}: [#{issue}] {description}"

Conventional Commit Format

We follow Conventional Commits specification.

Commit Message Structure

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Issue Number Convention

When working on a branch with an issue number, include it in your commit messages:

• •With issue branch: {type}: [#{issue}] {description}
  • •Example: feat: [#42] add MySQL database support
• •Without issue branch: {type}: {description}
  • •Example: docs: update deployment guide

Commit Types

Pre-commit Verification (MANDATORY)

Before committing any changes, you MUST run:

./scripts/pre-commit.sh

This script runs all mandatory checks:

1. •Unused dependencies: cargo machete
2. •All linters: cargo run --bin linter all (stable & nightly)
3. •Tests: cargo test
4. •Documentation builds: cargo doc --no-deps --bins --examples --workspace --all-features
5. •E2E infrastructure tests: cargo run --bin e2e-infrastructure-lifecycle-tests
6. •E2E deployment tests: cargo run --bin e2e-deployment-workflow-tests

All checks must pass before committing. Fix any reported issues.

Running Individual Linters (for debugging)

cargo run --bin linter markdown   # Markdown
cargo run --bin linter yaml       # YAML
cargo run --bin linter toml       # TOML
cargo run --bin linter clippy     # Rust code analysis
cargo run --bin linter rustfmt    # Rust formatting
cargo run --bin linter shellcheck # Shell scripts
cargo run --bin linter cspell     # Spell checking

Commit Examples

Feature with Issue Number

git commit -m "feat: [#42] add support for Ubuntu 22.04 in cloud-init"

Bug Fix with Issue Number

git commit -m "fix: [#15] resolve ansible inventory parsing error"

Documentation Update

git commit -m "docs: [#8] add troubleshooting section to README"

With Scope (optional)

git commit -m "fix(ansible): [#15] correct inventory file path resolution"

Breaking Change (note the !)

git commit -m "feat!: [#42] change default container provider from multipass to lxd"

Multi-line with Body and Footer

git commit -m "feat: [#23] add automated testing workflow

Add GitHub Actions workflow that tests:
- LXD container provisioning
- Multipass VM provisioning
- Ansible playbook execution

Closes #23"

Hashtag Usage Warning

Only use # when intentionally referencing a GitHub issue.

GitHub automatically links #NUMBER patterns to issues, so avoid accidental references:

• •✅ Correct: feat: [#42] add new feature (intentional reference)
• •✅ Correct: Closes #23 in footer (intentional)
• •❌ Incorrect: fix: update config #1 priority (accidentally links to issue #1)
• •❌ Incorrect: docs: add section #3 to guide (accidentally links to issue #3)

Common Mistakes to Avoid

# Bad: Accidentally links to issue #1
git commit -m "fix: make feature #1 priority"

# Good: Use alternative wording
git commit -m "fix: make feature top priority"
git commit -m "fix: make feature number one priority"

# Bad: Accidentally links to issue #3
git commit -m "docs: add section #3 about deployment"

# Good: Use alternative formatting
git commit -m "docs: add section 3 about deployment"
git commit -m "docs: add third section about deployment"

Commit Quality Guidelines

Good Commits (✅)

• •Atomic: Each commit represents one logical change
• •Descriptive: Clear, concise description of what changed
• •Tested: All tests pass
• •Linted: All linters pass
• •Conventional: Follows conventional commit format

Example of Good Commit History:

feat: [#42] add LXD container provisioning support
fix: [#15] resolve ansible inventory template rendering
docs: [#8] update contributing guidelines
test: [#67] add unit tests for configuration parsing
refactor: [#45] extract common logging utilities

Commits to Avoid (❌)

• •Too large: Multiple unrelated changes in one commit
• •Vague: Messages like "fix stuff" or "updates"
• •Broken: Commits that don't build or pass tests
• •Non-conventional: Not following the conventional commit format

Complete Workflow Example

# 1. Make your changes
vim src/main.rs

# 2. Run pre-commit checks (MANDATORY)
./scripts/pre-commit.sh

# 3. If checks fail, fix issues and re-run
#    Repeat until all checks pass

# 4. Stage changes
git add src/main.rs

# 5. Commit with conventional format
git commit -m "feat: [#42] add new CLI command"

# 6. Push to remote
git push origin 42-add-new-cli-command

Troubleshooting

Pre-commit Script Fails

Problem: One or more checks fail in ./scripts/pre-commit.sh

Solution:

1. •Read the error output carefully
2. •Fix the specific issue (e.g., run cargo fmt for formatting)
3. •Re-run ./scripts/pre-commit.sh
4. •Repeat until all checks pass

E2E Tests Take Too Long

Problem: E2E tests add significant time to the commit process

Context: This is intentional to ensure quality. The split test approach (e2e-infrastructure-lifecycle-tests + e2e-deployment-workflow-tests) is optimized for GitHub Actions compatibility while maintaining comprehensive coverage.

Alternative for Local Development: You can run the full E2E suite manually:

cargo run --bin e2e-complete-workflow-tests

Note: This is only supported in local environments with proper LXD networking and cannot run on GitHub Actions.

Linter Fails on Nightly Toolchain

Problem: cargo run --bin linter all fails on nightly Rust

Solution:

1. •Ensure you have the nightly toolchain: rustup toolchain install nightly
2. •Update toolchains: rustup update
3. •Re-run the linter

Related Documentation

• •Full Commit Process Guide: docs/contributing/commit-process.md
• •Contributing Guide: docs/contributing/README.md
• •Branching Conventions: docs/contributing/branching.md
• •Pre-commit Script: scripts/pre-commit.sh
• •Linting Guide: docs/contributing/linting.md

Key Reminders

1. •Always run ./scripts/pre-commit.sh before committing - This is non-negotiable
2. •Use issue numbers consistently - Follow the [#{issue}] format
3. •Be careful with hashtags - Only use #NUMBER when referencing issues
4. •Keep commits atomic - One logical change per commit
5. •Write descriptive messages - Future you will thank present you