chore: updating the classification of PR's via updated labels Signed-off-by: Peter Staar <taa@zurich.ibm.com>
Maintainer tools
Tools that give maintainers an overview of the open GitHub PRs, and act on them
with their own gh login.
Requirements:
- The GitHub CLI, logged in with
gh auth login. - Write access to the repository for the actions (comments, CI approval).
- The dev dependencies, which
uv runinstalls by default. The script needstqdm.
Run the tools from the repository root.
sync_prs.py
Rank the open PRs by how close they are to a merge.
uv run python scripts/tools/sync_prs.py # rank only
uv run python scripts/tools/sync_prs.py --comment-conflicts # comment on conflicts
uv run python scripts/tools/sync_prs.py --approve-ci # approve safe CI runs
uv run python scripts/tools/sync_prs.py --open-ci-greens-in-tabs
uv run python scripts/tools/sync_prs.py --pr 960 --pr 963 # only these PRs
uv run python scripts/tools/sync_prs.py --label doclang # only PRs with this label
Use -h to see all options and their defaults.
While it runs, the script shows status lines (▸ ...) and progress bars
with the PR that it reads, on stderr. The report goes to stdout, so
> report.md gives a clean Markdown file. Use --quiet to turn off the
status lines and progress bars.
Filter by label
Use --label to keep only the PRs with a label. In this repository, the format
labels are doclang and doctags. Other formats, such as Markdown, HTML, and
LaTeX, share the label serialization. Any other label also works.
- If you repeat
--label, a PR needs one of the labels, not all of them. - GitHub applies the filter, so
--limitcounts only the matching PRs. - The actions apply only to the matching PRs.
- A label that does not exist gives an empty report, not an error.
- You cannot use
--labeltogether with--pr. -hlists all labels. This is a fixed list in the script. UpdateLABELS_HELPwhen the repository labels change.
Output
The script prints four lists:
- Ready to merge: CI is green, the PR has all the approvals it needs, and
GitHub reports the merge state
CLEAN. - CI green, needs approval: the PR needs at least one more approval.
- Merge conflict: the PR conflicts with its base branch.
- Other: drafts, failing or running CI, CI that waits for a maintainer, changes requested, and PRs that GitHub blocks for another reason (for example, unresolved review threads).
Each entry shows the reason, for example 1/2 approvals, needs 1 more or
CI failed: lint-and-type.
The script also saves the metadata of each PR to
.cache/prs/<number>/pr.json: labels, approvers, checks, merge state, changed
file paths, and the computed rank. It does not download PR code. The folder
.cache/ is in .gitignore.
Rules
-
CI is green: every required status check of the base branch is present, and every check is complete with
SUCCESS,SKIPPED, orNEUTRAL. TheMergify Merge Protectionscheck is not part of CI, because it also counts approvals. -
Approvals needed: the highest value of these rules:
- the branch ruleset of the base branch (1 for
main), - 2 if the PR changes files in
tests(from.github/mergify.yml).
Only approvals from owners, members, and collaborators count.
- the branch ruleset of the base branch (1 for
Actions
All actions are off by default. Without a flag, the script only reads from GitHub.
--comment-conflicts
Posts a comment on each PR in the merge-conflict list. The comment asks the author to rebase on the base branch and shows the git commands.
The script reads the comments of every PR with a merge conflict, also without this flag. The conflict list shows the state of the notification:
| State | Meaning | With --comment-conflicts |
|---|---|---|
not notified |
No notification from the script yet. | Posts a comment. |
notified 3 h ago, last comment |
Our notification is the last comment. | Skips the PR. |
notified 3 d ago, new comments since |
Somebody commented after the notification, but the author did not push. | Skips the PR. |
..., author pushed since |
The author pushed after the notification, and the conflict is still there. | Posts a comment (if ours is not the last comment). |
A hidden marker in the comment (<!-- sync-prs:merge-conflict head=... -->)
identifies the notification and records the PR head commit. Only PR
conversation comments count, not review comments.
--approve-ci
GitHub holds the pull_request runs of fork PRs with the conclusion
action_required until a maintainer approves them. This flag approves these
runs only when all of these conditions are true:
- The PR is not a draft.
- The PR has the label
ai:ci-safeand notai:ci-needs-care. - The run is for the current head commit of the PR.
- The label
ai:ci-safewas added after GitHub created the run. This makes sure that the AI triage saw the commit that the run tests.
Without the flag, the script lists the runs that it would approve.
The label ai:ci-safe is advisory. See
.github/AI_TRIAGE.md.
--open-ci-greens-in-tabs
Opens a new Google Chrome window with a tab for each open PR with green CI. Your other Chrome windows stay as they are. The order is: ready to merge, then needs approval, then the rest (for example, PRs with a merge conflict or with changes requested).
The script starts Chrome with the flag --new-window:
- On macOS:
open -na "Google Chrome" --args --new-window <urls>. - On other systems: the first of
google-chrome,google-chrome-stable,chromium,chromium-browser, orchromeonPATH.
Use --limit or --pr to open fewer tabs.
Limits
- The script reads the 100 most recently updated open PRs by default. If the
repository has more, use a larger
--limit. - The script reads at most 100 changed files per PR. If a larger PR changes
testsonly after the first 100 files, the script reports 1 required approval instead of 2. - The script does not read review threads. A PR with enough approvals and
merge state
BLOCKEDgoes to "Other". Check it on GitHub. - GitHub computes mergeability on demand. If GitHub still reports
UNKNOWNafter one retry, the PR goes to "Other". Run the script again.