diff --git a/contrib/doc/pull-request-lifecycle.rst b/contrib/doc/pull-request-lifecycle.rst index a62e63728..68b4b861a 100644 --- a/contrib/doc/pull-request-lifecycle.rst +++ b/contrib/doc/pull-request-lifecycle.rst @@ -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 ``: `` 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! 🚀