From 1e739999d26dec850d01a7bbb3a668cd56d154bc Mon Sep 17 00:00:00 2001 From: Christophe Bedard Date: Sat, 14 Nov 2026 15:38:18 -0800 Subject: [PATCH] Add --stack option to test a GitHub PR stack Given a PR that is part of a GitHub PR stack, look up the whole stack and use the source branch of the top PR in the modified `ros2.repos`, since it contains the changes from all PRs of the stack. With `--comment`, post the comment on every open PR of the stack; this also works with `--test-report`. PyGithub does not support PR stacks, so query the REST API directly: https://docs.github.com/en/rest/pulls/stacks When using `--build`, ask for confirmation if the stack targets a different branch than the selected release (this check already exists for normal PRs), or if the top PR's branch is missing changes from the other PRs of the stack. `--stack` cannot be combined with `--pulls`, `--interactive`, or `--branch`: testing a PR stack along with other PRs is not supported for now. --- Example: ros2/rviz#1916 is stacked on ros2/rviz#1915 against Lyrical. Running: ``` $ GITHUB_TOKEN=... ros-ci-for-pr \ -s ros2/rviz#1915 -k rviz_ogre_vendor -t lyrical -b -c ``` Creates a gist using ros2/rviz#1916 (the top of the stack, which includes ros2/rviz#1915's changes) and comments on both ros2/rviz#1915 and ros2/rviz#1916 with the CI jobs info: * https://github.com/ros2/rviz/pull/1915#issuecomment-6886087162 * https://github.com/ros2/rviz/pull/1916#issuecomment-6886087336 Signed-off-by: Christophe Bedard --- AGENTS.md | 13 ++- README.md | 22 +++++ ros_github_scripts/ci_for_pr.py | 133 +++++++++++++++++++++++-- test/test_ci_for_pr.py | 165 +++++++++++++++++++++++++++++++- 4 files changed, 321 insertions(+), 12 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9aaef30..52cb045 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,6 +28,13 @@ ros-ci-for-pr --pulls ros2/rosbag2#2542 --packages rosbag2_tests --build --comme - Default to `--pulls ORG/REPO#N` (one PR per repo) with `--build` and `--comment` together. Use `--branch NAME` only for a branch pushed directly to `ros2/*` (no fork), e.g. a coordinated multi-repo change. +- If the PR is part of a GitHub PR stack (`gh api repos/ORG/REPO/pulls/N + --jq .stack` is not `null`), use `--stack ORG/REPO#N` instead of + `--pulls`: it tests the top PR of the stack, which contains the changes + from all PRs of the stack, and comments on every open PR of the stack. + It can't be combined with `--pulls`, `--interactive`, or `--branch`. + With `--build`, it asks `Continue anyway? [y/N]` if the stack targets + another distro or needs a rebase; relay that to the user, don't answer it. - **Always pass `--packages`** when you know what the PR touches (`gh pr view N -R ORG/REPO --json files`) — an unscoped run builds/tests 300+ packages across four platforms. It expands to @@ -35,9 +42,10 @@ ros-ci-for-pr --pulls ros2/rosbag2#2542 --packages rosbag2_tests --build --comme test. If the change is test-only, use `--only-fixes-test` instead for a much narrower/faster run. - `--target ` defaults to `rolling`; set explicitly if the PR's - base branch differs. + (or PR stack's) base branch differs. - Once the build finishes, pull results with `--test-report --pulls ORG/REPO#N --comment` (mutually exclusive with `--build`). + URL> --pulls ORG/REPO#N --comment` (or `--stack ORG/REPO#N`; mutually + exclusive with `--build`). ## ros-find-restarted-ci @@ -58,6 +66,7 @@ Run without `-u` first and show the user what it found before applying. | Task | Command | |---|---| | Launch CI for a PR | `ros-ci-for-pr --pulls ORG/REPO#N --packages PKG... --build --comment` | +| Launch CI for a PR stack | `ros-ci-for-pr --stack ORG/REPO#N --packages PKG... --build --comment` | | Dry run (no Jenkins call) | same, minus `--build` | | Pull test results from a finished run | `ros-ci-for-pr --test-report --pulls ORG/REPO#N --comment` | | Fix a stale "failed" badge | `ros-find-restarted-ci -u ` | diff --git a/README.md b/README.md index bbddf7b..409cd5b 100644 --- a/README.md +++ b/README.md @@ -84,6 +84,28 @@ ros-ci-for-pr \ --comment ``` +### With a GitHub PR stack + +As another alternative, a PR that is part of a [GitHub PR stack](https://gh.io/stacks) can be provided using the `--stack` option, in the same format as `--pulls`. +Any PR of the stack can be provided: the whole stack is looked up, and the source branch of the top PR is used in the modified `ros2.repos`, so CI tests the changes from _all_ PRs of the stack together. +When using the `--comment` option, the comment is posted on every open PR of the stack. + +Example: + +``` +export GITHUB_ACCESS_TOKEN=$GITHUB_TOKEN +ros-ci-for-pr \ + --stack ros2/repo#123 \ + --packages pkg1 pkg2 \ + --build \ + --comment +``` + +Testing a PR stack along with other PRs is not supported for now: the `--stack` option cannot be combined with `--pulls`, `--interactive`, or `--branch`. +Also note that GitHub requires all branches of a stack to be in the same repository: stacks across forks are not supported. + +Before starting a build, you are asked for confirmation if the stack targets a different branch than the selected `--target` release, or if the top PR is missing changes from other PRs of the stack (i.e., the stack needs to be rebased). + ## ros-github-contribution-report Generates a report of merged PRs on GitHub from a set of authors, optionally filtered by time and destination, and rendered to a variety of formats. diff --git a/ros_github_scripts/ci_for_pr.py b/ros_github_scripts/ci_for_pr.py index 5e4a703..260859d 100755 --- a/ros_github_scripts/ci_for_pr.py +++ b/ros_github_scripts/ci_for_pr.py @@ -13,6 +13,7 @@ # limitations under the License. import argparse +import dataclasses import logging import os import re @@ -230,6 +231,66 @@ def validate_and_fetch_pull_list( return return_prs +@dataclasses.dataclass +class PullStack: + """GitHub PR stack, with its open PRs ordered from bottom to top.""" + + repo: github.Repository.Repository + number: int + base_ref: str + pulls: List[github.PullRequest.PullRequest] + + @property + def top(self) -> github.PullRequest.PullRequest: + """Get the top PR, whose source branch contains the changes from all PRs in the stack.""" + return self.pulls[-1] + + +def fetch_pull_stack(github_instance: Github, pull: str) -> PullStack: + """ + Fetch the GitHub PR stack that contains the given pull request. + + Panic if the pull request is not part of a stack or if the stack does not have any open PRs. + + :param pull: pull request, in a format supported by parse_pull_spec() + """ + repo_name, pull_number = parse_pull_spec(pull) + repo = github_instance.get_repo(repo_name) + # PyGithub does not support PR stacks, so use the REST API directly: + # https://docs.github.com/en/rest/pulls/stacks + _, stacks = repo._requester.requestJsonAndCheck( + 'GET', f'{repo.url}/stacks', parameters={'pull_request': pull_number}) + if not stacks: + panic(f'{repo.full_name}#{pull_number} is not part of a GitHub PR stack') + # Unclear if a PR can technically be part of >1 stacks; check just in case + if len(stacks) > 1: + panic(f'{repo.full_name}#{pull_number} is part of multiple GitHub PR stacks') + stack = stacks[0] + stack_number = stack['number'] + base_ref = stack['base']['ref'] + + open_pull_numbers = [] + for stack_pull in stack['pull_requests']: + stack_pull_number = stack_pull['number'] + if stack_pull['state'] == 'open': + open_pull_numbers.append(stack_pull_number) + elif stack_pull['merged_at'] is None: + logger.warning( + f'{repo.full_name}#{stack_pull_number} is part of the PR stack but was closed ' + 'without being merged; its changes may still be included in the PRs above it') + if not open_pull_numbers: + panic(f'GitHub PR stack #{stack_number} in {repo.full_name} does not have any open PRs') + + # Sort from bottom to top using the position of each PR in the stack + pulls = sorted( + (repo.get_pull(number) for number in open_pull_numbers), + key=lambda github_pr: github_pr.raw_data['stack']['position']) + logger.info( + f'Found GitHub PR stack #{stack_number} in {repo.full_name} targeting {base_ref} with ' + 'open PRs (bottom to top): ' + ', '.join(f'#{github_pr.number}' for github_pr in pulls)) + return PullStack(repo=repo, number=stack_number, base_ref=base_ref, pulls=pulls) + + def prompt_continue_or_abort(abort_message: str) -> None: """Prompt for confirmation to continue anyway, and panic with the given message if not.""" answer = input('Continue anyway? [y/N] ').strip().lower() @@ -257,6 +318,37 @@ def validate_pulls_target( prompt_continue_or_abort('Target mismatch, aborting') +def validate_stack_target(pull_stack: PullStack, target_release: str) -> None: + """Prompt for confirmation if the stack's base branch does not match the target release.""" + if pull_stack.base_ref == target_release: + return + + print('\n>>> The PR stack targets a different branch than the selected release <<<') + print(f' {pull_stack.repo.full_name} stack #{pull_stack.number}: {pull_stack.base_ref}') + print(f' Selected target release: {target_release}') + prompt_continue_or_abort('Target mismatch, aborting') + + +def validate_stack_up_to_date(pull_stack: PullStack) -> None: + """Prompt for confirmation if the top PR is missing changes from other PRs of the stack.""" + top = pull_stack.top + outdated_pulls = [] + for pull in pull_stack.pulls[:-1]: + # The PR's source branch should be an ancestor of the top PR's source branch + comparison = pull_stack.repo.compare(pull.head.sha, top.head.sha) + if comparison.status not in ('ahead', 'identical'): + outdated_pulls.append(pull) + if not outdated_pulls: + return + + print('\n>>> The top PR of the stack is missing changes from the following PRs <<<') + for pull in outdated_pulls: + print(f' {pull_stack.repo.full_name}#{pull.number}: {pull.head.ref}') + print(f' Top PR: {pull_stack.repo.full_name}#{top.number}: {top.head.ref}') + print(' CI only tests the top PR, so the PR stack may need to be rebased') + prompt_continue_or_abort('PR stack is not up to date, aborting') + + def format_ci_details( *, gist_url: Optional[str], @@ -264,11 +356,13 @@ def format_ci_details( extra_test_args: str, target_release: str, target_pulls: Optional[List[str]], + is_pull_stack: bool, branch_name: Optional[str], ) -> str: details = [] if target_pulls: - details.append(f"Pulls: {', '.join(target_pulls)}") + pulls_label = 'PR stack' if is_pull_stack else 'Pulls' + details.append(f"{pulls_label}: {', '.join(target_pulls)}") if gist_url: details.append(f'Gist: {gist_url}') if branch_name: @@ -495,7 +589,7 @@ def parse_args(argv: Optional[List[str]] = None) -> argparse.Namespace: select_group = parser.add_argument_group( title='change selection', - description='Select the PRs or branch to test.') + description='Select the PRs, PR stack, or branch to test.') select_group.add_argument( '--branch', type=str, help='Branch to test across the repositories in the .repos files that have it. Corresponds ' @@ -513,6 +607,12 @@ def parse_args(argv: Optional[List[str]] = None) -> argparse.Namespace: '-i', '--interactive', action='store_true', help='Prompt me to select my pull requests from a list, instead of specifying. When using ' 'the --branch and --comment options, comments will be posted on these PRs.') + pulls_group.add_argument( + '-s', '--stack', type=str, metavar='PULL', + help='Pull request that is part of a GitHub PR stack, in the same format as --pulls. The ' + 'source branch of the top PR of the stack is tested, which contains the changes ' + 'from all PRs of the stack. When using the --comment option, comments will be ' + 'posted on all open PRs of the stack. Cannot be combined with --branch.') # Create a group for these so that they are displayed below the 'change selection' group group = parser.add_argument_group(title='other options') @@ -553,9 +653,13 @@ def printable_package_name(value): help='Fetch test results from a completed ci_launcher run and post a failure summary. ' 'Provide the ci_launcher build URL ' '(e.g. https://ci.ros2.org/job/ci_launcher/19468). ' - 'Use with --pulls and --comment to post the summary on the PR(s). ' + 'Use with --pulls or --stack and --comment to post the summary on the PR(s). ' 'Cannot be combined with --build.') - return parser.parse_args(argv) + args = parser.parse_args(argv) + # --branch can be combined with --pulls and --interactive, so it is not in their group + if args.stack and args.branch: + parser.error('argument -s/--stack: not allowed with argument --branch') + return args def main(): @@ -570,31 +674,43 @@ def main(): branch_name = parsed.branch pull_texts = parsed.pulls + # PRs to comment on chosen_pulls = [] + pull_stack: Optional[PullStack] = None if parsed.interactive: all_user_pulls = fetch_user_pulls(github_instance) pull_texts, chosen_pulls = prompt_pull_selection(all_user_pulls) elif parsed.pulls: chosen_pulls = validate_and_fetch_pull_list(github_instance, parsed.pulls) + elif parsed.stack: + pull_stack = fetch_pull_stack(github_instance, parsed.stack) + chosen_pulls = pull_stack.pulls + pull_texts = [f'{pull_stack.repo.full_name}#{pull.number}' for pull in pull_stack.pulls] # Have to select PRs when not providing branch if not branch_name and not chosen_pulls: panic( - 'When not using --branch, you must select PRs either using --interactive ' - 'or by providing them using --pulls') + 'When not using --branch, you must select PRs either using --interactive, ' + 'by providing them using --pulls, or by providing a PR stack using --stack') # Have to select PRs when providing branch and enabling comments if branch_name and parsed.comment and not chosen_pulls: panic( 'When using --branch and --comment, you must select PRs to comment on either using ' '--interactive or by providing them using --pulls') - if parsed.build and chosen_pulls: + if parsed.build and pull_stack: + validate_stack_target(pull_stack, parsed.target) + validate_stack_up_to_date(pull_stack) + elif parsed.build and chosen_pulls: validate_pulls_target(chosen_pulls, parsed.target) # Only create a gist if we are triggering a build (not for --test-report only) gist_url = None if chosen_pulls and not branch_name and not parsed.test_report: - gist = create_ci_gist(github_instance, chosen_pulls, parsed.target) + # The top PR of a stack contains the changes from all PRs of the stack + gist_pulls = [pull_stack.top] if pull_stack else chosen_pulls + gist = create_ci_gist( + github_instance, gist_pulls, parsed.target, description_pulls=chosen_pulls) gist_url = gist.files['ros2.repos'].raw_url if parsed.build and parsed.test_report: @@ -627,6 +743,7 @@ def main(): extra_test_args=extra_test_args, target_release=parsed.target, target_pulls=pull_texts, + is_pull_stack=pull_stack is not None, branch_name=branch_name)) if parsed.build: user = github_instance.get_user().login diff --git a/test/test_ci_for_pr.py b/test/test_ci_for_pr.py index 3012cdf..cb762a9 100644 --- a/test/test_ci_for_pr.py +++ b/test/test_ci_for_pr.py @@ -15,29 +15,72 @@ from contextlib import redirect_stderr, redirect_stdout import io import unittest -from unittest.mock import MagicMock, patch +from unittest.mock import call, MagicMock, patch from ros_github_scripts.ci_for_pr import ( create_ci_gist, + fetch_pull_stack, parse_args, parse_pull_spec, + PullStack, validate_and_fetch_pull_list, validate_pulls_target, + validate_stack_target, + validate_stack_up_to_date, ) import yaml -def make_pull(number, base_ref='rolling'): +def make_pull(number, base_ref='rolling', position=None): """Make a mock pull request in the ros2/rviz repository.""" pull = MagicMock() pull.number = number pull.head.ref = f'branch-{number}' + pull.head.sha = f'sha-{number}' pull.head.repo.full_name = 'ros2/rviz' pull.base.ref = base_ref pull.base.repo.full_name = 'ros2/rviz' + pull.raw_data = {'stack': {'position': position}} if position else {} return pull +def make_stack_json(number, base_ref, pulls): + """Make a PR stack, as returned by the REST API, from (number, state, merged) tuples.""" + return { + 'number': number, + 'base': {'ref': base_ref}, + 'pull_requests': [ + { + 'number': pull_number, + 'state': state, + 'merged_at': '2026-10-01T20:57:11Z' if merged else None, + 'head': {'ref': f'branch-{pull_number}', 'sha': f'sha-{pull_number}'}, + } + for pull_number, state, merged in pulls + ], + } + + +def make_github(stacks, positions): + """Make a mock GitHub instance where ros2/rviz has the given PR stacks.""" + repo = MagicMock() + repo.full_name = 'ros2/rviz' + repo.url = 'https://api.github.com/repos/ros2/rviz' + repo._requester.requestJsonAndCheck.return_value = ({}, stacks) + repo.get_pull.side_effect = lambda number: make_pull(number, position=positions[number]) + github_instance = MagicMock() + github_instance.get_repo.return_value = repo + return github_instance + + +def make_pull_stack(base_ref, numbers): + """Make a PR stack in ros2/rviz with mock pull requests.""" + repo = MagicMock() + repo.full_name = 'ros2/rviz' + return PullStack( + repo=repo, number=100, base_ref=base_ref, pulls=[make_pull(number) for number in numbers]) + + class TestParsePullSpec(unittest.TestCase): def test_valid_pull_descriptors(self): @@ -75,6 +118,72 @@ def test_invalid_pull_number(self): validate_and_fetch_pull_list(MagicMock(), [pull]) +class TestFetchPullStack(unittest.TestCase): + + def test_not_in_stack(self): + with self.assertRaisesRegex(RuntimeError, 'not part of a GitHub PR stack'): + fetch_pull_stack(make_github([], {}), 'ros2/rviz#1234') + + def test_stack(self): + stack = make_stack_json(1917, 'lyrical', [(1915, 'open', False), (1916, 'open', False)]) + github_instance = make_github([stack], {1915: 1, 1916: 2}) + + pull_stack = fetch_pull_stack(github_instance, 'https://github.com/ros2/rviz/pull/1915') + + github_instance.get_repo.assert_called_once_with('ros2/rviz') + repo = github_instance.get_repo.return_value + repo._requester.requestJsonAndCheck.assert_called_once_with( + 'GET', + 'https://api.github.com/repos/ros2/rviz/stacks', + parameters={'pull_request': 1915}) + self.assertEqual(pull_stack.number, 1917) + self.assertEqual(pull_stack.base_ref, 'lyrical') + self.assertEqual([pull.number for pull in pull_stack.pulls], [1915, 1916]) + self.assertEqual(pull_stack.top.number, 1916) + + def test_order_by_position(self): + # The top PR of github/gh-stack's stack #530 has the lowest number + numbers = [526, 527, 528, 529, 521] + positions = {number: index + 1 for index, number in enumerate(numbers)} + stack = make_stack_json(530, 'main', [(number, 'open', False) for number in numbers]) + # The order of the PRs in the API response should not matter + stack['pull_requests'].reverse() + + pull_stack = fetch_pull_stack(make_github([stack], positions), 'ros2/rviz#527') + + self.assertEqual([pull.number for pull in pull_stack.pulls], numbers) + self.assertEqual(pull_stack.top.number, 521) + + def test_closed_pulls(self): + stack = make_stack_json(100, 'rolling', [ + (10, 'closed', True), # merged + (11, 'closed', False), # closed without being merged + (12, 'open', False), + (13, 'open', False), + ]) + + with self.assertLogs('ros_github_scripts.ci_for_pr', level='WARNING') as logs: + pull_stack = fetch_pull_stack(make_github([stack], {12: 3, 13: 4}), 'ros2/rviz#12') + + self.assertEqual([pull.number for pull in pull_stack.pulls], [12, 13]) + # Only the PR that was closed without being merged should be reported + self.assertEqual(len(logs.output), 1) + self.assertIn('ros2/rviz#11', logs.output[0]) + + def test_no_open_pulls(self): + stack = make_stack_json(580, 'main', [(578, 'closed', True), (579, 'closed', True)]) + with self.assertRaisesRegex(RuntimeError, 'does not have any open PRs'): + fetch_pull_stack(make_github([stack], {}), 'ros2/rviz#578') + + def test_multiple_stacks(self): + stacks = [ + make_stack_json(1, 'rolling', [(10, 'open', False)]), + make_stack_json(2, 'rolling', [(10, 'open', False)]), + ] + with self.assertRaisesRegex(RuntimeError, 'multiple GitHub PR stacks'): + fetch_pull_stack(make_github(stacks, {}), 'ros2/rviz#10') + + class TestValidatePullsTarget(unittest.TestCase): @patch('builtins.input') @@ -97,6 +206,51 @@ def test_target_mismatch_continue(self, mock_input): mock_input.assert_called_once() +class TestValidateStack(unittest.TestCase): + + @patch('builtins.input') + def test_target_match(self, mock_input): + validate_stack_target(make_pull_stack('rolling', [1, 2]), 'rolling') + mock_input.assert_not_called() + + @patch('builtins.input', return_value='n') + def test_target_mismatch_abort(self, mock_input): + with redirect_stdout(io.StringIO()) as stdout: + with self.assertRaisesRegex(RuntimeError, 'Target mismatch'): + validate_stack_target(make_pull_stack('lyrical', [1, 2]), 'rolling') + self.assertIn('ros2/rviz stack #100: lyrical', stdout.getvalue()) + + @patch('builtins.input', return_value='y') + def test_target_mismatch_continue(self, mock_input): + with redirect_stdout(io.StringIO()): + validate_stack_target(make_pull_stack('lyrical', [1, 2]), 'rolling') + mock_input.assert_called_once() + + @patch('builtins.input') + def test_up_to_date(self, mock_input): + pull_stack = make_pull_stack('rolling', [1, 2, 3]) + pull_stack.repo.compare.return_value.status = 'ahead' + + validate_stack_up_to_date(pull_stack) + + pull_stack.repo.compare.assert_has_calls([call('sha-1', 'sha-3'), call('sha-2', 'sha-3')]) + mock_input.assert_not_called() + + @patch('builtins.input', return_value='n') + def test_not_up_to_date_abort(self, mock_input): + pull_stack = make_pull_stack('rolling', [1, 2, 3]) + # The top PR's branch does not contain the latest changes to the bottom PR's branch + pull_stack.repo.compare.side_effect = lambda base, head: MagicMock( + status='diverged' if base == 'sha-1' else 'ahead') + + with redirect_stdout(io.StringIO()) as stdout: + with self.assertRaisesRegex(RuntimeError, 'not up to date'): + validate_stack_up_to_date(pull_stack) + + self.assertIn('ros2/rviz#1:', stdout.getvalue()) + self.assertNotIn('ros2/rviz#2:', stdout.getvalue()) + + class TestParseArgs(unittest.TestCase): # Can't use --pulls and --interactive together @@ -104,6 +258,13 @@ def test_pulls_interactive_exclusive(self): with redirect_stderr(io.StringIO()), self.assertRaises(SystemExit): parse_args(['--pulls', 'ros2/rclcpp#1', '--interactive']) + # Can't use --stack with --pulls, --interactive, or --branch + def test_stack_exclusive(self): + for other_args in (['--pulls', 'ros2/rclcpp#1'], ['--interactive'], ['--branch', 'b']): + with self.subTest(other_args=other_args): + with redirect_stderr(io.StringIO()), self.assertRaises(SystemExit): + parse_args(['--stack', 'ros2/rviz#1915'] + other_args) + class TestCreateCIGist(unittest.TestCase):