From 4b428d6f253b084830b4451ca3404150d7dd6b8b Mon Sep 17 00:00:00 2001 From: Nic Crane Date: Fri, 10 Apr 2026 15:42:27 +0100 Subject: [PATCH] Update docs to mention issue policy and needs champion --- docs/source/developers/bug_reports.rst | 31 +++++++++++++++++++ .../guide/step_by_step/finding_issues.rst | 13 +++++++- 2 files changed, 43 insertions(+), 1 deletion(-) diff --git a/docs/source/developers/bug_reports.rst b/docs/source/developers/bug_reports.rst index 07445de2bbda..307261617acc 100644 --- a/docs/source/developers/bug_reports.rst +++ b/docs/source/developers/bug_reports.rst @@ -206,6 +206,37 @@ reached a terminal status, it is closed with one of two outcomes: * **closed as not planned** - indicates the issue is closed and should not receive any further updates, but *without* action being taken. +.. _stale-issues: + +Stale issues and pull requests +++++++++++++++++++++++++++++++ + +To keep the issue tracker manageable, issues and pull requests that have had +no activity for an extended period are automatically marked as stale by a +daily GitHub Actions workflow. + +The policy varies by type: + +* **Pull requests**: After 365 days of inactivity, a ``Status: stale-warning`` + label is added. If there is still no activity after 14 more days, the PR is + closed. +* **Usage issues** (labeled ``Type: usage``): Same 365 + 14 day policy as + pull requests. +* **Enhancement issues** (labeled ``Type: enhancement``): Same 365 + 14 day + policy, but issues labeled ``Status: needs champion`` are exempt from + closure. This label indicates that the enhancement is still desired but + needs someone to take ownership of it. + +To prevent an issue or PR from being closed, remove the +``Status: stale-warning`` label or leave a comment explaining that it is +still active. + +.. seealso:: + + If you are looking for issues to work on, issues labeled + ``Status: needs champion`` are confirmed-wanted enhancements that need + a contributor. See :ref:`finding-issues` for more. + .. _issue-assignment: Issue assignment diff --git a/docs/source/developers/guide/step_by_step/finding_issues.rst b/docs/source/developers/guide/step_by_step/finding_issues.rst index a76b15e917e9..de686269a885 100644 --- a/docs/source/developers/guide/step_by_step/finding_issues.rst +++ b/docs/source/developers/guide/step_by_step/finding_issues.rst @@ -59,7 +59,18 @@ GitHub issues. `_ The issues labeled as good first issues should take no more than two days or -a weekend to fix them. Once you dig into the code you may find that the issue +a weekend to fix them. + +Another way to find issues is to look for the **"Status: needs champion"** +label. These are enhancement requests that the community has confirmed are +still wanted, but that have no current owner. They may be more complex than +good first issues, but they are a great way to make a meaningful contribution. + +.. seealso:: + Search for needs champion issues `needs champion label listing + `_ + +Once you dig into the code you may find that the issue is not easy at all - this can happen as the problem could be harder than the person who triaged the ticket expected it to be. Don't hesitate to write that in the comments.