Skip to content

GH-931: Improve "Making Good PRs" docs with title guidelines and structure #1521

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’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

GH-931: Improve "Making Good PRs" docs with title guidelines and structure #1521

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
33 changes: 23 additions & 10 deletions contrib/doc/pull-request-lifecycle.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,18 +4,31 @@
Pull request lifecycle
======================

.. important::

|draft|
Making Good Pull Requests
=========================

|purpose|
- **Title Format**: Use a concise, imperative verb phrase (e.g., "Fix typo in setup guide", not "Fixed typo").
- Start with a verb (e.g., "Add", "Fix", "Improve").
- Avoid vague terms like "Update" or "Change".
- Include an issue reference (e.g., "GH-123: Fix ...").
- **Description**: Explain the **what**, **why**, and **how**.
- Reference related issues using ``GH-123`` or ``bpo-456``.
- For complex changes, add a "Rationale" subsection.

**Example:**
**Good Title**: "GH-931: Enforce imperative tense in PR titles"
**Bad Title**: "Updating docs"

[Details of pull requests for documentation contributions. The existing
:ref:`pull-request-lifecycle` page is long and includes many details.
Some only apply to code contributions, but many are common to all
contributions. Should we keep a common page, with documentation tweaks here, or
should this page have only the documentation details even if they are duplicated
elsewhere?]
**Here is a checklist for contributors before submitting a PR**

[See :ref:`code-pull-request-lifecycle` for the code half of this conundrum.]
Before submitting a PR:
- [ ] Title follows the ``<Verb>: <Concise Summary>`` format.
- [ ] Description explains the **purpose** and **impact**.
- [ ] Linked to relevant issues (e.g., "Closes GH-123").
- [ ] Tests or documentation updated (if applicable).

.. warning::
Poorly titled PRs may be rejected or delayed. Maintainers rely on clear titles to track changes in the project’s history.

Keep calm and code on! 🚀
Loading