diff --git a/src/docs/Ways-of-Working/Commit-Conventions.md b/src/docs/Ways-of-Working/Commit-Conventions.md index c55a0f1..485e452 100644 --- a/src/docs/Ways-of-Working/Commit-Conventions.md +++ b/src/docs/Ways-of-Working/Commit-Conventions.md @@ -8,7 +8,7 @@ Commit messages serve two audiences: the engineer reading `git log` six months f 2. **No conventional-commit prefixes.** No `fix:`, `feat:`, `docs:`, `chore:`, `refactor:`, etc. The change type is captured at the PR level — repeating it on every commit adds noise without information. 3. **No generic messages.** `Update for PR`, `WIP`, `fixes`, `more changes` — all forbidden. They erase traceability. 4. **One logical change per commit.** Micro-iterative discipline. If a change touches three unrelated concerns, that's three commits. -5. **Reference issues by number when natural** — but don't force it. `Fixes #N` belongs in the PR description, not every commit message. +5. **Keep issue and pull request references out of commit messages.** Cross-references to issues and pull requests belong in the PR description and in issues — not in commit history. The pull request links the work to its issue (via a closing keyword such as `Fixes #123`); commits describe the change itself. ## Examples diff --git a/src/docs/Ways-of-Working/Issue-Format.md b/src/docs/Ways-of-Working/Issue-Format.md index 678c2ea..3117291 100644 --- a/src/docs/Ways-of-Working/Issue-Format.md +++ b/src/docs/Ways-of-Working/Issue-Format.md @@ -13,6 +13,7 @@ Every issue in the PSModule organization follows the same structure. The format - **Comments record change history only.** Each description update is accompanied by a comment summarizing what changed and why. - **Tone is impersonal.** No first-person ("I", "my") or second-person ("you", "your") language. Neutral references like "the user", "the developer", or passive constructions. - **External references are hyperlinks.** Every mention of an API, RFC, library, doc, or tool is a clickable `[text](url)` link. No bare URLs. +- **Issue and PR references are scoped to their target.** Use the `#123` shorthand for an issue or pull request in the same repository, and the fully qualified `Owner/Repo#123` form for one in another repository so the link resolves to the right place. Outside GitHub — Jira, Confluence, Slack, or any surface without GitHub autolinking — use the full URL (`https://github.com/Owner/Repo/issues/123`). - **No duplicates.** Existing issues are searched before creating or restructuring. Duplicates are consolidated or cross-linked. ## Title diff --git a/src/docs/Ways-of-Working/PR-Format.md b/src/docs/Ways-of-Working/PR-Format.md index cd637fe..2d03d08 100644 --- a/src/docs/Ways-of-Working/PR-Format.md +++ b/src/docs/Ways-of-Working/PR-Format.md @@ -103,13 +103,13 @@ Omit the section entirely if there's nothing noteworthy. ### 4. Related issues -A collapsible `
` block at the very end of the description containing issue links. Always use fully qualified references (`Owner/Repo#N`) so links work across repositories. +A collapsible `
` block at the very end of the description containing issue links. Use the `#123` shorthand for issues in the same repository and the fully qualified `Owner/Repo#123` form for issues in another repository so links resolve to the right place. When a reference appears outside GitHub (release announcements, Jira, Slack, external docs), use the full URL (`https://github.com/Owner/Repo/issues/123`). ```markdown
Related issues -- Fixes PSModule/GitHub#123 +- Fixes #123 - PSModule/Process-PSModule#124
@@ -155,8 +155,8 @@ Commands that query a specific repository, enterprise, or release by name now re
Related issues -- Fixes PSModule/GitHub#218 -- PSModule/GitHub#219 +- Fixes #218 +- #219
````