recipe: introduce add_message api

Bug: 378480632
Change-Id: Idcd9decbf965cb9985d48a716e14473cb6ff7579
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/tools/depot_tools/+/6012778
Reviewed-by: Scott Lee <ddoman@chromium.org>
Commit-Queue: Scott Lee <ddoman@chromium.org>
Auto-Submit: Yiwei Zhang <yiwzhang@google.com>

recipes/README.recipes.md

@@ -274,38 +274,55 @@ revision map. This doesn't overwrite the revision if it was already set.
 [DEPS](/recipes/recipe_modules/gerrit/__init__.py#3): [recipe\_engine/context][recipe_engine/recipe_modules/context], [recipe\_engine/file][recipe_engine/recipe_modules/file], [recipe\_engine/json][recipe_engine/recipe_modules/json], [recipe\_engine/path][recipe_engine/recipe_modules/path], [recipe\_engine/raw\_io][recipe_engine/recipe_modules/raw_io], [recipe\_engine/step][recipe_engine/recipe_modules/step], [recipe\_engine/time][recipe_engine/recipe_modules/time]
 
 
-#### **class [GerritApi](/recipes/recipe_modules/gerrit/api.py#7)([RecipeApi][recipe_engine/wkt/RecipeApi]):**
+#### **class [GerritApi](/recipes/recipe_modules/gerrit/api.py#9)([RecipeApi][recipe_engine/wkt/RecipeApi]):**
 
 Module for interact with Gerrit endpoints
 
-— **def [\_\_call\_\_](/recipes/recipe_modules/gerrit/api.py#14)(self, name, cmd, infra_step=True, \*\*kwargs):**
+— **def [\_\_call\_\_](/recipes/recipe_modules/gerrit/api.py#16)(self, name, cmd, infra_step=True, \*\*kwargs):**
 
 Wrapper for easy calling of gerrit_utils steps.
 
-— **def [abandon\_change](/recipes/recipe_modules/gerrit/api.py#260)(self, host, change, message=None, name=None, step_test_data=None):**
+— **def [abandon\_change](/recipes/recipe_modules/gerrit/api.py#262)(self, host, change, message=None, name=None, step_test_data=None):**
 
-— **def [call\_raw\_api](/recipes/recipe_modules/gerrit/api.py#31)(self, host, path, method=None, body=None, accept_statuses=None, name=None, \*\*kwargs):**
+— **def [add\_message](/recipes/recipe_modules/gerrit/api.py#320)(self, host: str, change: int, message: str, revision: (str | int)='current', step_name: str=None, step_test_data: (Callable[([], StepTestData)] | None)=None):**
+
+Add a message to a change at given revision.
+
+Args:
+  * host: URL of Gerrit host of the change.
+  * change: The ID of the change to add message to as documented here:
+      https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#change-id
+  * message: The content of the message to add to the change.
+  * revision: The ID of the revision of change to add message to as
+      documented here:
+      https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#revision-id
+      This defaults to current, which names the most recent patchset.
+  * step_name: Optional step name.
+  * step_test_data: Optional mock test data for the underlying gerrit
+      client.
+
+— **def [call\_raw\_api](/recipes/recipe_modules/gerrit/api.py#33)(self, host, path, method=None, body=None, accept_statuses=None, name=None, \*\*kwargs):**
 
 Call an arbitrary Gerrit API that returns a JSON response.
 
 Returns:
   The JSON response data.
 
-— **def [create\_gerrit\_branch](/recipes/recipe_modules/gerrit/api.py#60)(self, host, project, branch, commit, \*\*kwargs):**
+— **def [create\_gerrit\_branch](/recipes/recipe_modules/gerrit/api.py#62)(self, host, project, branch, commit, \*\*kwargs):**
 
 Creates a new branch from given project and commit
 
 Returns:
   The ref of the branch created
 
-— **def [create\_gerrit\_tag](/recipes/recipe_modules/gerrit/api.py#82)(self, host, project, tag, commit, \*\*kwargs):**
+— **def [create\_gerrit\_tag](/recipes/recipe_modules/gerrit/api.py#84)(self, host, project, tag, commit, \*\*kwargs):**
 
 Creates a new tag at the given commit.
 
 Returns:
   The ref of the tag created.
 
-— **def [get\_change\_description](/recipes/recipe_modules/gerrit/api.py#121)(self, host, change, patchset, timeout=None, step_test_data=None):**
+— **def [get\_change\_description](/recipes/recipe_modules/gerrit/api.py#123)(self, host, change, patchset, timeout=None, step_test_data=None):**
 
 Gets the description for a given CL and patchset.
 
@@ -317,7 +334,7 @@ Args:
 Returns:
   The description corresponding to given CL and patchset.
 
-— **def [get\_changes](/recipes/recipe_modules/gerrit/api.py#181)(self, host, query_params, start=None, limit=None, o_params=None, step_test_data=None, \*\*kwargs):**
+— **def [get\_changes](/recipes/recipe_modules/gerrit/api.py#183)(self, host, query_params, start=None, limit=None, o_params=None, step_test_data=None, \*\*kwargs):**
 
 Queries changes for the given host.
 
@@ -336,14 +353,14 @@ Returns:
   A list of change dicts as documented here:
       https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#list-changes
 
-— **def [get\_gerrit\_branch](/recipes/recipe_modules/gerrit/api.py#103)(self, host, project, branch, \*\*kwargs):**
+— **def [get\_gerrit\_branch](/recipes/recipe_modules/gerrit/api.py#105)(self, host, project, branch, \*\*kwargs):**
 
 Gets a branch from given project and commit
 
 Returns:
   The revision of the branch
 
-— **def [get\_related\_changes](/recipes/recipe_modules/gerrit/api.py#224)(self, host, change, revision='current', step_test_data=None):**
+— **def [get\_related\_changes](/recipes/recipe_modules/gerrit/api.py#226)(self, host, change, revision='current', step_test_data=None):**
 
 Queries related changes for a given host, change, and revision.
 
@@ -362,7 +379,7 @@ Returns:
   A related changes dictionary as documented here:
       https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#related-changes-info
 
-— **def [get\_revision\_info](/recipes/recipe_modules/gerrit/api.py#140)(self, host, change, patchset, timeout=None, step_test_data=None):**
+— **def [get\_revision\_info](/recipes/recipe_modules/gerrit/api.py#142)(self, host, change, patchset, timeout=None, step_test_data=None):**
 
 Returns the info for a given patchset of a given change.
 
@@ -375,13 +392,13 @@ Returns:
   A dict for the target revision as documented here:
       https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#list-changes
 
-— **def [move\_changes](/recipes/recipe_modules/gerrit/api.py#318)(self, host, project, from_branch, to_branch, step_test_data=None):**
+— **def [move\_changes](/recipes/recipe_modules/gerrit/api.py#357)(self, host, project, from_branch, to_branch, step_test_data=None):**
 
-— **def [restore\_change](/recipes/recipe_modules/gerrit/api.py#280)(self, host, change, message=None, name=None, step_test_data=None):**
+— **def [restore\_change](/recipes/recipe_modules/gerrit/api.py#282)(self, host, change, message=None, name=None, step_test_data=None):**
 
-— **def [set\_change\_label](/recipes/recipe_modules/gerrit/api.py#300)(self, host, change, label_name, label_value, name=None, step_test_data=None):**
+— **def [set\_change\_label](/recipes/recipe_modules/gerrit/api.py#302)(self, host, change, label_name, label_value, name=None, step_test_data=None):**
 
-— **def [update\_files](/recipes/recipe_modules/gerrit/api.py#342)(self, host, project, branch, new_contents_by_file_path, commit_msg, params=frozenset(['status=NEW']), cc_list=frozenset([]), submit=False, submit_later=False, step_test_data_create_change=None, step_test_data_submit_change=None):**
+— **def [update\_files](/recipes/recipe_modules/gerrit/api.py#381)(self, host, project, branch, new_contents_by_file_path, commit_msg, params=frozenset(['status=NEW']), cc_list=frozenset([]), submit=False, submit_later=False, step_test_data_create_change=None, step_test_data_submit_change=None):**
 
 Update a set of files by creating and submitting a Gerrit CL.
 
@@ -1099,10 +1116,10 @@ Raises:
 — **def [RunSteps](/recipes/recipe_modules/gclient/tests/sync_failure.py#15)(api):**
 ### *recipes* / [gerrit:examples/full](/recipes/recipe_modules/gerrit/examples/full.py)
 
-[DEPS](/recipes/recipe_modules/gerrit/examples/full.py#7): [gerrit](#recipe_modules-gerrit), [recipe\_engine/step][recipe_engine/recipe_modules/step]
+[DEPS](/recipes/recipe_modules/gerrit/examples/full.py#7): [gerrit](#recipe_modules-gerrit), [recipe\_engine/json][recipe_engine/recipe_modules/json], [recipe\_engine/step][recipe_engine/recipe_modules/step]
 
 
-— **def [RunSteps](/recipes/recipe_modules/gerrit/examples/full.py#13)(api):**
+— **def [RunSteps](/recipes/recipe_modules/gerrit/examples/full.py#14)(api):**
 ### *recipes* / [git:examples/full](/recipes/recipe_modules/git/examples/full.py)
 
 [DEPS](/recipes/recipe_modules/git/examples/full.py#7): [git](#recipe_modules-git), [recipe\_engine/buildbucket][recipe_engine/recipe_modules/buildbucket], [recipe\_engine/context][recipe_engine/recipe_modules/context], [recipe\_engine/path][recipe_engine/recipe_modules/path], [recipe\_engine/platform][recipe_engine/recipe_modules/platform], [recipe\_engine/properties][recipe_engine/recipe_modules/properties], [recipe\_engine/raw\_io][recipe_engine/recipe_modules/raw_io], [recipe\_engine/step][recipe_engine/recipe_modules/step]

recipes/recipe_modules/gerrit/api.py

@@ -3,6 +3,8 @@
 # found in the LICENSE file.
 
 from recipe_engine import recipe_api
+from recipe_engine.recipe_test_api import StepTestData
+from typing import Callable
 
 class GerritApi(recipe_api.RecipeApi):
   """Module for interact with Gerrit endpoints"""
@@ -315,6 +317,43 @@ class GerritApi(recipe_api.RecipeApi):
         step_test_data=step_test_data,
     ).json.output
 
+  def add_message(
+      self,
+      host: str,
+      change: int,
+      message: str,
+      revision: str | int = 'current',
+      step_name: str = None,
+      step_test_data: Callable[[], StepTestData] | None = None) -> None:
+    """Add a message to a change at given revision.
+
+    Args:
+      * host: URL of Gerrit host of the change.
+      * change: The ID of the change to add message to as documented here:
+          https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#change-id
+      * message: The content of the message to add to the change.
+      * revision: The ID of the revision of change to add message to as
+          documented here:
+          https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#revision-id
+          This defaults to current, which names the most recent patchset.
+      * step_name: Optional step name.
+      * step_test_data: Optional mock test data for the underlying gerrit
+          client.
+    """
+    args = [
+        'addmessage', '--host', host, '--change',
+        int(change), '--revision',
+        str(revision), '--message', message, '--json_file',
+        self.m.json.output()
+    ]
+    if not step_test_data:
+      step_test_data = lambda: self.m.json.test_api.output({})
+    return self(
+        step_name or 'add message',
+        args,
+        step_test_data=step_test_data,
+    ).json.output
+
   def move_changes(self,
                    host,
                    project,

recipes/recipe_modules/gerrit/examples/full.expected/basic.json

@@ -652,6 +652,32 @@
       "@@@STEP_LOG_END@json.output (exception)@@@"
     ]
   },
+  {
+    "cmd": [
+      "vpython3",
+      "RECIPE_REPO[depot_tools]/gerrit_client.py",
+      "addmessage",
+      "--host",
+      "https://chromium-review.googlesource.com",
+      "--change",
+      "123",
+      "--revision",
+      "current",
+      "--message",
+      "This is a comment message",
+      "--json_file",
+      "/path/to/tmp/json"
+    ],
+    "env": {
+      "PATH": "<PATH>:RECIPE_REPO[depot_tools]"
+    },
+    "infra_step": true,
+    "name": "gerrit add message",
+    "~followup_annotations": [
+      "@@@STEP_LOG_LINE@json.output@{}@@@",
+      "@@@STEP_LOG_END@json.output@@@"
+    ]
+  },
   {
     "cmd": [
       "vpython3",

recipes/recipe_modules/gerrit/examples/full.py

@@ -6,6 +6,7 @@ PYTHON_VERSION_COMPATIBILITY = 'PY3'
 
 DEPS = [
     'gerrit',
+    'recipe_engine/json',
     'recipe_engine/step',
 ]
 
@@ -87,6 +88,8 @@ def RunSteps(api):
   api.gerrit.set_change_label(host, 123, 'code-review', -1)
   api.gerrit.set_change_label(host, 123, 'commit-queue', 1)
 
+  api.gerrit.add_message(host, 123, 'This is a comment message')
+
   api.gerrit.abandon_change(host, 123, 'bad roll')
   api.gerrit.restore_change(host, 123, 'nevermind')