commit-changes - SKILL.md Agent Skill

name: commit-changes description: Guide for committing changes in the torrust-tracker project. Covers conventional commit format, pre-commit verification checklist, GPG signing, and commit quality guidelines. Use when committing code, running pre-commit checks, or following project commit standards. Triggers on "commit", "commit changes", "how to commit", "pre-commit", "commit message", "commit format", or "conventional commits". metadata: author: torrust version: "1.0"

Committing Changes

This skill guides you through the complete commit process for the Torrust Tracker project.

Quick Reference

# One-time setup: install the pre-commit Git hook
./contrib/dev-tools/git/install-git-hooks.sh

# Stage changes
git add <files>

# Commit with conventional format and GPG signature (MANDATORY)
# The pre-commit hook runs ./contrib/dev-tools/git/hooks/pre-commit.sh automatically
git commit -S -m "<type>[(<scope>)]: <description>"

Conventional Commit Format

We follow Conventional Commits specification.

Commit Message Structure

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Scope should reflect the affected package or area (e.g., tracker-core, udp-protocol, ci, docs).

Commit Types

Type	Description	Example
`feat`	New feature or enhancement	`feat(tracker-core): add peer expiry grace period`
`fix`	Bug fix	`fix(udp-protocol): resolve endianness in announce response`
`docs`	Documentation changes	`docs(agents): add root AGENTS.md`
`style`	Code style changes (formatting, etc.)	`style: apply rustfmt to all source files`
`refactor`	Code refactoring	`refactor(tracker-core): extract peer list to own module`
`test`	Adding or updating tests	`test(http-tracker-core): add announce response tests`
`chore`	Maintenance tasks	`chore: update dependencies`
`ci`	CI/CD related changes	`ci: add workflow for container publishing`
`perf`	Performance improvements	`perf(torrent-repository): switch to dashmap`

GPG Commit Signing (MANDATORY)

All commits must be GPG signed. Use the -S flag:

git commit -S -m "your commit message"

Pre-commit Verification (MANDATORY)

Git Hook

The repository ships a pre-commit Git hook that runs ./contrib/dev-tools/git/hooks/pre-commit.sh automatically on every git commit. Install it once after cloning:

./contrib/dev-tools/git/install-git-hooks.sh

Once installed, the hook fires on every commit and you do not need to run the script manually.

Automated Checks

If the hook is not installed, run the script explicitly before committing. It must exit with code 0.

⏱️ Expected runtime: ~1 minute on a modern developer machine with warm caches. AI agents should set a command timeout of at least 3 minutes before invoking this script. AI agents should also set TORRUST_GIT_HOOKS_LOG_DIR=.tmp so per-step log files are written inside the workspace (git-ignored) instead of /tmp.

TORRUST_GIT_HOOKS_LOG_DIR=.tmp ./contrib/dev-tools/git/hooks/pre-commit.sh

The script runs:

cargo machete — unused dependency check
linter all — all linters (markdown, YAML, TOML, clippy, rustfmt, shellcheck, cspell)
cargo test --doc --workspace — documentation tests

For AI execution, prefer structured output first:

./contrib/dev-tools/git/hooks/pre-commit.sh --format=json

If it fails and deeper diagnostics are needed, retry with:

./contrib/dev-tools/git/hooks/pre-commit.sh --format=text --verbosity=verbose

Manual Checks (Cannot Be Automated)

Verify these by hand before committing:

Self-review the diff: read through git diff --staged and check for obvious mistakes, debug artifacts, or unintended changes
Documentation updated: if public API or behaviour changed, doc comments and any relevant docs/ pages reflect the change
AGENTS.md updated: if architecture, package structure, or key workflows changed, the relevant AGENTS.md file is updated
New technical terms added to project-words.txt: any new jargon or identifiers that cspell does not know about are added alphabetically

Debugging a Failing Run

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

Fix Rust formatting automatically:

cargo fmt

Hashtag Usage Warning

Only use # when intentionally referencing a GitHub issue.

GitHub auto-links #NUMBER to issues. Avoid accidental references:

✅ feat(tracker-core): add feature (see #42) — intentional reference
❌ fix: make feature #1 priority — accidentally links to issue #1

Use ordered Markdown lists or plain numbers instead of #N step labels.

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
Signed: GPG signature present

Commits to Avoid (❌)

Too large: multiple unrelated changes in one commit
Vague messages like "fix stuff" or "WIP"
Missing scope when a package is clearly affected
Unsigned commits