proto: Enforce comment-linting for enum definitions

Enforce that enum definitions must have a comment and add a placeholder
for all instances where such a comment is missing.

21 files changed, 77 insertions, 32 deletions

diff --git a/proto/.protolint.yaml b/proto/.protolint.yaml
index a4fac009f..9d29ed88f 100644
--- a/proto/.protolint.yaml
+++ b/proto/.protolint.yaml
@@ -15,7 +15,6 @@ lint:
       # get protolint included in our workflow with minimal required changes.
       - FILE_HAS_COMMENT
       - FIELDS_HAVE_COMMENT
-      - ENUMS_HAVE_COMMENT
       - ENUM_FIELDS_HAVE_COMMENT
       # Many of our fields and messages have prepositions in them, and
       # furthermore this rule doesn't feel all that sensible after all. We thus
diff --git a/proto/commit.proto b/proto/commit.proto
index df90e0fb6..5462fc5d7 100644
--- a/proto/commit.proto
+++ b/proto/commit.proto
@@ -387,16 +387,16 @@ message TreeEntry {
 
 // This comment is left unintentionally blank.
 message GetTreeEntriesRequest {
-  Repository repository = 1 [(target_repository)=true];
-  bytes revision = 2;
-  bytes path = 3;
-  bool recursive = 4;
-
+  // This comment is left unintentionally blank.
   enum SortBy {
     DEFAULT = 0; // Preserve order of git ls-tree
     TREES_FIRST = 1; // trees, blobs, submodules
   }
 
+  Repository repository = 1 [(target_repository)=true];
+  bytes revision = 2;
+  bytes path = 3;
+  bool recursive = 4;
   SortBy sort = 5;
   // The page token is the last commit OID that was sent. It's expected to be the
   // full object ID to guard against ambigious OIDs.
@@ -467,16 +467,18 @@ message ListCommitsByRefNameResponse {
 
 // This comment is left unintentionally blank.
 message FindAllCommitsRequest {
-  Repository repository = 1 [(target_repository)=true];
-  // When nil, return all commits reachable by any branch in the repo
-  bytes revision = 2;
-  int32 max_count = 3;
-  int32 skip = 4;
+  // This comment is left unintentionally blank.
   enum Order {
     NONE = 0;
     TOPO = 1;
     DATE = 2;
   }
+
+  Repository repository = 1 [(target_repository)=true];
+  // When nil, return all commits reachable by any branch in the repo
+  bytes revision = 2;
+  int32 max_count = 3;
+  int32 skip = 4;
   Order order = 5;
 }
 
@@ -487,6 +489,12 @@ message FindAllCommitsResponse {
 
 // This comment is left unintentionally blank.
 message FindCommitsRequest {
+  // This comment is left unintentionally blank.
+  enum Order {
+    NONE = 0;
+    TOPO = 1;
+  }
+
   Repository repository = 1 [(target_repository)=true];
   bytes revision = 2;
   int32 limit = 3;
@@ -501,10 +509,6 @@ message FindCommitsRequest {
   bool all = 11;
   bool first_parent = 12;
   bytes author = 13;
-  enum Order {
-    NONE = 0;
-    TOPO = 1;
-  }
   Order order = 14;
   GlobalOptions global_options = 15;
   bool trailers = 16;
diff --git a/proto/diff.proto b/proto/diff.proto
index c06f655d4..9ca0d7c13 100644
--- a/proto/diff.proto
+++ b/proto/diff.proto
@@ -57,6 +57,7 @@ service DiffService {
 
 // This comment is left unintentionally blank.
 message CommitDiffRequest {
+  // This comment is left unintentionally blank.
   enum DiffMode {
     // DEFAULT is the standard diff mode and results in a linewise diff for textfiles.
     DEFAULT = 0;
@@ -198,6 +199,7 @@ message FindChangedPathsResponse {
 
 // Includes the path of the file, and the status of the change
 message ChangedPaths {
+  // This comment is left unintentionally blank.
   enum Status {
     ADDED = 0;
     MODIFIED = 1;
diff --git a/proto/go/gitalypb/commit.pb.go b/proto/go/gitalypb/commit.pb.go
index c53f468a5..9cb3edc7c 100644
--- a/proto/go/gitalypb/commit.pb.go
+++ b/proto/go/gitalypb/commit.pb.go
@@ -181,6 +181,7 @@ func (TreeEntry_EntryType) EnumDescriptor() ([]byte, []int) {
 	return file_commit_proto_rawDescGZIP(), []int{14, 0}
 }
 
+// This comment is left unintentionally blank.
 type GetTreeEntriesRequest_SortBy int32
 
 const (
@@ -227,6 +228,7 @@ func (GetTreeEntriesRequest_SortBy) EnumDescriptor() ([]byte, []int) {
 	return file_commit_proto_rawDescGZIP(), []int{15, 0}
 }
 
+// This comment is left unintentionally blank.
 type FindAllCommitsRequest_Order int32
 
 const (
@@ -276,6 +278,7 @@ func (FindAllCommitsRequest_Order) EnumDescriptor() ([]byte, []int) {
 	return file_commit_proto_rawDescGZIP(), []int{25, 0}
 }
 
+// This comment is left unintentionally blank.
 type FindCommitsRequest_Order int32
 
 const (
diff --git a/proto/go/gitalypb/diff.pb.go b/proto/go/gitalypb/diff.pb.go
index 1ab7243fc..8cc86c4d3 100644
--- a/proto/go/gitalypb/diff.pb.go
+++ b/proto/go/gitalypb/diff.pb.go
@@ -20,6 +20,7 @@ const (
 	_ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20)
 )
 
+// This comment is left unintentionally blank.
 type CommitDiffRequest_DiffMode int32
 
 const (
@@ -68,6 +69,7 @@ func (CommitDiffRequest_DiffMode) EnumDescriptor() ([]byte, []int) {
 	return file_diff_proto_rawDescGZIP(), []int{0, 0}
 }
 
+// This comment is left unintentionally blank.
 type ChangedPaths_Status int32
 
 const (
diff --git a/proto/go/gitalypb/hook.pb.go b/proto/go/gitalypb/hook.pb.go
index 3c36fc08b..2c274a694 100644
--- a/proto/go/gitalypb/hook.pb.go
+++ b/proto/go/gitalypb/hook.pb.go
@@ -20,6 +20,7 @@ const (
 	_ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20)
 )
 
+// This comment is left unintentionally blank.
 type ReferenceTransactionHookRequest_State int32
 
 const (
diff --git a/proto/go/gitalypb/lint.pb.go b/proto/go/gitalypb/lint.pb.go
index b204d5dea..5d462c426 100644
--- a/proto/go/gitalypb/lint.pb.go
+++ b/proto/go/gitalypb/lint.pb.go
@@ -21,6 +21,7 @@ const (
 	_ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20)
 )
 
+// This comment is left unintentionally blank.
 type OperationMsg_Operation int32
 
 const (
@@ -73,6 +74,7 @@ func (OperationMsg_Operation) EnumDescriptor() ([]byte, []int) {
 	return file_lint_proto_rawDescGZIP(), []int{0, 0}
 }
 
+// This comment is left unintentionally blank.
 type OperationMsg_Scope int32
 
 const (
diff --git a/proto/go/gitalypb/operations.pb.go b/proto/go/gitalypb/operations.pb.go
index bac60b307..d47e55a73 100644
--- a/proto/go/gitalypb/operations.pb.go
+++ b/proto/go/gitalypb/operations.pb.go
@@ -131,6 +131,7 @@ func (UserRevertResponse_CreateTreeError) EnumDescriptor() ([]byte, []int) {
 	return file_operations_proto_rawDescGZIP(), []int{22, 0}
 }
 
+// This comment is left unintentionally blank.
 type UserCommitFilesActionHeader_ActionType int32
 
 const (
diff --git a/proto/go/gitalypb/ref.pb.go b/proto/go/gitalypb/ref.pb.go
index b5aeb9561..67cb0cc94 100644
--- a/proto/go/gitalypb/ref.pb.go
+++ b/proto/go/gitalypb/ref.pb.go
@@ -21,6 +21,7 @@ const (
 	_ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20)
 )
 
+// This comment is left unintentionally blank.
 type FindLocalBranchesRequest_SortBy int32
 
 const (
@@ -117,6 +118,7 @@ func (FindAllTagsRequest_SortBy_Key) EnumDescriptor() ([]byte, []int) {
 	return file_ref_proto_rawDescGZIP(), []int{14, 0, 0}
 }
 
+// This comment is left unintentionally blank.
 type CreateBranchResponse_Status int32
 
 const (
@@ -169,6 +171,7 @@ func (CreateBranchResponse_Status) EnumDescriptor() ([]byte, []int) {
 	return file_ref_proto_rawDescGZIP(), []int{19, 0}
 }
 
+// This comment is left unintentionally blank.
 type ListRefsRequest_SortBy_Key int32
 
 const (
diff --git a/proto/go/gitalypb/repository.pb.go b/proto/go/gitalypb/repository.pb.go
index a55198563..18a315209 100644
--- a/proto/go/gitalypb/repository.pb.go
+++ b/proto/go/gitalypb/repository.pb.go
@@ -20,6 +20,7 @@ const (
 	_ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20)
 )
 
+// This comment is left unintentionally blank.
 type WriteCommitGraphRequest_SplitStrategy int32
 
 const (
@@ -66,6 +67,7 @@ func (WriteCommitGraphRequest_SplitStrategy) EnumDescriptor() ([]byte, []int) {
 	return file_repository_proto_rawDescGZIP(), []int{10, 0}
 }
 
+// This comment is left unintentionally blank.
 type GetArchiveRequest_Format int32
 
 const (
@@ -118,6 +120,7 @@ func (GetArchiveRequest_Format) EnumDescriptor() ([]byte, []int) {
 	return file_repository_proto_rawDescGZIP(), []int{24, 0}
 }
 
+// This comment is left unintentionally blank.
 type GetRawChangesResponse_RawChange_Operation int32
 
 const (
diff --git a/proto/go/gitalypb/shared.pb.go b/proto/go/gitalypb/shared.pb.go
index 30255aa4c..3976c354c 100644
--- a/proto/go/gitalypb/shared.pb.go
+++ b/proto/go/gitalypb/shared.pb.go
@@ -21,6 +21,7 @@ const (
 	_ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20)
 )
 
+// This comment is left unintentionally blank.
 type ObjectType int32
 
 const (
@@ -76,6 +77,7 @@ func (ObjectType) EnumDescriptor() ([]byte, []int) {
 	return file_shared_proto_rawDescGZIP(), []int{0}
 }
 
+// This comment is left unintentionally blank.
 type SignatureType int32
 
 const (
diff --git a/proto/go/gitalypb/transaction.pb.go b/proto/go/gitalypb/transaction.pb.go
index e9cbc2ea0..0b358fd5f 100644
--- a/proto/go/gitalypb/transaction.pb.go
+++ b/proto/go/gitalypb/transaction.pb.go
@@ -20,6 +20,7 @@ const (
 	_ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20)
 )
 
+// This comment is left unintentionally blank.
 type VoteTransactionRequest_Phase int32
 
 const (
diff --git a/proto/go/gitalypb/wiki.pb.go b/proto/go/gitalypb/wiki.pb.go
index 6e3318ed2..b4255679b 100644
--- a/proto/go/gitalypb/wiki.pb.go
+++ b/proto/go/gitalypb/wiki.pb.go
@@ -20,6 +20,7 @@ const (
 	_ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20)
 )
 
+// This comment is left unintentionally blank.
 type WikiGetAllPagesRequest_SortBy int32
 
 const (
@@ -66,6 +67,7 @@ func (WikiGetAllPagesRequest_SortBy) EnumDescriptor() ([]byte, []int) {
 	return file_wiki_proto_rawDescGZIP(), []int{9, 0}
 }
 
+// This comment is left unintentionally blank.
 type WikiListPagesRequest_SortBy int32
 
 const (
diff --git a/proto/hook.proto b/proto/hook.proto
index b132ebcfb..84ed1caac 100644
--- a/proto/hook.proto
+++ b/proto/hook.proto
@@ -98,14 +98,16 @@ message UpdateHookResponse{
 
 // This comment is left unintentionally blank.
 message ReferenceTransactionHookRequest {
-  Repository repository = 1 [(target_repository)=true];
-  repeated string environment_variables = 2;
-  bytes stdin = 3;
+  // This comment is left unintentionally blank.
   enum State {
     PREPARED = 0;
     COMMITTED = 1;
     ABORTED = 2;
   }
+
+  Repository repository = 1 [(target_repository)=true];
+  repeated string environment_variables = 2;
+  bytes stdin = 3;
   State state = 4;
 }
 
diff --git a/proto/lint.proto b/proto/lint.proto
index 41240243b..cec0141b4 100644
--- a/proto/lint.proto
+++ b/proto/lint.proto
@@ -8,6 +8,7 @@ option go_package = "gitlab.com/gitlab-org/gitaly/v14/proto/go/gitalypb";
 
 // This comment is left unintentionally blank.
 message OperationMsg {
+  // This comment is left unintentionally blank.
   enum Operation {
     UNKNOWN = 0;
     MUTATOR = 1;
@@ -15,8 +16,7 @@ message OperationMsg {
     MAINTENANCE = 3;
   }
 
-  Operation op = 1;
-
+  // This comment is left unintentionally blank.
   enum Scope {
     REPOSITORY = 0;
     STORAGE = 2;
@@ -25,6 +25,9 @@ message OperationMsg {
     reserved "SERVER";
   }
 
+
+  Operation op = 1;
+
   // Scope level indicates what level an RPC interacts with a server:
   //   - REPOSITORY: scoped to only a single repo
   //   - SERVER: affects the entire server and potentially all repos
diff --git a/proto/operations.proto b/proto/operations.proto
index 91e3f59ac..b415ec16d 100644
--- a/proto/operations.proto
+++ b/proto/operations.proto
@@ -500,6 +500,7 @@ message UserRevertResponse {
 
 // UserCommitFilesActionHeader contains the details of the action to be performed.
 message UserCommitFilesActionHeader {
+  // This comment is left unintentionally blank.
   enum ActionType {
     // CREATE creates a new file.
     CREATE = 0;
@@ -514,6 +515,7 @@ message UserCommitFilesActionHeader {
     // CHMOD changes the permissions of an existing file.
     CHMOD = 5;
   }
+
   // action is the type of the action taken to build a commit. Not all fields are
   // used for all of the actions.
   ActionType action = 1;
diff --git a/proto/ref.proto b/proto/ref.proto
index 21a3e15a3..6c4417366 100644
--- a/proto/ref.proto
+++ b/proto/ref.proto
@@ -181,12 +181,14 @@ message FindAllTagNamesResponse {
 
 // This comment is left unintentionally blank.
 message FindLocalBranchesRequest {
-  Repository repository = 1 [(target_repository)=true];
+  // This comment is left unintentionally blank.
   enum SortBy {
     NAME = 0;
     UPDATED_ASC = 1;
     UPDATED_DESC = 2;
   }
+
+  Repository repository = 1 [(target_repository)=true];
   SortBy sort_by = 2;
   // The page token is the branch name, with the `refs/heads/` prefix, for
   // example "refs/heads/master". After the first branch name is encountered
@@ -299,12 +301,14 @@ message CreateBranchRequest {
 
 // This comment is left unintentionally blank.
 message CreateBranchResponse {
+  // This comment is left unintentionally blank.
   enum Status {
     OK = 0;
     ERR_EXISTS = 1;
     ERR_INVALID = 2;
     ERR_INVALID_START_POINT = 3;
   }
+
   Status status = 1;
   Branch branch = 2;
 }
@@ -466,6 +470,7 @@ message ListRefsRequest {
 
   // This comment is left unintentionally blank.
   message SortBy {
+    // This comment is left unintentionally blank.
     enum Key {
       REFNAME       = 0;
       CREATORDATE   = 1;
diff --git a/proto/repository.proto b/proto/repository.proto
index 2f2a6820c..31fb59e83 100644
--- a/proto/repository.proto
+++ b/proto/repository.proto
@@ -386,12 +386,14 @@ message GarbageCollectResponse {
 
 // This comment is left unintentionally blank.
 message WriteCommitGraphRequest {
+  // This comment is left unintentionally blank.
   enum SplitStrategy {
     // SizeMultiple requires to use '--split --size-multiple=4' strategy to create/update commit graph.
     // https://git-scm.com/docs/git-commit-graph#Documentation/git-commit-graph.txt-emwriteem
     // It is a default, there is no need to explicitly set it in the request.
     SizeMultiple = 0; // protolint:disable:this ENUM_FIELD_NAMES_UPPER_SNAKE_CASE
   }
+
   Repository repository = 1 [(target_repository)=true];
   // SplitStrategy is a strategy used to create/update commit graph.
   SplitStrategy splitStrategy = 2; // protolint:disable:this FIELD_NAMES_LOWER_SNAKE_CASE
@@ -498,6 +500,7 @@ message CreateRepositoryResponse {
 
 // This comment is left unintentionally blank.
 message GetArchiveRequest {
+  // This comment is left unintentionally blank.
   enum Format {
     ZIP = 0;
     TAR = 1;
@@ -770,6 +773,7 @@ message GetRawChangesRequest {
 message GetRawChangesResponse {
   // This comment is left unintentionally blank.
   message RawChange {
+    // This comment is left unintentionally blank.
     enum Operation {
       UNKNOWN = 0;
       ADDED = 1;
diff --git a/proto/shared.proto b/proto/shared.proto
index 733bce621..8a23b063e 100644
--- a/proto/shared.proto
+++ b/proto/shared.proto
@@ -7,6 +7,7 @@ import "lint.proto";
 
 option go_package = "gitlab.com/gitlab-org/gitaly/v14/proto/go/gitalypb";
 
+// This comment is left unintentionally blank.
 enum ObjectType {
   UNKNOWN = 0;
   COMMIT = 1;
@@ -15,6 +16,7 @@ enum ObjectType {
   TAG = 4;
 }
 
+// This comment is left unintentionally blank.
 enum SignatureType {
   NONE = 0;
   PGP = 1;
diff --git a/proto/transaction.proto b/proto/transaction.proto
index cbd94a985..4e8864c81 100644
--- a/proto/transaction.proto
+++ b/proto/transaction.proto
@@ -44,6 +44,7 @@ service RefTransaction {
 
 // This comment is left unintentionally blank.
 message VoteTransactionRequest {
+  // This comment is left unintentionally blank.
   enum Phase {
     // UNKNOWN_PHASE is the unknown voting phase. This value has been the
     // default because phases have been introduced. Eventually, using this
diff --git a/proto/wiki.proto b/proto/wiki.proto
index 0837b6470..b99181651 100644
--- a/proto/wiki.proto
+++ b/proto/wiki.proto
@@ -131,15 +131,16 @@ message WikiFindPageResponse {
 
 // This comment is left unintentionally blank.
 message WikiGetAllPagesRequest {
-  Repository repository = 1 [(target_repository)=true];
-  // Passing 0 means no limit is applied
-  uint32 limit = 2;
-  bool direction_desc = 3;
-
+  // This comment is left unintentionally blank.
   enum SortBy {
     TITLE = 0;
     CREATED_AT = 1;
   }
+
+  Repository repository = 1 [(target_repository)=true];
+  // Passing 0 means no limit is applied
+  uint32 limit = 2;
+  bool direction_desc = 3;
   SortBy sort = 4;
 }
 
@@ -152,17 +153,17 @@ message WikiGetAllPagesResponse {
 
 // This comment is left unintentionally blank.
 message WikiListPagesRequest {
-  Repository repository = 1 [(target_repository)=true];
-  // Passing 0 means no limit is applied
-  uint32 limit = 2;
-  bool direction_desc = 3;
-
+  // This comment is left unintentionally blank.
   enum SortBy {
     TITLE = 0;
     CREATED_AT = 1;
   }
-  SortBy sort = 4;
 
+  Repository repository = 1 [(target_repository)=true];
+  // Passing 0 means no limit is applied
+  uint32 limit = 2;
+  bool direction_desc = 3;
+  SortBy sort = 4;
   uint32 offset = 5;
 }