diff --git a/.github/workflows/check_dependent_pr.yaml b/.github/workflows/check_dependent_pr.yaml index 5c06e7b56304..1bb900108db4 100644 --- a/.github/workflows/check_dependent_pr.yaml +++ b/.github/workflows/check_dependent_pr.yaml @@ -4,12 +4,53 @@ name: 'Check Dependent PRs' on: + # zizmor: ignore[dangerous-triggers] - {necessary to mutate the PR} pull_request_target: - types: [opened, synchronize, ready_for_review, closed] + # Beyond code pushes and PR closes: + # - `reopened` refreshes status when a closed PR is reopened. + # - `edited` lets authors trigger a re-check by editing the PR description. + # - `labeled` / `unlabeled` let contributors with write access force a + # re-check (by adding `dependent`) or override a stale check (by removing + # `dependent`). + types: + - opened + - reopened + - synchronize + - ready_for_review + - edited + - labeled + - unlabeled + - closed + # Required checks on `trunk` must also report `success` on merge queue + # commits; PR dependencies are already verified prior to queueing. + merge_group: + # Allow manually checking, re-checking, overriding, or scanning from Actions. + workflow_dispatch: + inputs: + pr_number: + description: 'PR number to check (empty to scan dependent PRs)' + required: false + type: number + mode: + description: 'Mode when pr_number is provided' + required: false + type: choice + default: check + options: [check, recheck, override] +# Isolate concurrency by merge_group commit, closed-PR scan, or PR number, and +# avoid cancelling in-progress runs so rapid events (such as toggling labels or +# landing stacked PRs) cannot leave a required check unset or skip a scan. concurrency: - group: ${{ github.workflow }}-${{ github.event.pull_request.number }} - cancel-in-progress: true + group: >- + ${{ github.workflow }}-${{ + github.event.merge_group.head_sha || + (github.event.action == 'closed' && 'scan') || + github.event.pull_request.number || + inputs.pr_number || + 'scan' + }} + cancel-in-progress: false permissions: contents: read @@ -18,6 +59,14 @@ permissions: jobs: check_dependent_prs: + # Ignore label events for labels other than `dependent`, and ignore label + # changes made by this workflow itself to prevent self-triggering loops. + if: | + !contains(fromJSON('["labeled", "unlabeled"]'), github.event.action) || + ( + github.event.label.name == 'dependent' && + github.actor != 'github-actions[bot]' + ) runs-on: ubuntu-latest steps: - name: Harden Runner @@ -25,32 +74,57 @@ jobs: with: disable-sudo: true egress-policy: block + # prettier-ignore allowed-endpoints: > - api.github.com:443 github.com:443 pypi.org:443 - files.pythonhosted.org:443 raw.githubusercontent.com:443 + api.github.com:443 + files.pythonhosted.org:443 + github.com:443 + pypi.org:443 + raw.githubusercontent.com:443 releases.astral.sh:443 + - name: Report success for merge queue + if: github.event_name == 'merge_group' + env: + GH_TOKEN: ${{ github.token }} + HEAD_SHA: ${{ github.event.merge_group.head_sha }} + run: | + run_url="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" + gh api "repos/$GITHUB_REPOSITORY/statuses/$HEAD_SHA" \ + -f state=success \ + -f context='PR dependencies check' \ + -f description='Checked prior to merge queue' \ + -f target_url="$run_url" + # Note: pull_request_target checks out the base branch by default. # This is safe as it avoids running untrusted code from the PR branch. - name: Checkout code + if: github.event_name != 'merge_group' uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - name: Set up uv + if: github.event_name != 'merge_group' uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3 with: enable-cache: true version: '0.11.15' - name: Check Dependent PR + if: github.event_name != 'merge_group' + env: + DISPATCH_MODE: ${{ inputs.mode }} + EVENT_ACTION: ${{ github.event.action }} + GITHUB_ACCESS_TOKEN: ${{ secrets.GITHUB_TOKEN }} + PR_NUMBER: ${{ github.event.pull_request.number || inputs.pr_number }} run: | - if [ "$EVENT_ACTION" = "closed" ]; then + if [ "$EVENT_ACTION" = "closed" ] || [ -z "$PR_NUMBER" ]; then ./github_tools/check_dependent_pr.py --scan + elif [ "$EVENT_ACTION" = "unlabeled" ] || [ "$DISPATCH_MODE" = "override" ]; then + ./github_tools/check_dependent_pr.py --pr-number "${PR_NUMBER}" --override + elif [ "$EVENT_ACTION" = "labeled" ] || [ "$DISPATCH_MODE" = "recheck" ]; then + ./github_tools/check_dependent_pr.py --pr-number "${PR_NUMBER}" --recheck else ./github_tools/check_dependent_pr.py --pr-number "${PR_NUMBER}" fi - env: - GITHUB_ACCESS_TOKEN: ${{ secrets.GITHUB_TOKEN }} - PR_NUMBER: ${{ github.event.pull_request.number }} - EVENT_ACTION: ${{ github.event.action }} diff --git a/docs/project/code_review.md b/docs/project/code_review.md index be93d24c2c3a..bfb4ee18899a 100644 --- a/docs/project/code_review.md +++ b/docs/project/code_review.md @@ -229,6 +229,11 @@ far. It is still possible to shrink a change so much that it becomes nonsensical in isolation. For example, a change without appropriate tests is not self-contained. +When a series of small changes build on each other before earlier ones have +merged, see +[Dependent pull requests](pull_request_workflow.md#dependent-pull-requests) for +how stacked pull requests are tracked and reviewed. + ### Responding to review comments Many comments have easy and simple responses. The easiest is **"Done"**. When diff --git a/docs/project/pull_request_workflow.md b/docs/project/pull_request_workflow.md index 477b5fb7dfd1..5deed1691c27 100644 --- a/docs/project/pull_request_workflow.md +++ b/docs/project/pull_request_workflow.md @@ -15,6 +15,7 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception - [Green tests](#green-tests) - [Always use pull requests (with review) rather than pushing directly](#always-use-pull-requests-with-review-rather-than-pushing-directly) - [Small, incremental changes](#small-incremental-changes) + - [Dependent pull requests](#dependent-pull-requests) - [Linear history](#linear-history) - [Merging a pull request](#merging-a-pull-request) @@ -102,6 +103,38 @@ review you typically want to leave the development history undisturbed until the end so that comments on any particular increment aren't lost. We typically use the GitHub squash-and-merge functionality to land things. +### Dependent pull requests + +When splitting work into a series of changes that build on each other, open each +pull request against `trunk` with the commits from earlier unmerged pull +requests included in its branch. + +The `PR dependencies check` status tracks these dependencies based on shared +commits: + +- While a pull request depends on other open pull requests, the check adds the + `dependent` label, posts a comment linking to the diff of just that pull + request's commits, and leaves its status `pending` so it doesn't merge + before its dependencies. +- Once those pull requests merge, the check removes the `dependent` label, + updates the comment, and marks the status `success`. + +If the check becomes stale, editing the pull request description runs it again. +Contributors with write access can also re-run the workflow job from the check's +`Details` link, or use the `dependent` label: + +- **Re-check**: Adding the label drops any override and recomputes the open + dependencies from the current commits. If the label is already present, + remove and re-add it. +- **Override**: Removing the label ignores the currently detected dependencies + and marks the status `success`. + +Both are also available by manually running the +[`Check Dependent PRs` workflow](https://github.com/carbon-language/carbon-lang/actions/workflows/check_dependent_pr.yaml) +with the `recheck` or `override` mode. Hiding the check's comment discards all +of its tracked state, including merged dependencies, so the next check starts +from scratch. + ## Linear history We want the history of the `trunk` branch of each repository to be as simple and diff --git a/github_tools/check_dependent_pr.py b/github_tools/check_dependent_pr.py index 4d1785b54aa1..266f89248277 100755 --- a/github_tools/check_dependent_pr.py +++ b/github_tools/check_dependent_pr.py @@ -16,6 +16,12 @@ Usage examples: GITHUB_ACCESS_TOKEN=$(gh auth token) \ ./github_tools/check_dependent_pr.py --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 --recheck + GITHUB_ACCESS_TOKEN=$(gh auth token) \ + ./github_tools/check_dependent_pr.py --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 @@ -30,6 +36,7 @@ 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 @@ -41,6 +48,11 @@ try: 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 = """ { @@ -191,10 +203,11 @@ def _parse_and_validate_state( open_pr_numbers: set[int], max_merged_pr: int = 10000, pr_number: int = 0, -) -> tuple[list[int], list[int], Optional[str]]: +) -> 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) @@ -233,6 +246,20 @@ def _parse_and_validate_state( ) 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: @@ -244,7 +271,7 @@ def _parse_and_validate_state( f"PR #{pr_number}: Invalid commit OID format in " f"'first_commit': {fc}" ) - return parsed_open, parsed_merged, first_commit + return parsed_open, parsed_merged, parsed_ignored, first_commit def _set_commit_status( @@ -268,6 +295,13 @@ def _set_commit_status( "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} " @@ -294,6 +328,8 @@ def _process_pr( 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( @@ -352,6 +388,7 @@ def _process_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 @@ -368,21 +405,58 @@ def _process_pr( start = body.find(marker_prefix) + len(marker_prefix) end = body.find(" -->", start) if end != -1: - parsed_open_deps, parsed_merged_deps, previous_first_commit = ( - _parse_and_validate_state( - body[start:end], open_pr_numbers, max_merged_pr, pr_number - ) + ( + 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 ) - # Keep tracking previously identified dependencies if they are still open, - # even if they no longer pass the subset check (e.g. they got new commits). - for pr in parsed_open_deps: - if pr in open_pr_numbers and pr not in open_deps: - open_deps.append(pr) + 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 parsed_open_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) @@ -392,14 +466,14 @@ def _process_pr( 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" - _set_commit_status( - pr_node["headRefOid"], state, description, token, dry_run - ) - first_non_dep_oid = None if open_deps: dep_oids = set() @@ -437,13 +511,6 @@ def _process_pr( oid in dep_oids and oid not in last_dep_oids for oid in current_oids ) - if ( - open_deps == parsed_open_deps - and merged_deps == parsed_merged_deps - and first_non_dep_oid == previous_first_commit - ): - return - # Construct new comment timestamp = datetime.datetime.now(datetime.timezone.utc).strftime( "%Y-%m-%d %H:%M:%S UTC" @@ -453,6 +520,8 @@ def _process_pr( "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" @@ -479,19 +548,30 @@ def _process_pr( f"Depends on {pr_list_str}, unable to identify starting review " f"commit from simple analysis" ) - else: + 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 += f"\n\n(Last updated: {timestamp})" + 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})" + ) - _print_err(f"PR #{pr_number}: Updating comment. New body:\n{comment_body}") - - # Apply mutations - has_dependent_label = any(label["name"] == "dependent" for label in labels) + # 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: @@ -514,6 +594,19 @@ def _process_pr( 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}") @@ -557,13 +650,27 @@ def _parse_args(args: Optional[list[str]] = None) -> argparse.Namespace: 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") - return parser.parse_args(args=args) + 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: @@ -604,6 +711,8 @@ def main() -> None: 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( diff --git a/github_tools/check_dependent_pr_test.py b/github_tools/check_dependent_pr_test.py index 6bcc772d9b96..c0f240c6f41c 100644 --- a/github_tools/check_dependent_pr_test.py +++ b/github_tools/check_dependent_pr_test.py @@ -7,6 +7,7 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception """ import json +import os import unittest from typing import Any from unittest import mock @@ -45,6 +46,7 @@ class TestCheckDependentPR(unittest.TestCase): open_deps: list[int], merged_deps: list[int] = None, first_commit: str = None, + ignored_deps: list[int] = None, comment_id: str = "comment_id", ) -> dict[str, str]: """Builds a boilerplate PR comment.""" @@ -54,6 +56,8 @@ class TestCheckDependentPR(unittest.TestCase): } if first_commit: state["first_commit"] = first_commit + if ignored_deps: + state["ignored"] = ignored_deps return { "id": comment_id, "body": f"", @@ -126,6 +130,10 @@ class TestCheckDependentPR(unittest.TestCase): calls = self.mock_client.execute.call_args_list self.assertIn("addLabelsToLabelable", calls[1][0][0]) self.assertIn("addComment", calls[2][0][0]) + self.assertIn( + check_dependent_pr._DOCS_URL, + calls[2][1]["variable_values"]["body"], + ) self._assert_status( _OID2, "pending", "This PR has open dependencies: #1" ) @@ -220,6 +228,10 @@ class TestCheckDependentPR(unittest.TestCase): calls = self.mock_client.execute.call_args_list self.assertIn("addLabelsToLabelable", calls[1][0][0]) self.assertIn("addComment", calls[2][0][0]) + self.assertIn( + check_dependent_pr._DOCS_URL, + calls[2][1]["variable_values"]["body"], + ) self._assert_status( _OID2, "pending", "This PR has open dependencies: #1" ) @@ -565,6 +577,126 @@ class TestCheckDependentPR(unittest.TestCase): check_dependent_pr._QUERY_MAX_MERGED_PR, ) + def test_process_pr_override(self) -> None: + self.mock_client.execute.return_value = self._make_pr_response( + pr_id="pr_3", + head_ref_oid=_OID3, + commits=[_OID1, _OID3], + comments=[self._make_comment(open_deps=[1], first_commit=_OID3)], + has_dependent_label=True, + ) + check_dependent_pr._process_pr( + self.mock_client, + pr_number=3, + pr_to_commits={1: {_OID1}, 3: {_OID1, _OID3}}, + pr_to_head={1: _OID1, 3: _OID3}, + open_pr_numbers={1, 3}, + label_id="label_dependent", + token="test_token", + override=True, + ) + calls = self.mock_client.execute.call_args_list + self.assertIn("removeLabelsFromLabelable", calls[1][0][0]) + self.assertIn('"ignored": [1]', calls[2][1]["variable_values"]["body"]) + self._assert_status( + _OID3, "success", "Dependency check overridden (ignoring #1)" + ) + + # Subsequent push keeps #1 ignored, while still catching new dep #2. + self.mock_post.reset_mock() + self.mock_client.reset_mock() + self.mock_client.execute.return_value = self._make_pr_response( + pr_id="pr_3", + head_ref_oid=_OID4, + commits=[_OID1, _OID2, _OID4], + comments=[self._make_comment(open_deps=[], ignored_deps=[1])], + ) + check_dependent_pr._process_pr( + self.mock_client, + pr_number=3, + pr_to_commits={ + 1: {_OID1}, + 2: {_OID1, _OID2}, + 3: {_OID1, _OID2, _OID4}, + }, + pr_to_head={1: _OID1, 2: _OID2, 3: _OID4}, + open_pr_numbers={1, 2, 3}, + label_id="label_dependent", + token="test_token", + ) + self._assert_status( + _OID4, "pending", "This PR has open dependencies: #2" + ) + + def test_process_pr_recheck(self) -> None: + self.mock_client.execute.return_value = self._make_pr_response( + pr_id="pr_2", + head_ref_oid=_OID2, + commits=[_OID2], + comments=[self._make_comment(open_deps=[1], ignored_deps=[3])], + has_dependent_label=True, + ) + check_dependent_pr._process_pr( + self.mock_client, + pr_number=2, + pr_to_commits={1: {_OID1}, 2: {_OID2}, 3: {_OID3}}, + pr_to_head={1: _OID1, 2: _OID2, 3: _OID3}, + open_pr_numbers={1, 2, 3}, + label_id="label_dependent", + token="test_token", + recheck=True, + ) + calls = self.mock_client.execute.call_args_list + self.assertIn("removeLabelsFromLabelable", calls[1][0][0]) + self.assertIn("updateIssueComment", calls[2][0][0]) + self._assert_status( + _OID2, "success", "This PR has no open dependencies" + ) + + def test_process_pr_recheck_removes_label_without_comment(self) -> None: + # Adding `dependent` to an independent PR forces a re-check, which + # removes the label again without posting a comment. + self.mock_client.execute.return_value = self._make_pr_response( + pr_id="pr_2", + head_ref_oid=_OID2, + commits=[_OID2], + has_dependent_label=True, + ) + check_dependent_pr._process_pr( + self.mock_client, + pr_number=2, + pr_to_commits={2: {_OID2}}, + pr_to_head={2: _OID2}, + open_pr_numbers={2}, + label_id="label_dependent", + token="test_token", + recheck=True, + ) + calls = self.mock_client.execute.call_args_list + self.assertEqual(len(calls), 2) + self.assertIn("removeLabelsFromLabelable", calls[1][0][0]) + self._assert_status( + _OID2, "success", "This PR has no open dependencies" + ) + + def test_set_commit_status_links_workflow_run(self) -> None: + with mock.patch.dict( + os.environ, + { + "GITHUB_SERVER_URL": "https://github.com", + "GITHUB_REPOSITORY": "carbon-language/carbon-lang", + "GITHUB_RUN_ID": "42", + }, + ): + check_dependent_pr._set_commit_status( + _OID1, "success", "ok", "test_token", dry_run=False + ) + _, kwargs = self.mock_post.call_args + self.assertEqual( + kwargs["json"]["target_url"], + "https://github.com/carbon-language/carbon-lang/actions/runs/42", + ) + if __name__ == "__main__": unittest.main()