Pull Request Lifecycle Policy

.. _pr_lifecycle_policy:

Pull Request Lifecycle Policy #############################

This policy keeps the open pull request list focused on contributions that are actively progressing and have a realistic path to merge.

Goals

---

• Keep open pull requests manageable for contributors and maintainers.
• Prioritize review bandwidth for changes that are moving forward.
• Provide clear expectations for draft pull requests and inactive pull requests.

Scope

---

This policy applies to all pull requests in the repository, including draft pull requests.

Definitions

---

Active pull request A pull request with meaningful progress such as commits, review responses, or updates addressing requested changes.

Draft pull request A pull request opened for work in progress and early feedback.

Stalled pull request A pull request without meaningful activity inside the inactivity window.

Closed inactive pull request A pull request closed due to inactivity, supersession, or no clear merge path.

Draft Pull Request Expectations

---

• Draft pull requests should include a clear problem statement, current status, and known gaps.
• Draft pull requests should move to ready-for-review within 30 days.
• If a draft pull request is inactive for 30 days, it may be marked stale and a reminder is posted.
• If there is no meaningful progress for 7 additional days after stale notice, the pull request may be closed.

Ready-for-Review Pull Request Expectations

---

• Authors should respond to review feedback within 21 days.
• If a ready pull request has no meaningful activity for 30 days, it may be marked stale.
• If no meaningful update is made within 7 days after stale notice, the pull request may be closed.
• Pull requests with unresolved blocking feedback for more than 45 days may be closed if no concrete plan is provided.

What Counts as Meaningful Activity

---

Examples of meaningful activity include:

• New commits that address review feedback.
• Concrete technical responses and follow-up updates.
• Significant revision updates that materially change the pull request.

Examples that typically do not count as meaningful activity include:

• Ping-only comments with no technical update.
• Trivial rebases with no substantive change.

Exceptions

---

The following pull requests may be exempt from automatic inactive closure:

• Security-critical fixes.
• Release blockers.
• Pull requests explicitly waiting on an external dependency with a linked tracking item.

Exempt pull requests still need a status update at least every 30 days.

Superseded Pull Requests

---

When work is replaced by another pull request:

• Close the old pull request as superseded.
• Link the replacement pull request.
• Add a short summary comment preserving context.

Reopening Closed Inactive Pull Requests

---

Closing a pull request due to inactivity is an administrative step to keep the open list manageable. It is not a rejection of the contribution.

Closed inactive pull requests may be reopened when:

• The author posts an updated plan.
• Prior blocking feedback is addressed.
• Maintainers confirm that review can continue.

Contributors are encouraged to reopen at any time when they can provide meaningful updates.

Responsibilities

---

Contributors are expected to:

• Keep pull request descriptions up to date.
• Respond to review comments in a timely manner.
• Move draft pull requests to ready-for-review once they are reviewable.

Consult with the :ref:contributor expectations <contributor-expectations> document for additional guidance.

Maintainers are expected to:

• Apply stale and closure decisions consistently.
• Provide clear blocking feedback.
• Close with explicit rationale and a reopen path.

Consult with the :ref:maintainer responsibilities <maintainer> document for additional guidance.