create-feature-branch

name	create-feature-branch
description	Guide for creating feature branches following the torrust-tracker branching conventions. Covers branch naming format, lifecycle, and common patterns. Use when creating branches for issues, starting work on tasks, or setting up development branches. Triggers on "create branch", "new branch", "checkout branch", "branch for issue", or "start working on issue".
metadata	{"author":"torrust","version":"1.0"}

Creating Feature Branches

This skill guides you through creating feature branches following the Torrust Tracker branching conventions.

Delivery Policy

• Never push directly to develop or main.
• To merge into develop or main, you must open a PR in torrust/torrust-tracker.
• That PR must come from a branch in a fork (<fork-owner>:<branch>), not a branch in the same repository.
• Remote names are contributor-specific. Do not assume origin or torrust; identify remotes from git remote -v.
• The upstream repository is https://github.com/torrust/torrust-tracker. Its remote is commonly named torrust, but verify with git remote -v.
• Before branching, always fetch and pull the latest develop from the upstream remote to ensure the branch starts from an up-to-date base.

Branch Naming Convention

Format: {issue-number}-{short-description} (preferred)

Alternative formats (no tracked issue):

• feat/{short-description}
• fix/{short-description}
• chore/{short-description}

Rules:

• Always start with the GitHub issue number when one exists
• Use lowercase letters only
• Separate words with hyphens (not underscores)
• Keep description concise but descriptive

Creating a Branch

Standard Workflow

# Identify the upstream remote (points to https://github.com/torrust/torrust-tracker)
# It is commonly named "torrust"; verify with: git remote -v
UPSTREAM_REMOTE=torrust  # replace if your remote has a different name

# Ensure you're on the latest develop from upstream
git checkout develop
git fetch $UPSTREAM_REMOTE
git pull --ff-only $UPSTREAM_REMOTE develop

# Create and checkout branch for issue #42
git checkout -b 42-add-peer-expiry-grace-period

With MCP GitHub Tools

1. Get the issue number and title
2. Format the branch name: {number}-{kebab-case-description}
3. Create the branch from develop
4. Checkout locally: git fetch && git checkout {branch-name}

Branch Naming Examples

✅ Good branch names:

• 42-add-peer-expiry-grace-period
• 156-refactor-udp-server-socket-binding
• 203-add-e2e-mysql-tests
• 1697-ai-agent-configuration

❌ Avoid:

• my-feature — no issue number
• FEATURE-123 — all caps
• fix_bug — underscores instead of hyphens
• 42_add_support — underscores

Branch Name Validation

Before creating a branch, verify that the issue number (if used) actually exists as an open issue in GitHub and has a matching spec in docs/issues/open/. This prevents accidentally referencing a wrong, closed, or non-existent issue number.

Note: The git hooks runner (issue #1843) will eventually automate this check. Until then, verify manually by checking whether docs/issues/open/ contains a spec file or directory starting with the issue number.

Complete Branch Lifecycle

1. Create Branch from develop

# Identify the upstream remote (commonly "torrust"; verify with git remote -v)
UPSTREAM_REMOTE=torrust  # replace if your remote has a different name

git checkout develop
git fetch $UPSTREAM_REMOTE
git pull --ff-only $UPSTREAM_REMOTE develop
git checkout -b 42-add-peer-expiry-grace-period

2. Develop

Make commits following commit conventions.

3. Pre-commit Checks

cargo machete
linter all
cargo test --doc --workspace
cargo test --tests --benches --examples --workspace --all-targets --all-features

4. Push to Your Fork

git push {your-fork-remote} 42-add-peer-expiry-grace-period

To avoid assuming remote names, resolve upstream from Cargo.toml and then select your fork remote:

UPSTREAM_REPO=$(grep '^repository\s*=\s*"https://github.com/' Cargo.toml | sed -E 's#.*github.com/([^\"]+).*#\1#')
git remote -v
# Choose the remote that points to your fork (not "$UPSTREAM_REPO")

5. Create Pull Request

Target branch: torrust/torrust-tracker:develop from <fork-owner>:<branch-name>.

6. Cleanup After Merge

git checkout develop
git pull --ff-only
git branch -d 42-add-peer-expiry-grace-period

Converting Issue Title to Branch Name

1. Get issue number (e.g., #42)
2. Take issue title (e.g., "Add Peer Expiry Grace Period")
3. Convert to lowercase kebab-case: add-peer-expiry-grace-period
4. Prefix with issue number: 42-add-peer-expiry-grace-period