Improved 'Making Good PRs' section to improve clarity and maintainability. #1510
Conversation
|
All commit authors signed the Contributor License Agreement. |
|
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.) |
|
Hi, I have done the needful. Please let me know if any other changes are required. |
swastim01
changed the title
| .. _good-prs: | ||
|
|
||
| Making good PRs | ||
| Making Good PRs |
There was a problem hiding this comment.
Please retain sentence case: https://devguide.python.org/documentation/style-guide/#capitalization
| Making Good PRs | |
| Making good PRs |
Same applies to the headers below.
| #. 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** |
There was a problem hiding this comment.
Can we keep using #. so Sphinx auto-numbers, and we don't need to hardcode?
| 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
There was a problem hiding this comment.
This applies to all points not just this one @swastim01
|
|
||
| PR titles often become commit messages, making them **critical for maintainability and searchability**. Follow these guidelines: | ||
|
|
||
| **Do:** |
There was a problem hiding this comment.
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
| 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** |
There was a problem hiding this comment.
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.
| **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"). |
There was a problem hiding this comment.
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
| 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. |
There was a problem hiding this comment.
Why remove this note and replace it with a shorter one?
| @@ -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. | |||
|
|
|||
|
|
|||
There was a problem hiding this comment.
Accidentally removed line
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Improve PR Title Guidelines
Solves: #931
Description
These changes aim to enhance the quality of PR titles.
📚 Documentation preview 📚: https://cpython-devguide--1510.org.readthedocs.build/getting-started/pull-request-lifecycle/