Follow the principle of local consistency
Some of the conventions given below have multiple options. In those cases, or if in doubt, aim to be consistent locally e.g., when naming PRs, follow the convention most other PRs (especially, those done by senior developers) in the repo seem to follow.
Situation 1: The PR fully fixes an existing issue in the issue tracker (i.e., the issue can be closed when the PR is merged):
Error alert email has very long subject #5958
[#5958] Error alert email has very long subject
Shorten the error alert email subject
Rationale: Duplicating issue title in PR title is for easy tracing between PRs and issues, to compensate for GitHub’s lack of strong linking between the two. Assume there is an invisible prefix in front of the PR title
Fix issue: …
Situation 2: All other cases (i.e., the issue is only a partial fix to an existing issue or it does not correspond to an existing issue):
→ Name the PR as if it is the subject line of a commit that contains the entire PR code.
Follow when you submit a PR, GitHub will present you with some boilerplate content to tell you what details to includethe PR template (example), if any.
Fixes keyword annotations in the PR description so that the related issue can auto-closed when the PR is merged.
If the PR is a partial fix, use
Fixes part of #1234.
Give before-and-after screenshots if applicable. If yor change results in UI changes that are not readily apparent from the code, give before and after screenshots to help the reviewer.
Give the proposed merge commit message if applicable. If the PR has more than one commit and the PR is non-trivial, propose a commit message for the merge commit.
[Details of the PR...]
Proposed commit message:
commit message goes here more ...
When merging a PR branch to the main branch, use one of these formats for the subject line of the merge commit.
Issue Title #IssueNumber (#PrNumber)
Error alert email has very long subject #5958 (#6580)
[#IssueNumber] Issue Title (#PrNumber)
[#5958] Error alert email has very long subject (#6580)
PR Title (#PrNumber) (i.e., based on PR only, issue info omitted)
Error alert email has very long subject (#6580)
Pick one option and use it consistently in the entire code base.
Rationale: This format allows easy traceability among a merge commit, the issue it fixes, and the PR that fixed it. Having the issue name tells us what the commit is about without having to look it up in GitHub issue tracker.
Issue title should be concise yet descriptive. For example, instead of
Newbie question, please help, use
How do I set up git to ignore test files?
Follow when you submit an issue, GitHub will present you with some boilerplate content to tell you what details to includethe issue template (example), if any.