Add a section to the PR guide on how to write good titles and descriptions#1845
Open
sirosen wants to merge 1 commit into
Open
Add a section to the PR guide on how to write good titles and descriptions#1845sirosen wants to merge 1 commit into
sirosen wants to merge 1 commit into
Conversation
Add a short section to the PR guide which covers good titles and descriptions, at a summary level. The priority here is (in presentation order): - explain the rationale / why we care - demonstrate how a PR title should look - give some hint as to what a good description will look like Explaining how to write good technical prose for a PR description is considered out of scope, which limits the content of the PR description section.
Documentation build overview
3 files changed± getting-started/index.html± versions/index.html± getting-started/pull-request-lifecycle/index.html |
Comment on lines
+213
to
+214
| pull request does in short form. It should start with ``gh-NNNNNN:``, for pull | ||
| requests which close open issues. |
Member
There was a problem hiding this comment.
Suggested change
| pull request does in short form. It should start with ``gh-NNNNNN:``, for pull | |
| requests which close open issues. | |
| pull request does in short form. Pull requests attached to issues should | |
| be linked by putting the issue number in the title (``gh-NNNNNN:``). |
A rough suggestion. For two reasons:
- We don't clarify what
gh-NNNN:actually is. - They don't always close issues, but we still want the ref for follow-ups, backports etc.
| The title should be a sentence or phrase in the imperative which says what the | ||
| pull request does in short form. It should start with ``gh-NNNNNN:``, for pull | ||
| requests which close open issues. | ||
| For example, ``gh-12345: Fix bug when spam module is served with eggs``. |
Member
There was a problem hiding this comment.
Some of this is duplicated in the Submitting section. To me, the Making good PRs section seems like a checklist about the change itself, not a checklist for the PR on GitHub.
I think, looking at the (albeit quite terrible) flow, this section is too early (the following section here is about pre-submission things, for example), and can be merged with the duplicated content in Submitting.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add a short section to the PR guide which covers good titles and descriptions, at a summary level.
The priority here is (in presentation order):
Explaining how to write good technical prose for a PR description is considered out of scope, which limits the content of the PR description section.
Resolves #931
Supersedes prior PRs, and therefore