diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml index ab8538ee4..4b1d88370 100644 --- a/.github/workflows/stale.yml +++ b/.github/workflows/stale.yml @@ -13,7 +13,8 @@ jobs: stale: runs-on: ubuntu-latest steps: - - uses: actions/stale@v10 + # Pinned from actions/stale@v10; update deliberately when refreshing the policy. + - uses: actions/stale@eb5cf3af3ac0a1aa4c9c45633dd1ae542a27a899 with: days-before-stale: 14 days-before-close: 7 @@ -28,7 +29,7 @@ jobs: you can share the requested information. stale-issue-label: 'stale' only-labels: 'needs-info' - exempt-issue-labels: 'pinned,keep-open,bug,security' + exempt-issue-labels: 'pinned,keep-open,release-blocker,security' # Don't touch PRs — `actions/stale` defaults can be aggressive # there. We only want it for `needs-info` issues. days-before-pr-stale: -1 diff --git a/docs/ISSUE_TRIAGE.md b/docs/ISSUE_TRIAGE.md new file mode 100644 index 000000000..2b4126780 --- /dev/null +++ b/docs/ISSUE_TRIAGE.md @@ -0,0 +1,69 @@ +# Issue Triage + +## Stale `needs-info` cleanup + +The stale workflow only acts on issues that a maintainer has explicitly labeled +`needs-info`. This keeps old roadmap, release, security, and current milestone +work out of automatic cleanup unless a maintainer first marks the issue as +waiting on reporter input. + +Required labels: + +- `needs-info`: waiting on reporter information or current-version reproduction details. +- `stale`: inactive `needs-info` issue pending automatic closure. +- `keep-open`: protected because maintainers intentionally keep it open. +- `pinned`: protected maintainer issue. + +Protected labels for stale cleanup: + +- `pinned` +- `keep-open` +- `release-blocker` +- `security` + +A `bug` issue is not protected just because it is a bug. If a maintainer has +also labeled it `needs-info`, it is eligible for stale warning and closure +unless one of the protected labels above is present. + +## Dry-run queries + +Run these before changing stale policy or doing a manual cleanup pass: + +```sh +STALE_CUTOFF=$(python3 -c 'from datetime import date, timedelta; print(date.today() - timedelta(days=45))') +NEEDS_INFO_CUTOFF=$(python3 -c 'from datetime import date, timedelta; print(date.today() - timedelta(days=30))') + +gh issue list --repo Hmbown/CodeWhale --state open \ + --search "updated:<${STALE_CUTOFF}" \ + --limit 100 \ + --json number,title,updatedAt,labels,url + +gh issue list --repo Hmbown/CodeWhale --state open \ + --search "label:needs-info updated:<${NEEDS_INFO_CUTOFF}" \ + --limit 100 \ + --json number,title,updatedAt,labels,url + +gh issue list --repo Hmbown/CodeWhale --state open \ + --search "created:<${STALE_CUTOFF} comments:0 -label:keep-open -label:release-blocker -label:security" \ + --limit 100 \ + --json number,title,createdAt,updatedAt,labels,url +``` + +Use `updatedAt`, labels, and current release relevance as the closure basis. +Creation date alone is too aggressive. + +## First cleanup pass + +Before relying on automation, perform one manual pass: + +- Label unresolved old bug reports as `needs-info` only after asking for + current-version reproduction details. +- Close obvious GUI, VS Code, and web UI duplicates with links to canonical + desktop/runtime issues. +- Close old brand-discussion issues as superseded when the CodeWhale rebrand + and README/history work already covers them. +- Protect intentional v0.9.0 roadmap shards with `keep-open` or close them as + superseded by a canonical epic. + +Do not close release blockers, security issues, or active milestone work from +stale automation alone.