Improved 'Making Good PRs' section to improve clarity and maintainability. by swastim01 · Pull Request #1510 · python/devguide

swastim01 · 2025-02-09T10:32:39Z

Improve PR Title Guidelines

Solves: #931

Description

Enforced a stricter PR title format to improve clarity and maintainability.
Encouraged writing accurate and concise PR titles/descriptions.

These changes aim to enhance the quality of PR titles.

📚 Documentation preview 📚: https://cpython-devguide--1510.org.readthedocs.build/getting-started/pull-request-lifecycle/

… content

ghost · 2025-02-09T10:32:42Z

All commit authors signed the Contributor License Agreement.

hugovk · 2025-02-09T12:07:05Z

It's hard to review the changes because the section was moved in the page, please could you move it back?

I think it makes sense to keep the original order, where the "quick guide" comes first. (But if we do want to move it up a section, let's do that in a separate PR, with no other textual changes.)

swastim01 · 2025-02-09T13:12:51Z

Hi, I have done the needful. Please let me know if any other changes are required.

hugovk · 2025-02-09T13:23:56Z

 .. _good-prs:

-Making good PRs
+Making Good PRs


Please retain sentence case: https://devguide.python.org/documentation/style-guide/#capitalization
Suggested change
Making Good PRs
Making good PRs
Same applies to the headers below.

hugovk · 2025-02-09T13:28:16Z

-#. Proper :ref:`documentation <documenting>` additions/changes should be included.
+When creating a pull request, following best practices ensures your contribution is **clear, maintainable, and easy to review**. A well-structured PR improves collaboration and speeds up the review process.
+
+1. **Use a Clear and Structured PR Title** 


Can we keep using #. so Sphinx auto-numbers, and we don't need to hardcode?
Suggested change
1. **Use a Clear and Structured PR Title**
#. **Use a clear and structured PR title**
Also please trim trailing spaces, or install pre-commit to do it for you:
https://devguide.python.org/getting-started/setup-building/#install-pre-commit

This applies to all points not just this one @swastim01

hugovk · 2025-02-09T13:30:37Z

+
+ PR titles often become commit messages, making them **critical for maintainability and searchability**. Follow these guidelines:
+
+ **Do:** 


See the preview: https://cpython-devguide--1510.org.readthedocs.build/getting-started/pull-request-lifecycle/#making-good-prs
Don't blockquote this. Same for "Avoid".

…ling spaces using pre-commit, removed blockquotes

JelleZijlstra · 2025-02-09T17:03:41Z

- your pull request will be put on hold until you fix the formatting issues.
+When creating a pull request, following best practices ensures your contribution is **clear, maintainable, and easy to review**. A well-structured PR improves collaboration and speeds up the review process.
+
+1. **Use a Clear and Structured PR Title**


This is general guidance, not specific to Python. I'm not sure it makes sense to give this sort of general guideline: the devguide is more helpful to developers who want to start contributing to Python if it talks specifically about what's special about this project.

StanFromIreland · 2025-02-10T20:45:12Z

+ **Do:**
+
+ - Clearly summarize the change in a concise manner.
+ - Use the **imperative mood** (e.g., "Fix crash in parser" instead of "Fixed a crash in parser").


Maybe add a link to a better guide/more information? This would be helpful for non English natives. https://en.wikipedia.org/wiki/Imperative_mood

StanFromIreland · 2025-02-10T20:48:37Z

- Pull requests with only code formatting changes are usually rejected. On
- the other hand, fixes for typos and grammar errors in documents and
- docstrings are welcome.


Why remove this note and replace it with a shorter one?

StanFromIreland · 2025-02-10T20:58:56Z

 See `the merge command's documentation <https://git-scm.com/docs/git-merge>`_
 for a detailed technical explanation.

-


Accidentally removed line

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

python-cla-bot · 2025-04-18T09:56:08Z

The following commit authors need to sign the Contributor License Agreement:

140950062+swastim01@users.noreply.github.com

Moved 'Making Good PRs' section up in the hierarchy and clarified its…
a99729e
… content

Reversed the doc hierarchy as it was before
38a16d6

swastim01 changed the title ~~Moved 'Making Good PRs' section up in the hierarchy and clarified its content~~Improved 'Making Good PRs' section to improve clarity and maintainability.Feb 9, 2025

hugovk reviewed Feb 9, 2025
View reviewed changes

Improved capitalization, added #. instead of hardcoding, trimmed trai…
0cdb96a
…ling spaces using pre-commit, removed blockquotes

JelleZijlstra reviewed Feb 9, 2025
View reviewed changes

StanFromIreland reviewed Feb 10, 2025
View reviewed changes

swastim01and others added 7 commits February 12, 2025 13:41

Update getting-started/pull-request-lifecycle.rst
5932e90
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

Update getting-started/pull-request-lifecycle.rst
1c12ebd
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

Update getting-started/pull-request-lifecycle.rst
980bac0
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

Update getting-started/pull-request-lifecycle.rst
bd58b77
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

Update getting-started/pull-request-lifecycle.rst
e43ccdf
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

Update getting-started/pull-request-lifecycle.rst
d36d02e
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

Update getting-started/pull-request-lifecycle.rst
057d5b4
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

AA-Turner mentioned this pull request Aug 7, 2025
Improve the "Making Good PRs" section #931
Open

sirosen mentioned this pull request Jun 26, 2026
Add a section to the PR guide on how to write good titles and descriptions #1845
Open

	1. Use a Clear and Structured PR Title
	#. Use a clear and structured PR title


		PR titles often become commit messages, making them critical for maintainability and searchability. Follow these guidelines:

		Do:

		See `the merge command's documentation <https://git-scm.com/docs/git-merge>`_
		for a detailed technical explanation.

Uh oh!

Uh oh!

Conversation

swastim01 commented Feb 9, 2025• edited by hugovk Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Improve PR Title Guidelines

Solves: #931

Description

Uh oh!

ghost commented Feb 9, 2025• edited by ghost Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hugovk commented Feb 9, 2025• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

swastim01 commented Feb 9, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

python-cla-botBot commented Apr 18, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

swastim01 commented Feb 9, 2025•
edited by hugovk
Loading

ghost commented Feb 9, 2025•
edited by ghost
Loading

hugovk commented Feb 9, 2025•
edited
Loading