Revamp CreateCommits to just create Commits and add specialized Push and Rebase endpoints #43
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -37,6 +37,23 @@ service BranchService { | |
| rpc ListBranches(ListBranchesRequest) returns (ListBranchesResponse) { | ||
| option idempotency_level = NO_SIDE_EFFECTS; | ||
| } | ||
| // Push existing Commits onto Branches. | ||
| // | ||
| // This operation is atomic. Either all Commits are pushed to the referenced Branches in the order | ||
| // provided or an error is returned. | ||
| // | ||
| // This operation does not allow the caller to assert the state of Branches before pushing any | ||
| // Commits onto them. As a result, multiple concurrent PushCommits operations that target the same | ||
saquibmian marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| // Branch will all succeed, and the head Commit on the Branch will be determined by the last | ||
| // request that succeeded. To deterministically push Commits onto a Branch, use Rebase instead. | ||
| rpc Push(PushRequest) returns (PushResponse); | ||
| // Rebase existing Commits onto Branches. | ||
| // | ||
| // This operation is atomic. Either all Branches are rebased as represented in the given Operations, | ||
| // or an error is returned. Additionally, each update in the request asserts the expected head Commit | ||
| // of the branch. If the actual head Commit does not match the expected head Commit, all Operations | ||
| // are rejected and an error is returned. | ||
| rpc Rebase(RebaseRequest) returns (RebaseResponse); | ||
| } | ||
|
|
||
| message GetBranchesRequest { | ||
|
|
@@ -98,3 +115,132 @@ message ListBranchesResponse { | |
| // The listed Branches. | ||
| repeated Branch branches = 2; | ||
| } | ||
|
|
||
| message PushRequest { | ||
| message Value { | ||
| // The Branch to push the Commits to. | ||
| // | ||
| // If this is a name reference, and the named Branch does not exist, it will | ||
| // be created and the given Commits will be the first Commits on the Branch. | ||
| BranchRef branch_ref = 1 [(buf.validate.field).required = true]; | ||
| // The ID of the Commits to push to the Branch, in the order they should be added. | ||
| // | ||
| // This Commit will become the head Commit on the Branch. | ||
bufdev marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| // | ||
| // If the Commit already exists on the Branch, an error is returned. | ||
bufdev marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| repeated string commit_ids = 2 [ | ||
| (buf.validate.field).repeated.min_items = 1, | ||
| (buf.validate.field).repeated.items = { | ||
| string: {uuid: true} | ||
| } | ||
| ]; | ||
| } | ||
| // The Commits to push with the Branches they should be pushed to. | ||
| // | ||
| // All Values should have unique BranchRefs, that is no two Values should have | ||
| // a BranchRef that refers to the same Branch. An error will be returned if any | ||
| // two BranchRefs refer to the same Branch. | ||
| repeated Value values = 1 [(buf.validate.field).repeated.min_items = 1]; | ||
| } | ||
|
There was a problem hiding this comment. @saquibmian do we need to support pushing to multiple branches simultaneously - push is last writer wins anyways, so maybe it's not worthwhile? If we got rid of that, we'd be able to simplify this RPC and get rid of the nested There was a problem hiding this comment. We do not, but not supporting batching is inconsistent with the rest of the schema. Every RPC today supports batching, except the |
||
|
|
||
| message PushResponse { | ||
| // The Branches that were pushed to, in the order they appeared in the request. | ||
| repeated Branch branches = 1 [(buf.validate.field).repeated.min_items = 1]; | ||
| } | ||
|
|
||
| message RebaseRequest { | ||
| // An operation to apply as part of the rebase. | ||
| message Operation { | ||
| // An operation to create a Branch. | ||
| message CreateBranch { | ||
| // The Module to create the Branch on. | ||
| ModuleRef module_ref = 1 [(buf.validate.field).required = true]; | ||
| // The name of the Branch to create. | ||
| // | ||
| // If a Branch with this name already exists on the Module, this will result in an error. | ||
| string branch_name = 2 [ | ||
| (buf.validate.field).required = true, | ||
| (buf.validate.field).string.max_len = 250 | ||
| ]; | ||
| // The ID of the Commit for which to start history from. The history of the branch will | ||
bufdev marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| // reflect the history as if you called ListCommitHistory for this Commit ID. | ||
| // | ||
| // If this is empty, the created Branch will only have the Commits specified in | ||
| // add_commit_ids. | ||
| // | ||
| // This is primarily designed for use in forking a Branch instead of | ||
| // providing the new Branch's entire history. | ||
| string start_commit_id = 3 [(buf.validate.field).string.uuid = true]; | ||
saquibmian marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| // The IDs of the Commits to add to the Branch, in the order they should be added. | ||
| // | ||
| // If start_commit_id is specified, these will be appended to the Commit history | ||
| // that aleady exists up to start_commit_id. | ||
| // | ||
| // If start_commit_id is not specified, the newly-created Branch will have exactly | ||
| // these Commits, in this order. | ||
| repeated string add_commit_ids = 4 [(buf.validate.field).repeated.items = { | ||
| string: {uuid: true} | ||
| }]; | ||
| } | ||
|
|
||
| // An operation to update an existing branch. | ||
| message UpdateBranch { | ||
| // The branch to update. | ||
| BranchRef branch_ref = 1 [(buf.validate.field).required = true]; | ||
| // The ID of the Commit that the caller expects to be the head Commit on the Branch. | ||
| // | ||
| // If this ID does not match the ID of the head Commit on the Branch, an error is | ||
| // returned. | ||
| string expected_head_commit_id = 2 [ | ||
| (buf.validate.field).required = true, | ||
| (buf.validate.field).string.uuid = true | ||
| ]; | ||
| // The IDs of the Commits to remove from the Branch. | ||
| // | ||
| // Commits are removed before any Commits are added from add_commit_ids. | ||
| // | ||
| // Note that it is valid to have one of the remove_commit_ids be equal to the | ||
| // expected_head_commit_id. If this is the case, the Branch will have a different | ||
| // head Commit that add_commit_ids will be applied to. | ||
| repeated string remove_commit_ids = 3 [(buf.validate.field).repeated.items = { | ||
saquibmian marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| string: {uuid: true} | ||
| }]; | ||
| // The IDs of the Commits to add to the Branch, in the order they should be added. | ||
| // | ||
| // These are added starting at the head Commit after remove_commit_ids has been applied. | ||
| // | ||
| // Note that is is valid to have IDs in both add_commit_ids and remove_commit_ids. If | ||
| // this is the case, the IDs will be removed from the Branch prior to re-adding them after | ||
| // the head Commit via add_commit_ids. | ||
| repeated string add_commit_ids = 4 [(buf.validate.field).repeated.items = { | ||
| string: {uuid: true} | ||
| }]; | ||
| } | ||
|
|
||
| oneof value { | ||
| option (buf.validate.oneof).required = true; | ||
| // Create a new branch. | ||
| CreateBranch create_branch = 1; | ||
| // Update an existing branch. | ||
| UpdateBranch patch_branch = 2; | ||
saquibmian marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| } | ||
| } | ||
|
|
||
| // The operations to apply. | ||
| // | ||
| // The Operations will be applied in the order they are provided. Notably, this means that | ||
| // if a CreateBranch Operation precedes a UpdateBranch Operation for the same Branch, the | ||
| // UpdateBranch Operation is applied to the newly-created Branch, including any new Commits | ||
| // that were added from the CreateBranch Operation. Conversely, if a UpdateBranch Operation | ||
| // precedes the CreateBranch operation that creates the Branch, this will result in an error. | ||
| repeated Operation operations = 1 [(buf.validate.field).repeated.min_items = 1]; | ||
| } | ||
|
|
||
| message RebaseResponse { | ||
| // The Branches that were updated. This list will be the unique set of Branches | ||
| // that were updated, and the length of values will be less than the length | ||
| // of the input Operations if multiple Operations were applied for a single Branch. | ||
| // However, the response Branches ordered in the same order that the Branches | ||
| // first appeared in the request Operations. | ||
| repeated Branch branches = 1 [(buf.validate.field).repeated.min_items = 1]; | ||
| } | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I noticed this is required. Does this imply that an empty Branch does not exist, or should we relax this constraint?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Unless this causes a problem elsewhere, it makes sense to me that an empty branch doesn't exist because this is true in Git (a branch pointer has to point to a commit).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I updated the docs to reflect this.