Skip to content

SKILL.md

Latest commit

 

History

History
168 lines (118 loc) · 5.91 KB

SKILL.md

File metadata and controls

168 lines (118 loc) · 5.91 KB
Raw
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 version
torrust
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:

  1. cargo machete — unused dependency check
  2. linter all — all linters (markdown, YAML, TOML, clippy, rustfmt, shellcheck, cspell)
  3. 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