From 559bb1a019860596745b6df640dc0d4038b73386 Mon Sep 17 00:00:00 2001 From: Jose Celano Date: Wed, 13 May 2026 18:42:23 +0100 Subject: [PATCH 1/2] fix(issues): restore 1778 spec to open/ (issue was accidentally closed) Issue #1778 was closed by the PR that merged the issue spec into the repo. The implementation has not been done yet, so the issue and its spec should remain open. Issue #1778 has been reopened on GitHub. --- docs/issues/{closed => open}/1778-migrate-to-rust-edition-2024.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/issues/{closed => open}/1778-migrate-to-rust-edition-2024.md (100%) 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 From f75f2c6c4cd2f6a09ae4a635283ef6e875af9fc0 Mon Sep 17 00:00:00 2001 From: Jose Celano Date: Wed, 13 May 2026 18:46:51 +0100 Subject: [PATCH 2/2] docs(skills): add PR-to-issue linking rules to open-pull-request and create-issue Clarify when to use 'Closes #N' vs 'Related to #N' in PR bodies: - Spec-only PRs must use 'Related to #N' to avoid auto-closing the issue on merge. The issue should remain open until the implementation lands. - Implementation PRs (spec+impl combined, or impl-only) use 'Closes #N'. Changes: - open-pull-request/SKILL.md: replace single 'Closes #N' rule with an 'Issue Linking Rules' section containing a decision table and a diff- based check to identify the PR type; update post-creation checklist. - create-issue/SKILL.md: add 'Related to' warning in the workflow overview and in the spec-only PR step (Step 6), with a cross-reference to the open-pull-request skill. --- .../git-workflow/open-pull-request/SKILL.md | 29 +++++++++++++++++-- .../skills/dev/planning/create-issue/SKILL.md | 8 +++++ 2 files changed, 35 insertions(+), 2 deletions(-) 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`.