(arrow) branch main updated: GH-49675: [Docs] Make "stale issues" more visible to potential contributors and document stale issue policy (#49703)

[al...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

AlenkaF pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow.git


The following commit(s) were added to refs/heads/main by this push:
     new 7190a7c6a4 GH-49675: [Docs] Make "stale issues" more visible to potential contributors and document stale issue policy (#49703)
7190a7c6a4 is described below

commit 7190a7c6a48c99179922861ec5a5fe3b10534d8d
Author: Nic Crane <th...@gmail.com>
AuthorDate: Sun Apr 19 01:40:07 2026 -0400

    GH-49675: [Docs] Make "stale issues" more visible to potential contributors and document stale issue policy (#49703)
    
    ### Rationale for this change
    
    New things in repo weren't documented
    
    ### What changes are included in this PR?
    
    Document them
    
    ### Are these changes tested?
    
    I'll check they look correct on CI
    
    ### Are there any user-facing changes?
    
    Nah
    * GitHub Issue: #49675
    
    Authored-by: Nic Crane <th...@gmail.com>
    Signed-off-by: AlenkaF <fr...@gmail.com>
---
 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 07445de2bb..307261617a 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 a76b15e917..de686269a8 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.
    <https://github.com/apache/arrow/labels/good-first-issue>`_
 
 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
+   <https://github.com/apache/arrow/labels/Status%3A%20needs%20champion>`_
+
+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.