From a5ee5779a2a06f1a3dd87f33d3d1c6b59ddecad1 Mon Sep 17 00:00:00 2001
From: Saquib Mian <smian@buf.build>
Date: Tue, 14 Nov 2023 16:59:30 -0500
Subject: [PATCH] PR comments

---
 buf/registry/module/v1beta1/tag_service.proto | 67 ++++++++++++-------
 1 file changed, 42 insertions(+), 25 deletions(-)

diff --git a/buf/registry/module/v1beta1/tag_service.proto b/buf/registry/module/v1beta1/tag_service.proto
index 52f726b..9ab02e0 100644
--- a/buf/registry/module/v1beta1/tag_service.proto
+++ b/buf/registry/module/v1beta1/tag_service.proto
@@ -39,10 +39,10 @@ service TagService {
   rpc CreateTags(CreateTagsRequest) returns (CreateTagsResponse) {
     option idempotency_level = IDEMPOTENT;
   }
-  // Move existing Tags on a Module.
+  // Create new Tags on a Module, and Update existing Tags on a Module.
   //
-  // This operation is atomic. Either all Tags are moved or an error is returned.
-  rpc MoveTags(MoveTagsRequest) returns (MoveTagsResponse) {
+  // This operation is atomic. Either all Tags are created/updated or an error is returned.
+  rpc CreateOrUpdateTags(CreateOrUpdateTagsRequest) returns (CreateOrUpdateTagsResponse) {
     option idempotency_level = IDEMPOTENT;
   }
   // Delete existing Tags.
@@ -101,18 +101,26 @@ message ListTagsResponse {
 message CreateTagsRequest {
   // An individual request to create a Tag.
   message Value {
-    // The Module to create the Tag under.
-    ModuleRef module_ref = 1 [(buf.validate.field).required = true];
     // The Tag name.
-    string name = 2 [
+    //
+    // If there is already a Tag with a name, the request errors. Otherwise, a new Tag will be
+    // created associated with the commit identified.
+    repeated string name = 1 [
       (buf.validate.field).required = true,
       (buf.validate.field).string.max_len = 250
     ];
-    // The id of the Commit associated with the Tag.
-    string commit_id = 3 [
-      (buf.validate.field).required = true,
-      (buf.validate.field).string.uuid = true
-    ];
+    // The reference to resolve the Commit to which these Tags will be set.
+    //
+    // See the documentation on Ref for resource resolution details.
+    //
+    // The Tags are set depending on the kind of resource that is resolved:
+    //   - If a Module is referenced, Tags are set to the latest released Commit in the module.
+    //   - If a Commit is referenced, Tags are set for that Commit.
+    //   - If a Tag is referenced, Tags are set for the Commit that this Tag references.
+    //   - If a VCSCommit is referenced, Tags are set for the Commit that this VCSCommit references.
+    //   - Is a Branch is referenced, Tags are set for the latest Commit on the Branch.
+    //   - If a Digest is referenced, Tags are set for the most recent Commit with this Digest.
+    ResourceRef resource_ref = 2 [(buf.validate.field).required = true];
   }
   // The Tags to create.
   repeated Value values = 1 [
@@ -126,31 +134,40 @@ message CreateTagsResponse {
   repeated Tag tags = 1 [(buf.validate.field).repeated.min_items = 1];
 }
 
-message MoveTagsRequest {
-  // An individual request to move a Tag.
+message CreateOrUpdateTagsRequest {
+  // An individual request to create or update a Tag.
   message Value {
-    // The Module associated with the Tag.
-    ModuleRef module_ref = 1 [(buf.validate.field).required = true];
-    // The Tag name.
-    string name = 2 [
+    // The Tag names.
+    //
+    // If there is already a Tag with a name, it will be updated to be associated with
+    // the commit identified. Otherwise, a new Tag will be created associated with the
+    // commit identified.
+    repeated string name = 1 [
       (buf.validate.field).required = true,
       (buf.validate.field).string.max_len = 250
     ];
-    // The id of the Commit to associate with the Tag.
-    string commit_id = 3 [
-      (buf.validate.field).required = true,
-      (buf.validate.field).string.uuid = true
-    ];
+    // The reference to resolve the Commit to which these Tags will be set.
+    //
+    // See the documentation on Ref for resource resolution details.
+    //
+    // The Tags are set depending on the kind of resource that is resolved:
+    //   - If a Module is referenced, Tags are set to the latest released Commit in the module.
+    //   - If a Commit is referenced, Tags are set for that Commit.
+    //   - If a Tag is referenced, Tags are set for the Commit that this Tag references.
+    //   - If a VCSCommit is referenced, Tags are set for the Commit that this VCSCommit references.
+    //   - Is a Branch is referenced, Tags are set for the latest Commit on the Branch.
+    //   - If a Digest is referenced, Tags are set for the most recent Commit with this Digest.
+    ResourceRef resource_ref = 2 [(buf.validate.field).required = true];
   }
-  // The Tags to move.
+  // The Tags to create or update.
   repeated Value values = 1 [
     (buf.validate.field).repeated.min_items = 1,
     (buf.validate.field).repeated.max_items = 250
   ];
 }
 
-message MoveTagsResponse {
-  // The moved Tags in the same order as given on the request.
+message CreateOrUpdateTagsResponse {
+  // The created or updated Tags in the same order as given on the request.
   repeated Tag tags = 1 [(buf.validate.field).repeated.min_items = 1];
 }