Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 27 additions & 2 deletions .github/skills/dev/git-workflow/open-pull-request/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,13 +48,38 @@ PR body must include:
- Summary of changes
- Files/packages touched
- Validation performed
- Issue link (`Closes #<issue-number>`)
- 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 <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`
Comment on lines +79 to +81

## Option A (Preferred): GitHub CLI

```bash
Expand Down Expand Up @@ -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:
Expand Down
8 changes: 8 additions & 0 deletions .github/skills/dev/planning/create-issue/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 #<number>` (not `Closes #<number>`) 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.
Expand Down Expand Up @@ -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 #<number>` in the PR body, never `Closes #<number>` / `Fixes #<number>` /
> `Resolves #<number>`. Those keywords trigger GitHub auto-close on merge.
Comment on lines +150 to +151
> 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`.
Expand Down