open-pull-request

Open a Pull Request

CLI vs MCP Decision Rule

• Inner loop (fast local branch work): prefer GitHub CLI (gh pr create).
• Outer loop (cross-system coordination): use MCP tools for structured/authenticated access.

Pre-flight Checks

Before opening a PR:

• Working tree is clean (git status)
• Upstream target repository confirmed from workspace metadata (Cargo.toml → repository)
• Branch is rebased on the latest develop from upstream (<upstream-remote>/develop); verify with git log --oneline HEAD..<upstream-remote>/develop (empty output means up to date) and rebase if behind
• Branch is pushed to your fork remote
• Commits are GPG signed (git log --show-signature -n 1)
• All pre-commit checks passed (linter all, cargo machete, tests)
• PR body claims are aligned with the actual commit range (<upstream-remote>/develop..HEAD)
• If manual verification used temporary local-only patches, PR body explicitly says they are not included
• PR body paragraphs are written as single continuous lines (no hard line wrapping)

Keeping the branch up to date

Always rebase your branch on the latest upstream develop before pushing — both when opening a PR for the first time and when pushing updates to an existing PR:

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

git fetch $UPSTREAM_REMOTE
git rebase $UPSTREAM_REMOTE/develop

# Then push (use --force-with-lease when rewriting history)
git push --force-with-lease <fork-remote> <branch-name>

In general, every PR targeting develop should sit on top of the latest commit in <upstream-remote>/develop. Check this whenever you push or re-push.

Important:

• Never push directly to develop or main.
• Always open the PR in the upstream repository, not in your fork.
• For merges into develop or main, the PR head must be a fork branch (<fork-owner>:<branch>), not an upstream branch.
• Remote names vary by contributor (josecelano, origin, torrust, upstream, etc.); resolve remotes dynamically.

Resolve upstream from Cargo.toml (repository = "https://github.com/torrust/torrust-tracker") and use that value for gh pr create --repo ....

Title and Description Convention

Body Formatting for GitHub

Before opening the PR, review and reformat the body text following the write-markdown-docs checklist for GitHub surfaces:

• Write each paragraph as a single continuous line — do not hard-wrap at any fixed column width
• Use GitHub Flavored Markdown (GFM) conventions
• Check for accidental #NUMBER autolinks (only use #NUMBER for intentional issue/PR references)

Title

PR title: use Conventional Commit style, include issue reference.

Examples:

• feat(tracker-core): [#42] add peer expiry grace period
• docs(agents): set up basic AI agent configuration (#1697)

PR body must include:

• Summary of changes
• Files/packages touched
• Validation performed
• Issue link (see rules below)

PR body must not include:

• Claims about code changes that are not present in the branch diff
• Ambiguous wording that mixes temporary local verification patches with committed implementation

Issue Linking Rules

GitHub auto-closes an issue when a merged PR body contains Closes #N, Fixes #N, or Resolves #N. Choose the correct keyword based on what the PR contains:

Rule: only use Closes/Fixes/Resolves when the PR fully resolves the issue. A spec-only PR does not resolve the issue — use Related to #N to avoid auto-closing it.

Identifying the PR type

Before writing the PR body, check the diff:

git diff <upstream-remote>/develop...HEAD --name-only

• Diff touches only docs/issues/ → spec-only → use Related to #N
• Diff touches source code, tests, or other non-spec files → implementation → use Closes #N
• Diff touches both spec and implementation → combined → use Closes #N

Option A (Preferred): GitHub CLI

gh pr create \
  --repo <upstream-owner>/<upstream-repo> \
  --base develop \
  --head <fork-owner>:<branch-name> \
  --title "<title>" \
  --body "<body>"

Example upstream resolution from Cargo.toml:

UPSTREAM_REPO=$(grep '^repository\s*=\s*"https://github.com/' Cargo.toml | sed -E 's#.*github.com/([^\"]+).*#\1#')
gh pr create --repo "$UPSTREAM_REPO" --base develop --head <fork-owner>:<branch-name> --title "<title>" --body "<body>"

If successful, gh prints the PR URL.

Option B: GitHub MCP Tools

When MCP pull request management tools are available, create the PR with:

• base: develop
• head: <fork-owner>:<branch-name>
• Capture and share the resulting PR URL.

Post-creation Validation

• PR targets torrust/torrust-tracker:develop
• Head branch is correct
• CI workflows started
• Issue linked with the correct keyword (Related to for spec-only, Closes for implementation)
• PR body still matches branch diff and commit history after final rebases/edits

Quick body-accuracy verification:

gh pr view <pr-number> --repo <upstream-owner>/<upstream-repo> --json body
git diff --name-only <upstream-remote>/develop...HEAD
git log --oneline <upstream-remote>/develop..HEAD

Troubleshooting

• fatal: ... does not appear to be a git repository: push to correct remote (git remote -v)
• A pull request already exists: open existing PR URL instead of creating new
• Permission errors on upstream: use owner:branch fork syntax