@@ -301,6 +301,10 @@ intended to fix; or intended to help with; or could make worse; etc.
301
301
Similarly, when you file an issue, mention any issue you're aware of
302
302
that it's similar to, or might interact with, etc.
303
303
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
+
304
308
These cause GitHub to automatically link back from the other issue to
305
309
the new PR or issue. The cross-references in both directions are
306
310
essential for:
@@ -310,24 +314,33 @@ essential for:
310
314
311
315
Be sure to use the PR (or issue) description, not the title: for
312
316
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.)
314
319
315
320
316
321
<div id =" mention-fixed-issue " />
317
322
318
323
** Mention a fixed issue in both PR and commit message.**
319
324
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
321
328
* in the commit message of the main commit that fixes it.
322
329
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
+
323
336
The commit message is important because the commits in Git become our
324
337
primary record of what we did: people will read the commit message and
325
338
want to be able to look at the issue for context.
326
339
327
340
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.
331
344
332
345
You might find that a reference in a commit message causes GitHub to
333
346
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).
341
354
342
355
** Write ` Fixes: #1234 ` when fixing an issue.**
343
356
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 ) .
345
359
346
360
If there are any ` Reported-by: ` or similar lines (as discussed above),
347
361
put it next to them. See for example 58028d6d1:
0 commit comments