NotificationsYou must be signed in to change notification settings
Fork851
Star1.9k

Improved 'Making Good PRs' section to improve clarity and maintainability.#1510

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.

By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Jump to bottom

Open

swastim01 wants to merge10 commits intopython:main

base:main

Choose a base branch

fromswastim01:improve-doc-hierarchy

Open

Improved 'Making Good PRs' section to improve clarity and maintainability.#1510

swastim01 wants to merge10 commits intopython:mainfromswastim01:improve-doc-hierarchy

Conversation

Copy link

swastim01 commentedFeb 9, 2025•
edited by hugovk
Loading

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/

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

a99729e

… content

Copy link

ghost commentedFeb 9, 2025•
edited by ghost
Loading

All commit authors signed the Contributor License Agreement.

Copy link

Member

hugovk commentedFeb 9, 2025•
edited
Loading

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.)

Reversed the doc hierarchy as it was before

38a16d6

Copy link

Author

swastim01 commentedFeb 9, 2025

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

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

getting-started/pull-request-lifecycle.rst

		.. _good-prs:

		Makinggood PRs
		MakingGood PRs

Copy link

Member

Choose a reason for hiding this comment

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

Please retain sentence case:https://devguide.python.org/documentation/style-guide/#capitalization

Suggested change

	MakingGood PRs
	Makinggood PRs

Same applies to the headers below.

getting-started/pull-request-lifecycle.rst Outdated

		#. 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

Copy link

Member

Choose a reason for hiding this comment

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

Can we keep using#. so Sphinx auto-numbers, and we don't need to hardcode?

Suggested change

	1. Use aClear andStructured PRTitle
	#. Use aclear andstructured PRtitle

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

Copy link

Contributor

Choose a reason for hiding this comment

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

This applies to all points not just this one@swastim01

getting-started/pull-request-lifecycle.rst Outdated


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

		Do:

Copy link

Member

Choose a reason for hiding this comment

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

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".

Improved capitalization, added #. instead of hardcoding, trimmed trai…

0cdb96a

…ling spaces using pre-commit, removed blockquotes

JelleZijlstra reviewed

Feb 9, 2025

View reviewed changes

getting-started/pull-request-lifecycle.rst

		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

Copy link

Member

Choose a reason for hiding this comment

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

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 reviewed

Feb 10, 2025

View reviewed changes

getting-started/pull-request-lifecycle.rst OutdatedShow resolvedHide resolved

getting-started/pull-request-lifecycle.rst

		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").

Copy link

Contributor

StanFromIrelandFeb 10, 2025

Choose a reason for hiding this comment

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

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

getting-started/pull-request-lifecycle.rst OutdatedShow resolvedHide resolved

getting-started/pull-request-lifecycle.rst

Comment on lines -212 to -214

		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.

Copy link

Contributor

StanFromIrelandFeb 10, 2025

Choose a reason for hiding this comment

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

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

getting-started/pull-request-lifecycle.rst OutdatedShow resolvedHide resolved

getting-started/pull-request-lifecycle.rst

		@@ -183,59 +183,93 @@ message. It is usually okay to leave that as-is and close the editor.
		See `the merge command's documentation <https://git-scm.com/docs/git-merge>`_
		for a detailed technical explanation.

Copy link

Contributor

StanFromIrelandFeb 10, 2025

Choose a reason for hiding this comment

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

Accidentally removed line

getting-started/pull-request-lifecycle.rst OutdatedShow resolvedHide resolved

swastim01and others added7 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>

Copy link

python-cla-botbot commentedApr 18, 2025

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

140950062+swastim01@users.noreply.github.com

Labels

None yet

4 participants

Movatterモバイル変換

Uh oh!

Improved 'Making Good PRs' section to improve clarity and maintainability.#1510

Are you sure you want to change the base?

Improved 'Making Good PRs' section to improve clarity and maintainability.#1510

Uh oh!

Conversation

swastim01 commentedFeb 9, 2025• edited by hugovkLoading Uh oh!There was an error while loading.Please reload this page.

Uh oh!

Improve PR Title Guidelines

Solves:#931

Description

Uh oh!

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

Uh oh!

Uh oh!

hugovk commentedFeb 9, 2025• editedLoading Uh oh!There was an error while loading.Please reload this page.

Uh oh!

Uh oh!

swastim01 commentedFeb 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 commentedApr 18, 2025

Uh oh!

Uh oh!

swastim01 commentedFeb 9, 2025•
edited by hugovk
Loading

ghost commentedFeb 9, 2025•
edited by ghost
Loading

hugovk commentedFeb 9, 2025•
edited
Loading