create-feature-branch

# 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) For a spec-only branch, use `{issue-number}-{short-description}-spec`. Reserve the base issue branch name for the later implementation branch so the two phases do not collide. 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 ```bash # 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` - `2134-fix-cognitive-complexity-lint-enforcement-spec` — spec-only branch ❌ **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` ```bash # 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](../commit-changes/SKILL.md). ### 3. Pre-commit Checks ```bash cargo machete linter all cargo test --doc --workspace cargo test --tests --benches --examples --workspace --all-targets --all-features ``` ### 4. Push to Your Fork ```bash 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: ```bash 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 ```bash 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`