Visitar URL original
Update pull-request-lifecycle.rst with creating PR title and descriptions (#931) by gioviebell 路 Pull Request #1626 路 python/devguide 路 GitHub
Skip to content

Update pull-request-lifecycle.rst with creating PR title and descriptions (#931) #1626

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gioviebell wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Update pull-request-lifecycle.rst with creating PR title and descriptions (#931) #1626

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4d24e74
Update pull-request-lifecycle.rst
gioviebell Aug 9, 2025
65613fb
Merge branch 'main' into main
gioviebell Aug 9, 2025
f1b556b
Update pull-request-lifecycle.rst PR title and description section
gioviebell Aug 10, 2025
a11f273
Merge pull request #1 from gioviebell/gioviebell-patch-1
gioviebell Aug 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
Update pull-request-lifecycle.rst 
Updated the "making a good PR" section of the page with tips on creating the title and description
  • Loading branch information
@gioviebell
gioviebell authored Aug 9, 2025
commit 4d24e74592f5709ea5da862a6cdf0746cce5b0d2
26 changes: 26 additions & 0 deletions getting-started/pull-request-lifecycle.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

@StanFromIreland StanFromIreland Aug 9, 2025 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't understand this, where is the gh-XXXXX, and what is type?

An example title:

GH-132732: Use pure op machinery to optimize various instructions with _POP_TOP and _POP_TWO

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)"
Comment on lines +232 to +234

@StanFromIreland StanFromIreland Sep 17, 2025

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This has the same issue I mentioned above (which was correct).


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
Expand Down Expand Up @@ -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