diff --git a/.github/skills/dev/git-workflow/open-pull-request/SKILL.md b/.github/skills/dev/git-workflow/open-pull-request/SKILL.md index 6c6e4bc83..842fa710f 100644 --- a/.github/skills/dev/git-workflow/open-pull-request/SKILL.md +++ b/.github/skills/dev/git-workflow/open-pull-request/SKILL.md @@ -48,13 +48,38 @@ PR body must include: - Summary of changes - Files/packages touched - Validation performed -- Issue link (`Closes #`) +- 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: + +| PR type | Keyword to use | Example | +| --------------------------------------------------------------------------------------- | --------------- | ------------------ | +| **Spec-only** — PR contains only the issue spec document, no implementation | `Related to #N` | `Related to #1780` | +| **Implementation** — PR implements the issue (whether or not it also includes the spec) | `Closes #N` | `Closes #1780` | + +> **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: + +```bash +git diff /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 ```bash @@ -88,7 +113,7 @@ When MCP pull request management tools are available, create the PR with: - [ ] PR targets `torrust/torrust-tracker:develop` - [ ] Head branch is correct - [ ] CI workflows started -- [ ] Issue linked in description +- [ ] 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: diff --git a/.github/skills/dev/planning/create-issue/SKILL.md b/.github/skills/dev/planning/create-issue/SKILL.md index 6d31c7ef5..b007aecdc 100644 --- a/.github/skills/dev/planning/create-issue/SKILL.md +++ b/.github/skills/dev/planning/create-issue/SKILL.md @@ -43,6 +43,8 @@ For complex or high-impact issues, a **spec-first PR** is recommended: - Open a branch containing only issue-spec/EPIC documentation changes - Submit and merge that PR into `develop` first - Start implementation only after the specification PR has been reviewed and merged +- Use `Related to #` (not `Closes #`) in the spec-only PR body to avoid + auto-closing the issue on merge (see the `open-pull-request` skill) This improves visibility and allows maintainers/contributors to review scope and acceptance criteria before code changes begin. @@ -144,6 +146,12 @@ contains only the issue specification changes: 7. Merge PR after review 8. Start implementation work in a separate branch/PR +> **Important — do NOT auto-close the issue from a spec-only PR.** +> Use `Related to #` in the PR body, never `Closes #` / `Fixes #` / +> `Resolves #`. Those keywords trigger GitHub auto-close on merge. +> The issue must remain open until the implementation is merged. +> See the `open-pull-request` skill for the full issue-linking rules. + Policy notes: - Never push directly to `develop` or `main`. diff --git a/docs/issues/closed/1778-migrate-to-rust-edition-2024.md b/docs/issues/open/1778-migrate-to-rust-edition-2024.md similarity index 100% rename from docs/issues/closed/1778-migrate-to-rust-edition-2024.md rename to docs/issues/open/1778-migrate-to-rust-edition-2024.md