Files
zed/script/github-community-pr-board.py
Lena 4c90ed88c3 Add more fields to the community PR board (#66617)
- Last push: the head commit's committer date, which moves with rebases
and merges from `main`.
- Merge conflicts
- Opened with no self-review: that's the `no self-review` label.

The Upvotes field now also counts comments and reviews too (and still
deduplicates per person).

The daily refresh had hit its 15-minute timeout many times so it now
fetches board items in batches of 10 (one at a time if a batch fails),
writes only values that changed, asks GitHub again for mergeability it
hasn't computed yet, and fails the run if any PR failed instead of
exiting successfully.

In `github_helpers.py`, `set_github_project_field` now handles number,
date and text fields, clears a field for `None` and can skip missing
fields. `is_staff_member` reads the staff team once per run. Requests
share one HTTP session. Rate-limited requests are retried, writes
included, as are project field writes that hit transient errors.

The refresh workflow is renamed to "Community PR Board Signals Refresh"
(also in the Slack failure notifier) for moar consistency, and it gets
members:read for the staff list.

## Testing

Ran from my machine and it worked (after two fix-ups)

Release Notes:

- N/A
2026-11-06 14:32:34 +00:00

721 lines
25 KiB
Python

#!/usr/bin/env python3
"""
Route community PRs to the correct review track on a GitHub Project board,
and surface signal fields (Size, Issue Linked, Contributor, Upvotes, Last
push, Merge conflicts, Opened with no self-review) that the board's views
can filter and sort on.
Reads the event payload dispatched by the GitHub Actions workflow and:
- On `labeled` or `reopened`: adds the PR to the board (idempotent), sets the
Track field to the most specific matching track, and recomputes signals.
- On `unlabeled`: re-resolves Track from remaining labels, or clears it
if no area/platform labels remain (PR stays on the board for visibility).
Signals are recomputed if the PR is on the board.
- On `edited`: recomputes signals if the PR is on the board (a body edit
can change which issues the PR closes).
- On `assigned`: if the assignee is a staff team member, sets Status to
"In Progress (us)".
- On `review_requested`: if current Status is "In Progress (author)",
flips it to "In Progress (us)" — the author is explicitly asking for
re-review.
- On `issue_comment.created`: if the commenter is the PR author and
current Status is "In Progress (author)", flips it to
"In Progress (us)" — the author is likely signaling they're done.
- On `workflow_dispatch` with a PR number: re-resolves Track and
recomputes signals for a manually specified PR.
- When run with REFRESH_ALL=1: walks every open PR on the board and
recomputes its signals. Used by the scheduled refresh workflow as a
belt-and-suspenders pass against changes that don't reach the
event-driven workflow (notably intentionally-unsubscribed `synchronize`
events that change Size, Last push and Merge conflicts, pushes to main
that change Merge conflicts, reactions, comments and reviews that change
Upvotes, and sidebar edits to linked issues that don't fire a PR webhook).
Review-based status changes (approved → "In Progress (us)", changes
requested → "In Progress (author)") are handled by built-in board
automations, not this script.
Signal fields are written only when their value changed, and best-effort:
if a field or option is missing from the project, the script logs and
skips it rather than failing, so new fields can be rolled out in the
project UI independently of deploys.
Requires:
requests (pip install requests)
Usage (called by the workflow, not directly):
python github-community-pr-board.py
"""
import json
import os
import sys
import time
from itertools import batched
from pathlib import Path
from github_helpers import (
add_github_project_item,
fetch_github_project,
github_graphql,
github_rest_api,
is_staff_member,
set_github_project_field,
)
REPO_OWNER = "zed-industries"
REPO_NAME = "zed"
REPO_FULL_NAME = f"{REPO_OWNER}/{REPO_NAME}"
SKIP_LABELS = {"staff", "bot"}
STATUS_IN_PROGRESS_US = "In Progress (us)"
STATUS_IN_PROGRESS_AUTHOR = (
"In Progress (author)" # set by built-in board automation, read by this script
)
MAPPING_PATH = Path(__file__).parent / "community-pr-track-mapping.json"
MERGE_CONFLICTS_FIELD = "Merge conflicts"
HAS_CONFLICTS_OPTION = "❌"
NO_SELF_REVIEW_LABEL = "no self-review"
NO_SELF_REVIEW_OPTION = "AI?"
POSITIVE_REACTIONS = {"THUMBS_UP", "HEART", "HOORAY", "ROCKET"}
BOTS_WITH_USER_ACCOUNTS = {"zed-industries-bot"}
# GitHub answers 502 to batches of 25.
BOARD_ITEMS_PER_QUERY = 10
MAX_NODE_IDS_PER_QUERY = 100
# GitHub forgets mergeability whenever main moves, and only computes it again
# once asked, so a recheck asks, waits, and reads again.
MERGEABILITY_RECHECK_DELAY_SECONDS = 15
MERGEABILITY_RECHECK_ROUNDS = 3
CONNECTION_NODE_SELECTIONS = {
"reactions": "content user { login }",
"comments": "author { __typename login }",
"reviews": "author { __typename login }",
}
# %-formatting, since every GraphQL brace would need doubling in an f-string.
BOARD_ITEM_FRAGMENT = """
fragment BoardItem on ProjectV2Item {
id
isArchived
fieldValues(first: 30) {
nodes {
... on ProjectV2ItemFieldSingleSelectValue { name field { ... on ProjectV2FieldCommon { name } } }
... on ProjectV2ItemFieldNumberValue { number field { ... on ProjectV2FieldCommon { name } } }
... on ProjectV2ItemFieldDateValue { date field { ... on ProjectV2FieldCommon { name } } }
}
}
content {
... on PullRequest {
id
number
state
additions
deletions
mergeable
author { login }
labels(first: 50) { nodes { name } }
commits(last: 1) { nodes { commit { committedDate } } }
reactions(first: 100) { nodes { %(reactions)s } pageInfo { hasNextPage endCursor } }
comments(first: 100) { nodes { %(comments)s } pageInfo { hasNextPage endCursor } }
reviews(first: 100) { nodes { %(reviews)s } pageInfo { hasNextPage endCursor } }
closingIssuesReferences(first: 20) {
nodes {
__typename
id
repository { nameWithOwner }
issueType { name }
reactions(first: 100) { nodes { %(reactions)s } pageInfo { hasNextPage endCursor } }
comments(first: 100) { nodes { %(comments)s } pageInfo { hasNextPage endCursor } }
}
}
}
}
}
""" % CONNECTION_NODE_SELECTIONS
def sync_track_from_labels(pr, project_number):
"""Sync the PR's Track field on the board with its current labels.
Returns (project, item) if the PR ends up on (or stays on) the board, so
callers can refresh its signals without fetching it again. Returns
(None, None) otherwise.
"""
pr_labels = {label["name"] for label in pr.get("labels", [])}
track_name = resolve_track(pr_labels, load_mapping())
project = fetch_github_project(project_number)
item_id = github_find_project_item_id(project["id"], pr["node_id"])
if not item_id:
if not track_name:
print(
f"No track matched for labels on PR #{pr['number']}, not on board, nothing to do"
)
return None, None
item_id = add_github_project_item(project["id"], pr["node_id"])
[item] = github_fetch_board_items([item_id])
current_track = current_field_values(item).get("Track")
# Case-insensitive like the write, since the mapping is maintained by hand.
if (current_track or "").casefold() != (track_name or "").casefold():
set_github_project_field(project, item_id, "Track", track_name)
return project, item
def set_progress_status_on_assignment(pr, assignee_login, project_number):
"""Set Status to 'In Progress (us)' when a staff member self-assigns."""
if not is_staff_member(assignee_login):
print(f"Assignee '{assignee_login}' is not a staff member, skipping")
return
project = fetch_github_project(project_number)
item_id = github_find_project_item_id(project["id"], pr["node_id"])
if not item_id:
print(f"PR #{pr['number']} not on board, skipping assignment status update")
return
set_github_project_field(project, item_id, "Status", STATUS_IN_PROGRESS_US)
def return_to_reviewer(pr, project_number, reason):
"""Flip Status from 'In Progress (author)' to 'In Progress (us)'.
Called when the author signals they're ready for re-review, either
by re-requesting review or by commenting on the PR.
"""
project = fetch_github_project(project_number)
item_id = github_find_project_item_id(project["id"], pr["node_id"])
if not item_id:
print(f"PR #{pr['number']} not on board, skipping")
return
current_status = github_get_field_value(item_id, "Status")
if current_status == STATUS_IN_PROGRESS_AUTHOR:
print(
f"{reason}, flipping status from '{current_status}' to '{STATUS_IN_PROGRESS_US}'"
)
set_github_project_field(project, item_id, "Status", STATUS_IN_PROGRESS_US)
else:
print(f"Current status is '{current_status}', not flipping ({reason})")
def compute_size_bucket(total_changes):
"""Return the size bucket label for a PR's total (additions + deletions).
Size is computed from raw additions + deletions; we don't try to strip
generated files.
"""
buckets = [(30, "XS"), (150, "S"), (400, "M"), (1000, "L")]
for threshold, name in buckets:
if total_changes < threshold:
return name
return "XL"
def compute_contributor(pr_labels):
"""Return the Contributor value derived from the PR's labels.
The auto-labeler is responsible for applying `guild`, `community champion`
and `first contribution` based on the author's membership/history; anything
else on the board is treated as a returning contributor (PRs from staff/bots
don't reach this function because they're filtered upstream).
Guild takes precedence over Champion because current-cohort guild members
are frequently also community champions, and their guild status is the more
relevant signal while the cohort is active.
"""
if "guild" in pr_labels:
return "Guild"
if "community champion" in pr_labels:
return "Champion"
if "first contribution" in pr_labels:
return "First PR"
return "Returning"
def closing_issues_in_repository(pr):
return [
issue
for issue in pr["closingIssuesReferences"]["nodes"]
if issue["repository"]["nameWithOwner"] == REPO_FULL_NAME
]
def linked_issue_type(pr):
"""Return the most significant type among the repository's issues the PR closes."""
closing_issues = closing_issues_in_repository(pr)
if not closing_issues:
return "No issue"
type_names = {
issue["issueType"]["name"]
for issue in closing_issues
if issue.get("issueType")
}
for type_name in ("Crash", "Bug", "Feature", "Docs"):
if type_name in type_names:
return type_name
print(
f"Warning: PR has {len(closing_issues)} linked issue(s) but none with "
f"a recognized type (saw: {type_names or 'no type set'})"
)
return "No issue"
def github_connection_page(subject, connection_name, cursor):
data = github_graphql(
f"""
query($id: ID!, $cursor: String!) {{
node(id: $id) {{
... on {subject['__typename']} {{
page: {connection_name}(first: 100, after: $cursor) {{
nodes {{ {CONNECTION_NODE_SELECTIONS[connection_name]} }}
pageInfo {{ hasNextPage endCursor }}
}}
}}
}}
}}
""",
{"id": subject["id"], "cursor": cursor},
)
return data["node"]["page"]
def connection_nodes(subject, connection_name):
connection = subject[connection_name]
while True:
yield from connection["nodes"]
if not connection["pageInfo"]["hasNextPage"]:
return
connection = github_connection_page(
subject, connection_name, connection["pageInfo"]["endCursor"]
)
def engaged_users(pr):
for subject in [pr, *closing_issues_in_repository(pr)]:
for reaction in connection_nodes(subject, "reactions"):
if reaction["content"] in POSITIVE_REACTIONS:
yield reaction["user"]
for comment in connection_nodes(subject, "comments"):
yield comment["author"]
for review in connection_nodes(pr, "reviews"):
yield review["author"]
def is_bot(user):
login = user["login"].lower()
return (
user.get("__typename") == "Bot"
or login.endswith("[bot]")
or login in BOTS_WITH_USER_ACCOUNTS
)
def count_interested_people(pr):
author_login = (pr["author"] or {}).get("login")
interested_logins = {
user["login"]
for user in engaged_users(pr)
if user
and user["login"] != author_login
and not is_bot(user)
and not is_staff_member(user["login"])
}
return len(interested_logins)
def merge_conflicts_value(mergeable):
return HAS_CONFLICTS_OPTION if mergeable == "CONFLICTING" else None
def compute_signals(pr):
pr_labels = {label["name"] for label in pr["labels"]["nodes"]}
signals = {
"Size": compute_size_bucket(pr["additions"] + pr["deletions"]),
"Contributor": compute_contributor(pr_labels),
"Issue Linked": linked_issue_type(pr),
# Counts people, not reactions, despite the field's name.
"Upvotes": count_interested_people(pr),
# The committer date moves with rebases and merges from main.
"Last push": pr["commits"]["nodes"][0]["commit"]["committedDate"][:10],
"Opened with no self-review": (
NO_SELF_REVIEW_OPTION if NO_SELF_REVIEW_LABEL in pr_labels else None
),
}
# Left out while GitHub is still computing mergeability, so the current value stays.
if pr["mergeable"] != "UNKNOWN":
signals[MERGE_CONFLICTS_FIELD] = merge_conflicts_value(pr["mergeable"])
return signals
def current_field_values(item):
return {
node["field"]["name"]: node.get("name", node.get("number", node.get("date")))
for node in item["fieldValues"]["nodes"]
if "field" in node
}
def write_changed_fields(project, item_id, values, current_values):
for field_name, value in values.items():
if current_values.get(field_name) != value:
set_github_project_field(
project, item_id, field_name, value, missing_ok=True
)
def refresh_signals(project, item):
pr = item["content"]
print(f"--- Refreshing signals on PR #{pr['number']} ---")
write_changed_fields(
project, item["id"], compute_signals(pr), current_field_values(item)
)
def refresh_signals_if_on_board(pr, project_number):
project = fetch_github_project(project_number)
item_id = github_find_project_item_id(project["id"], pr["node_id"])
if not item_id:
print(f"PR #{pr['number']} not on board, skipping signal refresh")
return
[item] = github_fetch_board_items([item_id])
refresh_signals(project, item)
def recheck_mergeability(project, mergeability_rechecks):
"""Write Merge conflicts on items whose mergeability was still UNKNOWN on
the first read. Returns the number of items that failed.
"""
failed = 0
pending_rechecks = mergeability_rechecks
for _ in range(MERGEABILITY_RECHECK_ROUNDS):
time.sleep(MERGEABILITY_RECHECK_DELAY_SECONDS)
still_unknown = []
for batch in batched(pending_rechecks, MAX_NODE_IDS_PER_QUERY):
try:
mergeable_by_pr_id = github_fetch_mergeable_by_pr_id(
[recheck["pr_id"] for recheck in batch]
)
except Exception as error:
print(f"Failed to re-read mergeability of {len(batch)} PR(s): {error}")
failed += len(batch)
continue
for recheck in batch:
mergeable = mergeable_by_pr_id.get(recheck["pr_id"], "UNKNOWN")
if mergeable == "UNKNOWN":
still_unknown.append(recheck)
continue
try:
write_changed_fields(
project,
recheck["item_id"],
{MERGE_CONFLICTS_FIELD: merge_conflicts_value(mergeable)},
{MERGE_CONFLICTS_FIELD: recheck["merge_conflicts"]},
)
except Exception as error:
print(f"Failed to write Merge conflicts on PR #{recheck['number']}: {error}")
failed += 1
pending_rechecks = still_unknown
if not pending_rechecks:
break
if pending_rechecks:
print(f"Mergeability still unknown for {len(pending_rechecks)} PR(s), left as they were")
return failed
def refresh_all_board_items(project_number):
"""Walk every open PR on the board and refresh its signals.
Backstop for the daily refresh workflow. A failure on one PR doesn't
stop the others, but fails the run at the end.
"""
project = fetch_github_project(project_number)
listed_items = []
skipped = 0
for item in github_list_project_items(project["id"]):
if item.get("isArchived"):
skipped += 1
continue
content = item.get("content") or {}
if content.get("__typename") != "PullRequest":
skipped += 1
continue
if content.get("state") != "OPEN" or content.get("isDraft"):
skipped += 1
continue
label_names = [label["name"] for label in content["labels"]["nodes"]]
if set(label_names) & SKIP_LABELS:
skipped += 1
continue
listed_items.append(item)
processed = failed = 0
mergeability_rechecks = []
for batch in batched(listed_items, BOARD_ITEMS_PER_QUERY):
try:
items = github_fetch_board_items([item["id"] for item in batch])
except Exception as error:
# One broken item fails the whole query, so they're fetched one by one.
print(f"Failed to fetch {len(batch)} items at once, retrying one by one: {error}")
items = [None] * len(batch)
for listed_item, item in zip(batch, items):
try:
if item is None:
[item] = github_fetch_board_items([listed_item["id"]])
pr = item["content"]
# Closed since the board was listed, and archived along with it.
if item["isArchived"] or pr["state"] != "OPEN":
skipped += 1
continue
refresh_signals(project, item)
processed += 1
if pr["mergeable"] == "UNKNOWN":
mergeability_rechecks.append({
"item_id": item["id"],
"pr_id": pr["id"],
"number": pr["number"],
"merge_conflicts": current_field_values(item).get(
MERGE_CONFLICTS_FIELD
),
})
except Exception as error:
print(f"Failed to refresh PR #{listed_item['content']['number']}: {error}")
failed += 1
if mergeability_rechecks:
failed += recheck_mergeability(project, mergeability_rechecks)
print(
f"Refresh complete: {processed} processed, {skipped} skipped, {failed} failed"
)
if failed:
raise RuntimeError(f"Failed to refresh {failed} PR(s), see above")
def load_mapping(path=MAPPING_PATH):
"""Load the Track-to-labels mapping from the JSON file."""
with open(path) as f:
data = json.load(f)
return data["tracks"]
def resolve_track(pr_labels, tracks):
"""Return the name of the most specific track matching the PR's labels.
Tracks are checked in order; the first match wins (most specific first).
"""
for track in tracks:
if pr_labels & set(track["labels"]):
return track["name"]
return None
def github_fetch_pr(pr_number):
"""Fetch a PR by number via the REST API."""
return github_rest_api("GET", f"repos/{REPO_OWNER}/{REPO_NAME}/pulls/{pr_number}")
def github_list_project_items(project_id):
"""Yield every item on a project board, paginating as needed.
Each item includes `isArchived` so callers can cheaply filter archived
items out without an extra round-trip per item.
"""
cursor = None
while True:
data = github_graphql(
"""
query($projectId: ID!, $cursor: String) {
node(id: $projectId) {
... on ProjectV2 {
items(first: 100, after: $cursor) {
pageInfo { hasNextPage endCursor }
nodes {
id
isArchived
content {
__typename
... on PullRequest {
number
state
isDraft
labels(first: 50) { nodes { name } }
}
}
}
}
}
}
}
""",
{"projectId": project_id, "cursor": cursor},
)
page = data["node"]["items"]
for item in page["nodes"]:
yield item
if not page["pageInfo"]["hasNextPage"]:
return
cursor = page["pageInfo"]["endCursor"]
def github_fetch_board_items(item_ids):
data = github_graphql(
BOARD_ITEM_FRAGMENT
+ """
query($ids: [ID!]!) {
nodes(ids: $ids) { ...BoardItem }
}
""",
{"ids": item_ids},
)
return data["nodes"]
def github_fetch_mergeable_by_pr_id(pr_ids):
data = github_graphql(
"""
query($ids: [ID!]!) {
nodes(ids: $ids) { ... on PullRequest { id mergeable } }
}
""",
{"ids": pr_ids},
partial_errors_ok=True,
)
# PRs GitHub can no longer return come back as null.
return {node["id"]: node["mergeable"] for node in data["nodes"] if node}
def github_find_project_item_id(project_id, content_node_id):
"""Find a PR's item ID on the project board, or None if not present.
Uses a read-only query so it won't add the PR as a side effect.
"""
data = github_graphql(
"""
query($contentId: ID!) {
node(id: $contentId) {
... on PullRequest {
projectItems(first: 50) {
nodes {
id
project { id }
}
}
}
}
}
""",
{"contentId": content_node_id},
)
for item in data["node"]["projectItems"]["nodes"]:
if item["project"]["id"] == project_id:
return item["id"]
return None
def github_get_field_value(item_id, field_name):
"""Read the current value of a single-select field on a project item."""
data = github_graphql(
"""
query($itemId: ID!) {
node(id: $itemId) {
... on ProjectV2Item {
fieldValues(first: 20) {
nodes {
... on ProjectV2ItemFieldSingleSelectValue {
field { ... on ProjectV2SingleSelectField { name } }
name
}
}
}
}
}
}
""",
{"itemId": item_id},
)
for field_value in data["node"]["fieldValues"]["nodes"]:
if field_value.get("field", {}).get("name") == field_name:
return field_value.get("name")
return None
if __name__ == "__main__":
project_number = int(os.environ["PROJECT_NUMBER"])
if os.environ.get("REFRESH_ALL") == "1":
refresh_all_board_items(project_number)
sys.exit(0)
manual_pr_number = os.environ.get("MANUAL_PR_NUMBER")
if manual_pr_number:
pr = github_fetch_pr(manual_pr_number)
action = "labeled"
event = {}
print(f"Manual dispatch for PR #{manual_pr_number}")
else:
event_name = os.environ["GITHUB_EVENT_NAME"]
with open(os.environ["GITHUB_EVENT_PATH"]) as f:
event = json.load(f)
if event_name in ("pull_request", "pull_request_target"):
pr = event["pull_request"]
action = event["action"]
elif event_name == "issue_comment":
issue = event["issue"]
if "pull_request" not in issue:
print("Comment is on an issue, not a PR, skipping")
sys.exit(0)
commenter = event["comment"]["user"]["login"]
pr_author = issue["user"]["login"]
if commenter != pr_author:
print(
f"Commenter '{commenter}' is not PR author '{pr_author}', skipping"
)
sys.exit(0)
pr = github_fetch_pr(issue["number"])
action = "author_commented"
else:
print(f"Unexpected event: {event_name}")
sys.exit(0)
pr_labels = {label["name"] for label in pr.get("labels", [])}
if pr_labels & SKIP_LABELS:
print(f"Skipping PR #{pr['number']} (has {pr_labels & SKIP_LABELS} label)")
sys.exit(0)
if pr.get("draft"):
print(f"Skipping draft PR #{pr['number']}")
sys.exit(0)
if pr.get("state") != "open":
print(f"Skipping PR #{pr['number']} (state: {pr.get('state')})")
sys.exit(0)
print(f"Processing PR #{pr['number']}: action={action}")
if action in ("labeled", "unlabeled", "reopened"):
project, item = sync_track_from_labels(pr, project_number)
if item:
refresh_signals(project, item)
elif action == "assigned":
assignee_login = event.get("assignee", {}).get("login")
if not assignee_login:
print("No assignee login in event payload, skipping")
else:
set_progress_status_on_assignment(pr, assignee_login, project_number)
elif action == "review_requested":
return_to_reviewer(pr, project_number, "Author re-requested review")
elif action == "author_commented":
return_to_reviewer(pr, project_number, "Author commented on PR")
elif action == "edited":
refresh_signals_if_on_board(pr, project_number)
else:
print(f"Ignoring action: {action}")