From 4d24e74592f5709ea5da862a6cdf0746cce5b0d2 Mon Sep 17 00:00:00 2001 From: Giovanita Bell <129814598+gioviebell@users.noreply.github.com> Date: Sat, 9 Aug 2025 00:35:44 -0500 Subject: [PATCH 1/2] Update pull-request-lifecycle.rst Updated the "making a good PR" section of the page with tips on creating the title and description --- getting-started/pull-request-lifecycle.rst | 26 ++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/getting-started/pull-request-lifecycle.rst b/getting-started/pull-request-lifecycle.rst index fe810e90f..a0c5507bc 100644 --- a/getting-started/pull-request-lifecycle.rst +++ b/getting-started/pull-request-lifecycle.rst @@ -213,6 +213,30 @@ should do to help ensure that your pull request is accepted. the other hand, fixes for typos and grammar errors in documents and docstrings are welcome. +#. **Follow best practices when creating the PR title and description.** The + pull requests title and description play a pivotal role in code review and + issue resolution. It is the initial point of contact in a code review, and + allows the code reviewer to quickly assess the issue. The suggested formatting + of the title and description is + **[type(optional) title: description (issue number)]** where type is the label + associated with the issue being resolved. Based on `Best practices for + writing good pull request titles`_, a pull request title should be descriptive but + to the point. It should establish a clear yet brief summary, so to allow the code + reviewer to quickly assess the pull request. + The description should explain what was changed in the pull request, why it exists, + and explain the process of what was done in the pull request. + Here is an example of a poor and revised pull request description: + **Poor Pull Request:** "update code" **Revised Pull Request:** + "feat: add search functionality to user dashboard(closes #111)" + + For more examples on writing a good pull request title, please take a look at + `Best practices for + writing good pull request titles`_ + + To read more on creating a descriptive pull request description, please review + `Anatomy of a perfect pull request`_ + + #. **Be aware of backwards-compatibility considerations.** While the core developer who eventually handles your pull request will make the final call on whether something is acceptable, thinking about backwards-compatibility early @@ -606,3 +630,5 @@ accepts your pull request. .. _issue tracker: https://github.com/python/cpython/issues .. _Core Development Discourse category: https://discuss.python.org/c/core-dev/23 .. _Release Status: https://buildbot.python.org/all/#/release_status +.. _Best practices for writing good pull request titles: https://graphite.dev/guides/best-pr-title-guidelines +.. _Anatomy of a perfect pull request: https://opensource.com/article/18/6/anatomy-perfect-pull-request From f1b556b50ef260f5a99b3303032f8f2ef7baa904 Mon Sep 17 00:00:00 2001 From: Giovanita Bell <129814598+gioviebell@users.noreply.github.com> Date: Sun, 10 Aug 2025 18:35:05 -0500 Subject: [PATCH 2/2] Update pull-request-lifecycle.rst PR title and description section Updated the title formatting, and provided an example. Also removed trailing whitespaces. --- getting-started/pull-request-lifecycle.rst | 32 ++++++++++++---------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/getting-started/pull-request-lifecycle.rst b/getting-started/pull-request-lifecycle.rst index a0c5507bc..49d8de261 100644 --- a/getting-started/pull-request-lifecycle.rst +++ b/getting-started/pull-request-lifecycle.rst @@ -213,24 +213,28 @@ should do to help ensure that your pull request is accepted. the other hand, fixes for typos and grammar errors in documents and docstrings are welcome. -#. **Follow best practices when creating the PR title and description.** The - pull requests title and description play a pivotal role in code review and +#. **Follow best practices when creating the PR title and description.** The + pull requests title and description play a pivotal role in code review and issue resolution. It is the initial point of contact in a code review, and allows the code reviewer to quickly assess the issue. The suggested formatting - of the title and description is - **[type(optional) title: description (issue number)]** where type is the label - associated with the issue being resolved. Based on `Best practices for - writing good pull request titles`_, a pull request title should be descriptive but - to the point. It should establish a clear yet brief summary, so to allow the code - reviewer to quickly assess the pull request. - The description should explain what was changed in the pull request, why it exists, - and explain the process of what was done in the pull request. - Here is an example of a poor and revised pull request description: - **Poor Pull Request:** "update code" **Revised Pull Request:** + of the title and description is + + **GH-issue number: brief description of what the pull request resolves** + + **Example: GH-123456: Use pure op machinery to optimize various instructions + with _POP_TOP and _POP_TWO** + + Based on `Best practices for writing good pull request titles`_, a pull request + title should be descriptive but to the point. It should establish a clear yet brief + summary, so to allow the code reviewer to quickly assess the pull request. + The description should explain what was changed in the pull request, why it exists, + and explain the process of what was done in the pull request. + Here is an example of a poor and revised pull request description: + **Poor Pull Request:** "update code" **Revised Pull Request:** "feat: add search functionality to user dashboard(closes #111)" - For more examples on writing a good pull request title, please take a look at - `Best practices for + For more examples on writing a good pull request title, please take a look at + `Best practices for writing good pull request titles`_ To read more on creating a descriptive pull request description, please review