From e480e1b72268b7b0ad47e0828a03c47dc27b0083 Mon Sep 17 00:00:00 2001 From: Patrick Steinhardt Date: Tue, 20 Apr 2021 10:07:21 +0200 Subject: proto: Document the `ResolveConflicts()` RPC While ResolveConflicts is all but trivial, it's protobuf interface isn't documented at all. Fix this by adding documentation. --- proto/conflicts.proto | 31 ++++++++++++++++++++++++++ proto/go/gitalypb/conflicts.pb.go | 46 +++++++++++++++++++++++++++++++++------ 2 files changed, 70 insertions(+), 7 deletions(-) (limited to 'proto') diff --git a/proto/conflicts.proto b/proto/conflicts.proto index 64efb7d60..9897069c1 100644 --- a/proto/conflicts.proto +++ b/proto/conflicts.proto @@ -14,6 +14,10 @@ service ConflictsService { op: ACCESSOR }; } + + // ResolveConflicts tries to resolve a conflicting merge with a set of + // user-provided merge resolutions. If resolving the conflict succeeds, the + // result will be a new merge commit. rpc ResolveConflicts(stream ResolveConflictsRequest) returns (ResolveConflictsResponse) { option (op_type) = { op: MUTATOR @@ -47,27 +51,54 @@ message ListConflictFilesResponse { repeated ConflictFile files = 1; } +// ResolveConflictsRequestHeader is the first message that must be sent for +// each ResolveConflicts call. message ResolveConflictsRequestHeader { + // Repository is the repository in which conflicts shall be resolved and + // where SourceBranch shall be updated with the resolved conflict. Repository repository = 1 [(gitaly.target_repository)=true]; + // OurCommitOid is the OID of the commit representing the local commit. string our_commit_oid = 2; + // TargetRepository is the repository from which TheirCommitOid shall be + // retrieved. Repository target_repository = 3; + // TheirCommitOid is the OID of the commit representing the remote commit + // which is to be merged into the local commit. string their_commit_oid = 4; + // SourceBranch is the branch on which the new commit shall be created. bytes source_branch = 5; + // TargetBranch identifies the branch which will be fetched from + // TargetRepository in case TheirCommitOid does not exist in Repository. bytes target_branch = 6; + // CommitMessage is the message of the newly created merge commit. bytes commit_message = 7; + // User is the user used as author and committer of the newly created merge + // commit. User user = 8; // timestamp is the optional timestamp to use for the commit as committer // date. If it's not set, the current time will be used. google.protobuf.Timestamp timestamp = 9; } +// ResolveConflictsRequest is a request for the ResolveConflicts RPC. message ResolveConflictsRequest { + // RequestPayload is the payload part of the request. The first message sent + // must always be a ResolveConflictsRequestHeader, whereas all remaining + // requests must be FilesJson requests. oneof resolve_conflicts_request_payload { + // Header is the initial message specifying parameters of the RPC call. ResolveConflictsRequestHeader header = 1; + // FilesJson is a JSON-encoded list of conflicts resolutions. bytes files_json = 2; } } +// ResolveConflictsResponse is a response of the ResolveConflicts RPC. Conflict +// resolution may have failed even if the RPC has returned OK. The user must +// check ResolutionError to verify whether the merge commit was correctly +// computed or not. message ResolveConflictsResponse { + // ResolutionError contains a description of why conflict resolution has + // failed. string resolution_error = 1; } diff --git a/proto/go/gitalypb/conflicts.pb.go b/proto/go/gitalypb/conflicts.pb.go index 0fb7650ca..e93c9e9c1 100644 --- a/proto/go/gitalypb/conflicts.pb.go +++ b/proto/go/gitalypb/conflicts.pb.go @@ -270,15 +270,30 @@ func (m *ListConflictFilesResponse) GetFiles() []*ConflictFile { return nil } +// ResolveConflictsRequestHeader is the first message that must be sent for +// each ResolveConflicts call. type ResolveConflictsRequestHeader struct { - Repository *Repository `protobuf:"bytes,1,opt,name=repository,proto3" json:"repository,omitempty"` - OurCommitOid string `protobuf:"bytes,2,opt,name=our_commit_oid,json=ourCommitOid,proto3" json:"our_commit_oid,omitempty"` + // Repository is the repository in which conflicts shall be resolved and + // where SourceBranch shall be updated with the resolved conflict. + Repository *Repository `protobuf:"bytes,1,opt,name=repository,proto3" json:"repository,omitempty"` + // OurCommitOid is the OID of the commit representing the local commit. + OurCommitOid string `protobuf:"bytes,2,opt,name=our_commit_oid,json=ourCommitOid,proto3" json:"our_commit_oid,omitempty"` + // TargetRepository is the repository from which TheirCommitOid shall be + // retrieved. TargetRepository *Repository `protobuf:"bytes,3,opt,name=target_repository,json=targetRepository,proto3" json:"target_repository,omitempty"` - TheirCommitOid string `protobuf:"bytes,4,opt,name=their_commit_oid,json=theirCommitOid,proto3" json:"their_commit_oid,omitempty"` - SourceBranch []byte `protobuf:"bytes,5,opt,name=source_branch,json=sourceBranch,proto3" json:"source_branch,omitempty"` - TargetBranch []byte `protobuf:"bytes,6,opt,name=target_branch,json=targetBranch,proto3" json:"target_branch,omitempty"` - CommitMessage []byte `protobuf:"bytes,7,opt,name=commit_message,json=commitMessage,proto3" json:"commit_message,omitempty"` - User *User `protobuf:"bytes,8,opt,name=user,proto3" json:"user,omitempty"` + // TheirCommitOid is the OID of the commit representing the remote commit + // which is to be merged into the local commit. + TheirCommitOid string `protobuf:"bytes,4,opt,name=their_commit_oid,json=theirCommitOid,proto3" json:"their_commit_oid,omitempty"` + // SourceBranch is the branch on which the new commit shall be created. + SourceBranch []byte `protobuf:"bytes,5,opt,name=source_branch,json=sourceBranch,proto3" json:"source_branch,omitempty"` + // TargetBranch identifies the branch which will be fetched from + // TargetRepository in case TheirCommitOid does not exist in Repository. + TargetBranch []byte `protobuf:"bytes,6,opt,name=target_branch,json=targetBranch,proto3" json:"target_branch,omitempty"` + // CommitMessage is the message of the newly created merge commit. + CommitMessage []byte `protobuf:"bytes,7,opt,name=commit_message,json=commitMessage,proto3" json:"commit_message,omitempty"` + // User is the user used as author and committer of the newly created merge + // commit. + User *User `protobuf:"bytes,8,opt,name=user,proto3" json:"user,omitempty"` // timestamp is the optional timestamp to use for the commit as committer // date. If it's not set, the current time will be used. Timestamp *timestamp.Timestamp `protobuf:"bytes,9,opt,name=timestamp,proto3" json:"timestamp,omitempty"` @@ -375,7 +390,12 @@ func (m *ResolveConflictsRequestHeader) GetTimestamp() *timestamp.Timestamp { return nil } +// ResolveConflictsRequest is a request for the ResolveConflicts RPC. type ResolveConflictsRequest struct { + // RequestPayload is the payload part of the request. The first message sent + // must always be a ResolveConflictsRequestHeader, whereas all remaining + // requests must be FilesJson requests. + // // Types that are valid to be assigned to ResolveConflictsRequestPayload: // *ResolveConflictsRequest_Header // *ResolveConflictsRequest_FilesJson @@ -456,7 +476,13 @@ func (*ResolveConflictsRequest) XXX_OneofWrappers() []interface{} { } } +// ResolveConflictsResponse is a response of the ResolveConflicts RPC. Conflict +// resolution may have failed even if the RPC has returned OK. The user must +// check ResolutionError to verify whether the merge commit was correctly +// computed or not. type ResolveConflictsResponse struct { + // ResolutionError contains a description of why conflict resolution has + // failed. ResolutionError string `protobuf:"bytes,1,opt,name=resolution_error,json=resolutionError,proto3" json:"resolution_error,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -568,6 +594,9 @@ const _ = grpc.SupportPackageIsVersion4 // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://godoc.org/google.golang.org/grpc#ClientConn.NewStream. type ConflictsServiceClient interface { ListConflictFiles(ctx context.Context, in *ListConflictFilesRequest, opts ...grpc.CallOption) (ConflictsService_ListConflictFilesClient, error) + // ResolveConflicts tries to resolve a conflicting merge with a set of + // user-provided merge resolutions. If resolving the conflict succeeds, the + // result will be a new merge commit. ResolveConflicts(ctx context.Context, opts ...grpc.CallOption) (ConflictsService_ResolveConflictsClient, error) } @@ -648,6 +677,9 @@ func (x *conflictsServiceResolveConflictsClient) CloseAndRecv() (*ResolveConflic // ConflictsServiceServer is the server API for ConflictsService service. type ConflictsServiceServer interface { ListConflictFiles(*ListConflictFilesRequest, ConflictsService_ListConflictFilesServer) error + // ResolveConflicts tries to resolve a conflicting merge with a set of + // user-provided merge resolutions. If resolving the conflict succeeds, the + // result will be a new merge commit. ResolveConflicts(ConflictsService_ResolveConflictsServer) error } -- cgit v1.2.3