Files
carbon-lang/github_tools/check_dependent_pr.py
T
Chandler Carruth b7ea32c3a4 Support re-checking, overriding, and requiring the PR dependency check (#8120)
There are a world of reasons why the dependent state check can be wrong
or get stuck. We need ways to manually override inaccurate findings or
trigger a re-check when things change.

Overriding: removing the `dependent` label causes the job to run and
immediately report success to unblock merging. The `workflow_dispatch`
can also run with an `override` mode. This requires adding more tracked
state in the form of _ignored_ PRs that would otherwise be considered
dependencies.

Re-checking: the job now makes the status have a `Details` link that can
be used to re-run it, and editing the PR description also re-runs it.
However, adding the `dependent` label or doing an explicit
`workflow_dispatch` with mode `recheck` goes further: it drops any
overrides and recomputes the open dependencies from the current commits,
keeping the record of merged dependencies.

Hiding the comment still clears _all_ of the tracked state for the PR,
so the next check starts completely from scratch.

Lastly, this extends the workflow to support being marked as required by
letting it run in the merge queue and report success.

Works to keep the changes to `_process_pr` organized so that we first
collect and analyze the state, and only at the end mutate the PR's state
to the new configuration. Adds relevant unit tests for the new features.
Also added some basic documentation of this so that folks have a
reference when it has issues.

I considered the alternative of parsing mentions out of comments
(dependabot-style), but it ended up significantly more complicated and
brittle, so instead went with basing each change on an operation on the
PR that is already mechanically available.

Assisted-by: Antigravity with Opus
2026-11-13 05:19:44 +00:00

737 lines
23 KiB
Python
Executable File

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.12"
# dependencies = [
# "gql==2.0.0",
# "requests",
# "types-requests",
# ]
# ///
"""Check if a PR depends on other open PRs based on shared commits.
Usage examples:
# Check a specific PR in dry-run mode:
GITHUB_ACCESS_TOKEN=$(gh auth token) \
./github_tools/check_dependent_pr.py --pr-number <PR_NUMBER> --dry-run
# Force a fresh check or override open dependencies:
GITHUB_ACCESS_TOKEN=$(gh auth token) \
./github_tools/check_dependent_pr.py --pr-number <PR_NUMBER> --recheck
GITHUB_ACCESS_TOKEN=$(gh auth token) \
./github_tools/check_dependent_pr.py --pr-number <PR_NUMBER> --override
# Scan all dependent PRs in dry-run mode:
GITHUB_ACCESS_TOKEN=$(gh auth token) \
./github_tools/check_dependent_pr.py --scan --dry-run
"""
__copyright__ = """
Part of the Carbon Language project, under the Apache License v2.0 with LLVM
Exceptions. See /LICENSE for license information.
SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
"""
import argparse
import datetime
import json
import os
import re
import sys
from typing import Any, Optional
import requests
try:
from github_tools import github_helpers
except ImportError:
import github_helpers # type: ignore
_DOCS_URL = (
"https://github.com/carbon-language/carbon-lang/blob/trunk/"
"docs/project/pull_request_workflow.md#dependent-pull-requests"
)
# Queries
_QUERY_OPEN_PRS = """
{
repository(owner: "carbon-language", name: "carbon-lang") {
pullRequests(states: OPEN, first: 100%(cursor)s) {
nodes {
number
headRefOid
commits(first: 100) {
nodes {
commit {
oid
}
}
}
}
%(pagination)s
}
}
}
"""
_QUERY_DEPENDENT_PRS = """
{
repository(owner: "carbon-language", name: "carbon-lang") {
pullRequests(states: OPEN, labels: ["dependent"], first: 100%(cursor)s) {
nodes {
number
}
%(pagination)s
}
}
}
"""
_QUERY_PR_DETAILS = """
query GetPrDetails($prNumber: Int!) {
repository(owner: "carbon-language", name: "carbon-lang") {
pullRequest(number: $prNumber) {
id
headRefOid
labels(first: 100) {
nodes {
name
id
}
}
commits(first: 100) {
nodes {
commit {
oid
}
}
}
comments(first: 100) {
nodes {
id
body
isMinimized
}
}
}
}
}
"""
_QUERY_LABEL = """
{
repository(owner: "carbon-language", name: "carbon-lang") {
label(name: "dependent") {
id
}
}
}
"""
_QUERY_MAX_MERGED_PR = """
{
repository(owner: "carbon-language", name: "carbon-lang") {
pullRequests(
states: MERGED
orderBy: {field: CREATED_AT, direction: DESC}
first: 1
) {
nodes {
number
}
}
}
}
"""
_MUTATION_ADD_LABEL = """
mutation AddLabel($labelableId: ID!, $labelIds: [ID!]!) {
addLabelsToLabelable(
input: {labelableId: $labelableId, labelIds: $labelIds}
) {
clientMutationId
}
}
"""
_MUTATION_REMOVE_LABEL = """
mutation RemoveLabel($labelableId: ID!, $labelIds: [ID!]!) {
removeLabelsFromLabelable(
input: {labelableId: $labelableId, labelIds: $labelIds}
) {
clientMutationId
}
}
"""
_MUTATION_UPDATE_COMMENT = """
mutation UpdateComment($id: ID!, $body: String!) {
updateIssueComment(input: {id: $id, body: $body}) {
clientMutationId
}
}
"""
_MUTATION_ADD_COMMENT = """
mutation AddComment($subjectId: ID!, $body: String!) {
addComment(input: {subjectId: $subjectId, body: $body}) {
clientMutationId
}
}
"""
def _print_err(*args: Any, **kwargs: Any) -> None:
"""Prints to stderr."""
kwargs["file"] = sys.stderr
print(*args, **kwargs)
def _parse_pr_number(x: Any) -> Optional[int]:
"""Parses x into a positive integer if possible."""
if isinstance(x, int):
return x if x > 0 else None
if isinstance(x, str) and x.isdigit():
val = int(x)
return val if val > 0 else None
return None
def _parse_and_validate_state(
json_str: str,
open_pr_numbers: set[int],
max_merged_pr: int = 10000,
pr_number: int = 0,
) -> tuple[list[int], list[int], list[int], Optional[str]]:
"""Parses and validates the state from a JSON string."""
parsed_open: list[int] = []
parsed_merged: list[int] = []
parsed_ignored: list[int] = []
first_commit: Optional[str] = None
raw_state = json.loads(json_str)
if not isinstance(raw_state, dict):
raise ValueError(f"PR #{pr_number}: Parsed JSON is not a dictionary.")
for x in raw_state.get("open", []):
val = _parse_pr_number(x)
if val is None:
raise ValueError(
f"PR #{pr_number}: Invalid PR number format in 'open': {x}"
)
elif val not in open_pr_numbers and val > max_merged_pr:
raise ValueError(
f"PR #{pr_number}: Rejecting PR #{val} from 'open' because "
"it is not an open PR and exceeds maximum merged PR "
f"#{max_merged_pr}."
)
else:
parsed_open.append(val)
for x in raw_state.get("merged", []):
val = _parse_pr_number(x)
if val is None:
raise ValueError(
f"PR #{pr_number}: Invalid PR number format in 'merged': {x}"
)
elif val in open_pr_numbers:
raise ValueError(
f"PR #{pr_number}: Rejecting PR #{val} from 'merged' "
"because it is actually open."
)
elif val > max_merged_pr:
raise ValueError(
f"PR #{pr_number}: Rejecting PR #{val} from 'merged' "
f"because it exceeds maximum merged PR #{max_merged_pr}."
)
else:
parsed_merged.append(val)
for x in raw_state.get("ignored", []):
val = _parse_pr_number(x)
if val is None:
raise ValueError(
f"PR #{pr_number}: Invalid PR number format in 'ignored': {x}"
)
elif val not in open_pr_numbers and val > max_merged_pr:
raise ValueError(
f"PR #{pr_number}: Rejecting PR #{val} from 'ignored' because "
"it is not an open PR and exceeds maximum merged PR "
f"#{max_merged_pr}."
)
else:
parsed_ignored.append(val)
if "first_commit" in raw_state:
fc = raw_state["first_commit"]
if fc is None:
first_commit = None
elif isinstance(fc, str) and re.fullmatch(r"[0-9a-fA-F]{40}", fc):
first_commit = fc
else:
raise ValueError(
f"PR #{pr_number}: Invalid commit OID format in "
f"'first_commit': {fc}"
)
return parsed_open, parsed_merged, parsed_ignored, first_commit
def _set_commit_status(
sha: str,
state: str,
description: str,
token: str,
dry_run: bool,
) -> None:
"""Sets the commit status via the GitHub REST API."""
url = (
"https://api.github.com/repos/carbon-language/carbon-lang/"
f"statuses/{sha}"
)
headers = {
"Authorization": f"bearer {token}",
"Accept": "application/vnd.github.v3+json",
}
payload = {
"state": state,
"description": description,
"context": "PR dependencies check",
}
# Link `Details` to the Actions workflow run when running in CI so
# contributors can easily open and re-run the job if the check is stale.
server = os.environ.get("GITHUB_SERVER_URL")
repo = os.environ.get("GITHUB_REPOSITORY")
run_id = os.environ.get("GITHUB_RUN_ID")
if server and repo and run_id:
payload["target_url"] = f"{server}/{repo}/actions/runs/{run_id}"
if dry_run:
_print_err(
f"[Dry-run] Would set commit status on {sha[:8]} to {state} "
f"({description})"
)
return
try:
response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
_print_err(f"Set commit status on {sha[:8]} to {state}")
except Exception as e:
_print_err(f"Error setting commit status on {sha[:8]}: {e}")
def _process_pr(
client: github_helpers.Client,
pr_number: int,
pr_to_commits: dict[int, set[str]],
pr_to_head: dict[int, str],
open_pr_numbers: set[int],
label_id: str,
token: str,
dry_run: bool = False,
scanning: bool = False,
max_merged_pr: int = 10000,
recheck: bool = False,
override: bool = False,
) -> None:
"""Processes a single PR to check for dependencies and update comments."""
current_res = client.execute(
_QUERY_PR_DETAILS, variable_values={"prNumber": pr_number}
)
pr_node = current_res["repository"]["pullRequest"]
if not pr_node:
_print_err(f"PR #{pr_number} not found.")
return
pr_id = pr_node["id"]
commits = pr_node["commits"]["nodes"]
comments = pr_node["comments"]["nodes"]
labels = pr_node["labels"]["nodes"]
open_deps: list[int] = []
current_oids = [c["commit"]["oid"] for c in commits]
if len(commits) <= 1:
_print_err(
f"PR #{pr_number} has 1 or fewer commits, skipping overlap check."
)
else:
# Dependency Logic: Overlap and Sequence
#
# We consider PR B dependent on PR A if:
# 1. The dependency PR A was created before PR B (A.number < B.number).
# 2. There is a non-empty overlap of commits between PR A and PR B.
# 3. PR B has at least one commit not present in PR A.
#
# Why this works:
# - Ensures the dependency direction reflects the creation sequence.
# - Handles minor fixes or differences by only requiring overlap, not
# strict subset inclusion.
# - Avoids circular dependencies via the sequence check.
current_oids_set = set(current_oids)
for other_pr_num, other_oids_set in pr_to_commits.items():
if other_pr_num >= pr_number:
continue
# Filter out commits from PRs earlier than other_pr_num.
new_commits_in_other_pr = other_oids_set.copy()
for prev_pr_num, prev_oids_set in pr_to_commits.items():
if prev_pr_num < other_pr_num:
new_commits_in_other_pr -= prev_oids_set
if not (new_commits_in_other_pr & current_oids_set):
continue
if not (current_oids_set - other_oids_set):
continue
open_deps.append(other_pr_num)
# Parse existing comment
marker_prefix = "<!-- check_dependent_pr "
existing_comment_id = None
parsed_open_deps: list[int] = []
parsed_merged_deps: list[int] = []
parsed_ignored_deps: list[int] = []
previous_first_commit: Optional[str] = None
matching_comment = None
for comment in comments:
# If a marker comment is hidden (minimized), we ignore it and treat
# the PR as if it never had that comment.
if marker_prefix in comment["body"] and not comment.get("isMinimized"):
matching_comment = comment
break
if matching_comment:
existing_comment_id = matching_comment["id"]
body = matching_comment["body"]
start = body.find(marker_prefix) + len(marker_prefix)
end = body.find(" -->", start)
if end != -1:
(
parsed_open_deps,
parsed_merged_deps,
parsed_ignored_deps,
previous_first_commit,
) = _parse_and_validate_state(
body[start:end], open_pr_numbers, max_merged_pr, pr_number
)
has_dependent_label = any(label["name"] == "dependent" for label in labels)
# If the `dependent` label was manually removed while open dependencies
# were tracked, treat that as an override on single-PR checks as well.
if (
not recheck
and not override
and not scanning
and parsed_open_deps
and not has_dependent_label
):
override = True
if recheck:
# Recompute purely from current commit overlap, clearing any override
# or sticky dependencies carried over from earlier runs.
ignored_deps: list[int] = []
elif override:
# Move all detected and tracked open dependencies into `ignored` while
# they remain open so the status check becomes `success`.
ignored_deps = sorted(
{
pr
for pr in (open_deps + parsed_open_deps + parsed_ignored_deps)
if pr in open_pr_numbers
}
)
open_deps = []
else:
# Keep tracking previously identified dependencies if they are still
# open, even if they no longer pass the overlap check (e.g. they got
# force-pushed), while respecting any overridden dependencies.
ignored_deps = [
pr for pr in parsed_ignored_deps if pr in open_pr_numbers
]
for pr in parsed_open_deps:
if pr in open_pr_numbers and pr not in open_deps:
open_deps.append(pr)
open_deps = [pr for pr in open_deps if pr not in ignored_deps]
# Identify newly merged PRs
newly_merged_deps = []
for pr in set(parsed_open_deps + parsed_ignored_deps):
if pr not in open_deps and pr not in open_pr_numbers:
newly_merged_deps.append(pr)
merged_deps = list(set(parsed_merged_deps + newly_merged_deps))
if open_deps:
state = "pending"
pr_list_str = ", ".join([f"#{num}" for num in open_deps])
description = f"This PR has open dependencies: {pr_list_str}"
elif ignored_deps:
state = "success"
ignored_str = ", ".join([f"#{num}" for num in ignored_deps])
description = f"Dependency check overridden (ignoring {ignored_str})"
else:
state = "success"
description = "This PR has no open dependencies"
first_non_dep_oid = None
if open_deps:
dep_oids = set()
for d in open_deps:
dep_oids.update(pr_to_commits[d])
# previous_first_commit already assigned from comment state.
if previous_first_commit and previous_first_commit in current_oids:
start_idx = current_oids.index(previous_first_commit)
else:
start_idx = 0
# Assumes `current_oids` is in chronological order (oldest first).
# This guarantees we find the first non-dependency commit to start the
# review.
for oid in current_oids[start_idx:]:
if oid not in dep_oids:
first_non_dep_oid = oid
break
last_dep_pr_num = max(open_deps)
last_dep_oids = pr_to_commits[last_dep_pr_num]
# Find the most recent commit in the current PR that is also in the
# last dependency PR.
last_dep_head_oid = None
for oid in reversed(current_oids):
if oid in last_dep_oids:
last_dep_head_oid = oid
break
# Detect non-linear history: any commit in the current PR that is in
# *some* dependency but *not* in the last dependency.
any_later_dep_oids = any(
oid in dep_oids and oid not in last_dep_oids for oid in current_oids
)
# Construct new comment
timestamp = datetime.datetime.now(datetime.timezone.utc).strftime(
"%Y-%m-%d %H:%M:%S UTC"
)
new_state: dict[str, Any] = {
"open": open_deps,
"merged": merged_deps,
"first_commit": first_non_dep_oid,
}
if ignored_deps:
new_state["ignored"] = ignored_deps
state_json = json.dumps(new_state)
comment_body = f"{marker_prefix}{state_json} -->\n"
if open_deps:
pr_list_str = ", ".join([f"#{num}" for num in open_deps])
if last_dep_head_oid:
changes_url = (
"https://github.com/carbon-language/carbon-lang/pull/"
f"{pr_number}/changes/{last_dep_head_oid}..HEAD"
)
comment_body += (
f"Depends on {pr_list_str}, start review with "
f"[these changes]({changes_url})"
)
if any_later_dep_oids:
comment_body += (
"\n\n> [!WARNING]\n"
"> Also contains changes from dependency PRs due to "
"non-linear history."
)
else:
comment_body += (
f"Depends on {pr_list_str}, unable to identify starting review "
f"commit from simple analysis"
)
elif ignored_deps:
ignored_str = ", ".join([f"#{num}" for num in ignored_deps])
comment_body += f"Dependency check overridden (ignoring {ignored_str})."
elif merged_deps:
comment_body += "All dependency PRs are merged."
else:
comment_body += "No open dependency PRs."
if merged_deps:
merged_str = ", ".join([f"#{num}" for num in sorted(merged_deps)])
comment_body += f"\n\nMerged dependency PRs: {merged_str}"
comment_body += (
"\n\nSee the [dependent pull requests documentation]"
f"({_DOCS_URL}) for details on how stacked PRs are tracked, "
"re-checked, and overridden."
f"\n\n(Last updated: {timestamp})"
)
# Apply mutations only after all reading and analysis above is complete, so
# that the analysis never observes our own changes.
_set_commit_status(
pr_node["headRefOid"], state, description, token, dry_run
)
if open_deps and not has_dependent_label and not scanning:
if dry_run:
_print_err(
f"[Dry-run] Would add 'dependent' label to PR #{pr_number}"
)
else:
client.execute(
_MUTATION_ADD_LABEL,
variable_values={"labelableId": pr_id, "labelIds": [label_id]},
)
elif not open_deps and has_dependent_label:
if dry_run:
_print_err(
f"[Dry-run] Would remove 'dependent' label from PR #{pr_number}"
)
else:
client.execute(
_MUTATION_REMOVE_LABEL,
variable_values={"labelableId": pr_id, "labelIds": [label_id]},
)
# Only rewrite the comment when its tracked state changed. The status and
# label above are always reconciled so that, for example, a `dependent`
# label added to force a re-check is removed even if nothing else changed.
if (
open_deps == parsed_open_deps
and merged_deps == parsed_merged_deps
and ignored_deps == parsed_ignored_deps
and first_non_dep_oid == previous_first_commit
):
return
_print_err(f"PR #{pr_number}: Updating comment. New body:\n{comment_body}")
if existing_comment_id:
if dry_run:
_print_err(f"[Dry-run] Would update comment {existing_comment_id}")
else:
client.execute(
_MUTATION_UPDATE_COMMENT,
variable_values={
"id": existing_comment_id,
"body": comment_body,
},
)
else:
if scanning:
_print_err(
f"PR #{pr_number}: Skipping new comment creation in scan mode."
)
return
if dry_run:
_print_err(f"[Dry-run] Would add comment to PR #{pr_number}")
else:
client.execute(
_MUTATION_ADD_COMMENT,
variable_values={"subjectId": pr_id, "body": comment_body},
)
def _parse_args(args: Optional[list[str]] = None) -> argparse.Namespace:
"""Parses command-line arguments."""
parser = argparse.ArgumentParser(
description=__doc__,
formatter_class=argparse.RawDescriptionHelpFormatter,
)
group = parser.add_mutually_exclusive_group(required=True)
group.add_argument(
"--pr-number",
type=int,
help="The pull request number to check.",
)
group.add_argument(
"--scan",
action="store_true",
help="Scan all open PRs with 'dependent' label and update them.",
)
mode_group = parser.add_mutually_exclusive_group()
mode_group.add_argument(
"--recheck",
action="store_true",
help="Clear cached/overridden state and re-check dependencies.",
)
mode_group.add_argument(
"--override",
action="store_true",
help="Override open dependencies for the PR and set status to success.",
)
parser.add_argument(
"--dry-run",
action="store_true",
help="Print mutations without updating GitHub",
)
github_helpers.add_access_token_arg(parser, "repo")
parsed = parser.parse_args(args=args)
if parsed.scan and (parsed.recheck or parsed.override):
parser.error("--recheck and --override require --pr-number.")
return parsed
def main() -> None:
parsed_args = _parse_args()
client = github_helpers.Client(parsed_args)
_print_err("Loading open PRs ...", end="", flush=True)
pr_to_commits: dict[int, set[str]] = {}
pr_to_head: dict[int, str] = {}
open_pr_numbers: set[int] = set()
for node in client.execute_and_paginate(
_QUERY_OPEN_PRS, ("repository", "pullRequests")
):
_print_err(".", end="", flush=True)
other_pr_num = node["number"]
open_pr_numbers.add(other_pr_num)
pr_to_head[other_pr_num] = node["headRefOid"]
pr_to_commits[other_pr_num] = {
c["commit"]["oid"] for c in node["commits"]["nodes"]
}
_print_err()
label_res = client.execute(_QUERY_LABEL)
label_id = label_res["repository"]["label"]["id"]
merged_res = client.execute(_QUERY_MAX_MERGED_PR)
merged_nodes = merged_res["repository"]["pullRequests"]["nodes"]
max_merged_pr = merged_nodes[0]["number"] if merged_nodes else 0
if parsed_args.pr_number:
_process_pr(
client,
parsed_args.pr_number,
pr_to_commits,
pr_to_head,
open_pr_numbers,
label_id,
parsed_args.access_token,
dry_run=parsed_args.dry_run,
max_merged_pr=max_merged_pr,
recheck=parsed_args.recheck,
override=parsed_args.override,
)
elif parsed_args.scan:
for node in client.execute_and_paginate(
_QUERY_DEPENDENT_PRS, ("repository", "pullRequests")
):
_process_pr(
client,
node["number"],
pr_to_commits,
pr_to_head,
open_pr_numbers,
label_id,
parsed_args.access_token,
dry_run=parsed_args.dry_run,
scanning=True,
max_merged_pr=max_merged_pr,
)
if __name__ == "__main__":
main()