Skip to content

Commit 4e09f23

Browse files
committed
docs/style: Elaborate on "Fixes:" links in PR descriptions
This was unclear in a couple of respects, as I learned here: #5493 (comment) Specifically, fill in some background that's well known to those of us who work in GitHub daily but isn't otherwise obvious. Also make better cross-references, and expand a bit on leaving issue numbers out of PR titles.
1 parent 7bd56c3 commit 4e09f23

File tree

1 file changed

+20
-6
lines changed

1 file changed

+20
-6
lines changed

docs/style.md

Lines changed: 20 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -301,6 +301,10 @@ intended to fix; or intended to help with; or could make worse; etc.
301301
Similarly, when you file an issue, mention any issue you're aware of
302302
that it's similar to, or might interact with, etc.
303303

304+
(When the issue is *fixed* by the PR, see also the next two items,
305+
on [mentioning in a commit message](#mention-fixed-issue)
306+
and [the format to use](#fixes-format).)
307+
304308
These cause GitHub to automatically link back from the other issue to
305309
the new PR or issue. The cross-references in both directions are
306310
essential for:
@@ -310,24 +314,33 @@ essential for:
310314

311315
Be sure to use the PR (or issue) description, not the title: for
312316
whatever reason, GitHub doesn't count links in PR titles for creating
313-
automatic backlinks.
317+
automatic backlinks. (Plus, an issue number in a PR title gets shown
318+
confusingly close to the PR's own number.)
314319

315320

316321
<div id="mention-fixed-issue" />
317322

318323
**Mention a fixed issue in both PR and commit message.**
319324
When you submit a fix for an issue, please refer to it *both*
320-
* in the PR description, and
325+
* in the PR description (aka summary, body, or zeroth comment—the
326+
thing you write in a large textbox when you submit a PR, which you
327+
can also edit later); and
321328
* in the commit message of the main commit that fixes it.
322329

330+
In both places, use the `Fixes: #1234` format discussed
331+
[below](#fixes-format).
332+
This [causes GitHub to close the issue automatically][gh-close-issue-keywords]
333+
when the commit and/or PR is merged, and to make a handy special link
334+
to the PR wherever the issue appears.
335+
323336
The commit message is important because the commits in Git become our
324337
primary record of what we did: people will read the commit message and
325338
want to be able to look at the issue for context.
326339

327340
The reference in the PR description is important for the sake of the
328-
GitHub website, for the reasons mentioned above. When the reference
329-
is only in a commit message, GitHub doesn't use that information as
330-
usefully.
341+
GitHub website, for the reasons [mentioned above](#mention-related-issues).
342+
When the reference is only in a commit message, GitHub doesn't use
343+
that information as usefully.
331344

332345
You might find that a reference in a commit message causes GitHub to
333346
show a noisy list of backlinks in the issue thread, after you make
@@ -341,7 +354,8 @@ extremely helpful when [reading the Git log](howto/git.md).
341354

342355
**Write `Fixes: #1234` when fixing an issue.**
343356
When a commit fixes an issue, use a line like `Fixes: #1234` at the
344-
end of the commit message.
357+
end of the commit message and the PR description, as further discussed
358+
[above](#mention-fixed-issue).
345359

346360
If there are any `Reported-by:` or similar lines (as discussed above),
347361
put it next to them. See for example 58028d6d1:

0 commit comments

Comments
 (0)