From f82399f26331903692d9978b42dc3cfb3fa3ad92 Mon Sep 17 00:00:00 2001 From: Garrett Beaty Date: Wed, 3 Dec 2025 09:24:23 -0800 Subject: [PATCH] Cleanup bot_update TurboCI code. This adds and fixes documentation for the TurboCI check handler types and the turboci_check_id parameter to bot_update.ensure_checkout. Additionally, the gclient_config to _TurboCICheckHandler.create and _EnabledTurboCiCheckHandler.__init__ was removed because the gclient config wasn't being used. Bug: b:443496677 Change-Id: I4acc3170522735e63062bed47f555aabcd2a4304 Reviewed-on: https://chromium-review.googlesource.com/c/chromium/tools/depot_tools/+/7172970 Auto-Submit: Garrett Beaty Commit-Queue: Garrett Beaty Reviewed-by: Robbie Iannucci --- recipes/README.recipes.md | 16 +++---- recipes/recipe_modules/bot_update/api.py | 60 +++++++++++++++++++++--- 2 files changed, 62 insertions(+), 14 deletions(-) diff --git a/recipes/README.recipes.md b/recipes/README.recipes.md index eb56372240..118e25fd35 100644 --- a/recipes/README.recipes.md +++ b/recipes/README.recipes.md @@ -59,18 +59,18 @@ Recipe module to ensure a checkout is consistent on a bot. -#### **class [BotUpdateApi](/recipes/recipe_modules/bot_update/api.py#218)([RecipeApi][recipe_engine/wkt/RecipeApi]):** +#### **class [BotUpdateApi](/recipes/recipe_modules/bot_update/api.py#266)([RecipeApi][recipe_engine/wkt/RecipeApi]):** -— **def [\_\_call\_\_](/recipes/recipe_modules/bot_update/api.py#227)(self, name, cmd, \*\*kwargs):** +— **def [\_\_call\_\_](/recipes/recipe_modules/bot_update/api.py#275)(self, name, cmd, \*\*kwargs):** Wrapper for easy calling of bot_update. -— **def [deapply\_patch](/recipes/recipe_modules/bot_update/api.py#851)(self, bot_update_result):** +— **def [deapply\_patch](/recipes/recipe_modules/bot_update/api.py#899)(self, bot_update_result):** Deapplies a patch, taking care of DEPS and solution revisions properly. -— **def [ensure\_checkout](/recipes/recipe_modules/bot_update/api.py#338)(self, gclient_config=None, \*, suffix=None, patch=True, update_presentation=True, patch_root=None, with_branch_heads=False, with_tags=False, no_fetch_tags=False, refs=None, clobber=False, root_solution_revision=None, gerrit_no_reset=False, gerrit_no_rebase_patch_ref=False, assert_one_gerrit_change=True, patch_refs=None, ignore_input_commit=False, add_blamelists=False, set_output_commit=False, step_test_data=None, enforce_fetch=False, download_topics=False, recipe_revision_overrides=None, step_tags=None, clean_ignored=False, turboci_check_id: str='', \*\*kwargs):** +— **def [ensure\_checkout](/recipes/recipe_modules/bot_update/api.py#386)(self, gclient_config=None, \*, suffix=None, patch=True, update_presentation=True, patch_root=None, with_branch_heads=False, with_tags=False, no_fetch_tags=False, refs=None, clobber=False, root_solution_revision=None, gerrit_no_reset=False, gerrit_no_rebase_patch_ref=False, assert_one_gerrit_change=True, patch_refs=None, ignore_input_commit=False, add_blamelists=False, set_output_commit=False, step_test_data=None, enforce_fetch=False, download_topics=False, recipe_revision_overrides=None, step_tags=None, clean_ignored=False, turboci_check_id: str='', \*\*kwargs):** Args: * gclient_config: The gclient configuration to use when running bot_update. @@ -113,7 +113,7 @@ Args: if a non-empty value is provided and the gclient config doesn't have exactly 1 solution. -— **def [get\_project\_revision\_properties](/recipes/recipe_modules/bot_update/api.py#828)(self, project_name, gclient_config=None):** +— **def [get\_project\_revision\_properties](/recipes/recipe_modules/bot_update/api.py#876)(self, project_name, gclient_config=None):** Returns all property names used for storing the checked-out revision of a given project. @@ -127,14 +127,14 @@ Args: Returns (list of str): All properties that'll hold the checked-out revision of the given project. An empty list if no such properties exist. -  **@property**
— **def [last\_returned\_properties](/recipes/recipe_modules/bot_update/api.py#246)(self):** +  **@property**
— **def [last\_returned\_properties](/recipes/recipe_modules/bot_update/api.py#294)(self):** -— **def [resolve\_fixed\_revision](/recipes/recipe_modules/bot_update/api.py#779)(self, bot_update_result, name):** +— **def [resolve\_fixed\_revision](/recipes/recipe_modules/bot_update/api.py#827)(self, bot_update_result, name):** Sets a fixed revision for a single dependency using project revision properties. -— **def [step\_name](/recipes/recipe_modules/bot_update/api.py#868)(self, patch, suffix):** +— **def [step\_name](/recipes/recipe_modules/bot_update/api.py#916)(self, patch, suffix):** ### *recipe_modules* / [depot\_tools](/recipes/recipe_modules/depot_tools) [DEPS](/recipes/recipe_modules/depot_tools/__init__.py#6): [recipe\_engine/cipd][recipe_engine/recipe_modules/cipd], [recipe\_engine/context][recipe_engine/recipe_modules/context], [recipe\_engine/platform][recipe_engine/recipe_modules/platform], [recipe\_engine/runtime][recipe_engine/recipe_modules/runtime] diff --git a/recipes/recipe_modules/bot_update/api.py b/recipes/recipe_modules/bot_update/api.py index 1490dc1156..ea9ce3749b 100644 --- a/recipes/recipe_modules/bot_update/api.py +++ b/recipes/recipe_modules/bot_update/api.py @@ -70,19 +70,43 @@ class Result: class _TurboCICheckHandler(abc.ABC): + """Handler for creating and updating a TurboCI source check. + + Getting a handler should be done by calling + _TurboCICheckHandler.create with the ID to use for the check. An empty + check ID will result in a no-op handler. + + Before performing the checkout, set_revisions should be called to + provide information about the known revisions being checked out and if + a patch is being applied, set_gerrit_change should be called to + provide information about the change. After those calls are made, + create_check should be called to create the check in TurboCI. + + After performing the checkout, set_result should be called to write + results into the check and finalize it. + """ @staticmethod - def create(api, check_id: str, gclient_config): + def create(api, check_id: str): + """Create a _TurboCiCheckHandler. + + Args: + check_id: The ID of the TurboCI check that the handler should + create. If empty, a no-op handler will be returned. + """ if not check_id: return _DisabledTurboCICheckHandler() - return _EnabledTurboCiCheckHandler(api, check_id, gclient_config) + return _EnabledTurboCiCheckHandler(api, check_id) @abc.abstractmethod def set_gerrit_change(self, gerrit_change: common_pb2.GerritChange, patch_root: str) -> None: """Sets the gerrit change that is being checked out. + Information about the change will be added to the check that is + created. + Args: gerrit_change: The gerrit change that is being checked out. patch_root: The path to the repository that is being patched, @@ -96,14 +120,39 @@ class _TurboCICheckHandler(abc.ABC): revisions: collections.abc.Mapping[str, str], refs: collections.abc.Mapping[str, str], ) -> None: + """Set the revisions to be checked out. + + Information about the revisions will be added to the check that is + created. + + Args: + revisions: Mapping from the solution name/checkout-relative path + of a repo to the revision that the repo will be checked out + from. + refs: Mapping from the solution name/checkout-relative path of a + repo to the ref that the repo will be checked out from. + """ raise NotImplementedError() # pragma: no cover @abc.abstractmethod def create_check(self) -> None: + """Create the TurboCI check. + + A check will be created with kind SOURCE and state PLANNED. The + check will contain a GobSourceCheckOptions option that contains the + revision information specified by set_revisions and the change + information specified by set_gerrit_change. + """ raise NotImplementedError() # pragma: no cover @abc.abstractmethod def set_result(self, result: Result) -> None: + """Set the results on the TurboCI check. + + The check will have a GobSourceCheckResults result added that + contains details about the change that was applied (if any) and be + moved to the FINAL state. + """ raise NotImplementedError() # pragma: no cover @@ -129,12 +178,11 @@ class _DisabledTurboCICheckHandler(_TurboCICheckHandler): class _EnabledTurboCiCheckHandler(_TurboCICheckHandler): - """A no-op implementation of _TurboCICheckHandler.""" + """_TurboCICheckHandler that actually creates a check in TurboCI.""" - def __init__(self, api, check_id: str, gclient_config): + def __init__(self, api, check_id: str): self._api = api self._check_id = check_id - self._gclient_config = gclient_config self._gerrit_change: common_pb2.GerritChange | None = None self._source_check_options = GobSourceCheckOptions() @@ -418,7 +466,7 @@ class BotUpdateApi(recipe_api.RecipeApi): assert cfg is not None, ( 'missing gclient_config or forgot api.gclient.set_config(...) before?') - check_handler = _TurboCICheckHandler.create(self, turboci_check_id, cfg) + check_handler = _TurboCICheckHandler.create(self, turboci_check_id) # Construct our bot_update command. This basically be inclusive of # everything required for bot_update to know: