diff --git a/org-tools/triage/README.md b/org-tools/triage/README.md index 790a967..75f4ad1 100644 --- a/org-tools/triage/README.md +++ b/org-tools/triage/README.md @@ -1,6 +1,6 @@ # Central PR Triage Tool -This tool automatically applies the `status:needs-triage` label to eligible Pull Requests (PRs) across multiple repositories in your organization. It is designed to run centrally as a cron job. +This tool automatically applies the `status:needs-triage` label to eligible Pull Requests (PRs) and marks blocked PRs as `status:stale` if they have been blocked for more than 30 days. It is designed to run centrally as a cron job. --- @@ -15,11 +15,16 @@ The tool consists of a CLI entry point ([triage_cli.py](scripts/triage_cli.py)) - **Single PR Mode**: If `--pr` is specified, the tool fetches the specific PR from the target `--repos` (which must contain exactly one repository) and triages it. - **Bulk Mode**: If `--pr` is not specified, the tool enters bulk triage mode. 3. **Upfront Access Pre-Check (Bulk Mode)**: Iterates through the list of `--repos` and verifies API access for each. If any repository is inaccessible (e.g., 404 or 403), the run is aborted immediately. -4. **Candidate PR Query (Bulk Mode)**: Queries the GitHub Search API for open, non-draft PRs in the target repositories that do not have `status:needs-triage` or skip labels (`status:backlog`/`status:stale`/`status:under-review`). +4. **Candidate PR Query (Bulk Mode)**: Queries the GitHub Search API for: + - Open, non-draft PRs in the target repositories with no labels. + - Open, non-draft PRs with `status:blocked` label. + - Open, non-draft PRs with `status:under-review` label. + - Open, non-draft PRs with `status:stale` label. + - Open, non-draft PRs with `status:stale-review` label. 5. **Core Triage Loop**: For each candidate PR, the tool: - Fetches its live state from the GitHub API. - Evaluates the PR against the **Core Triage Rules**. - - Applies the `status:needs-triage` label if eligible (or logs the would-be action if running in dry-run mode). + - Applies or removes status labels (e.g., `status:needs-triage`, `status:stale`, `status:stale-review`, `status:under-review`) if eligible based on the triage and recovery rules (or logs the would-be action if running in dry-run mode). ### Key Features @@ -31,18 +36,65 @@ The tool consists of a CLI entry point ([triage_cli.py](scripts/triage_cli.py)) ## Core Triage Rules -When evaluating a PR (either in bulk or single-PR mode), the tool fetches the live state of the PR from GitHub and applies the following rules: +When evaluating a PR (either in bulk or single-PR mode), the tool applies the following rules: -| PR State | Has Target Label (`status:needs-triage`) | Has Skip Label (`status:backlog`/`status:stale`/`status:under-review`) | Action | Log Message / Reason | -| :--------- | :--------------------------------------: | :--------------------------------------------------------------------: | :-------: | :---------------------------------------------------------------- | -| **Closed** | Any | Any | **Skip** | `Skipping: PR # is closed (not open).` | -| **Draft** | Any | Any | **Skip** | `Skipping: PR # is a draft.` | -| **Open** | Yes | Any | **Skip** | `Skipping: PR # already has 'status:needs-triage' label.` | -| **Open** | No | Yes | **Skip** | `Skipping: PR # has skip label '