Add a section to the PR guide on how to write good titles and descriptions#1845
Add a section to the PR guide on how to write good titles and descriptions#1845sirosen wants to merge 3 commits 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 |
Co-authored-by: Stan Ulbrych <stan@python.org>
Give this section a referenceable label, and place it in the "Submitting" section rather than "Writing good pull requests". Keep the content largely the same, but add a new trailing sentence to note that `#NNNNN` syntax can link issues. This replaces a note from "Submitting" that was mostly redundant with the new section.
| If this is a pull request in response to a pre-existing issue on the | ||
| `issue tracker`_, please make sure to reference the issue number using | ||
| ``gh-NNNNN:`` prefix in the pull request title and ``#NNNNN`` in the description. | ||
| See :ref:`the section below on writing good titles and descriptions <good-pull-request-metadata>`. |
There was a problem hiding this comment.
I'm afraid I think this is a little odd, we are now jumping away from the section for some very key information (the amount of PR titles I've fixed is staggering).
I'd like to make further changes to "Submitting" -- I don't think it's quite right in scope right now
I think it's very much in scope now, considering we're editing it ;-) If we want minimal changes in this PR, then let's just add the content directly to the section IMO.
Additionally, I think this makes more sense after the following two comments, as we assume you already have an issue number.
| Avoid over-explaining: simpler descriptions are easier to read, so make sure not | ||
| to write large descriptions for simple changes. | ||
|
|
||
| Use ``#NNNNN`` in the description to refer to and link relevant issues. |
There was a problem hiding this comment.
We don't quite want this here IMO, since the bot automatically links the issue we'll just end up with duplicate references.
| the title (``gh-NNNNNN:``). | ||
| For example, ``gh-12345: Fix bug when spam module is served with eggs``. | ||
|
|
||
| The pull request description field should be a detailed summary. |
There was a problem hiding this comment.
| The pull request description field should be a detailed summary. | |
| The pull request description field should be a succinct summary. |
The amount of descriptions we get now with a list of tests that they ran and passed is quite annoying (all clearly straight from an AI, of course. :-/ )
2 participants
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