diff options
Diffstat (limited to 'third_party/go/git-appraise/docs/tutorial.md')
| -rw-r--r-- | third_party/go/git-appraise/docs/tutorial.md | 404 |
1 files changed, 0 insertions, 404 deletions
diff --git a/third_party/go/git-appraise/docs/tutorial.md b/third_party/go/git-appraise/docs/tutorial.md deleted file mode 100644 index 6f95bb7e2ff5..000000000000 --- a/third_party/go/git-appraise/docs/tutorial.md +++ /dev/null @@ -1,404 +0,0 @@ -# Getting started with git-appraise - -This file gives an example code-review workflow using git-appraise. It starts -with cloning a repository and goes all the way through to browsing -your submitted commits. - -The git-appraise tool is largely agnostic of what workflow you use, so feel -free to change things to your liking, but this particular workflow should help -you get started. - -## Cloning your repository - -Since you're using a code review tool, we'll assume that you have a URL that -you can push to and pull from in order to collaborate with the rest of your team. - -First we'll create our local clone of the repository: -```shell -git clone ${URL} example-repo -cd example-repo -``` - -If you are starting from an empty repository, then it's a good practice to add a -README file explaining the purpose of the repository: - -```shell -echo '# Example Repository' > README.md -git add README.md -git commit -m 'Added a README file to the repo' -git push -``` - -## Creating our first review - -Generally, reviews in git-appraise are used to decide if the code in one branch -(called the "source") is ready to merge into another branch (called the -"target"). The meaning of each branch and the policies around merging into a -branch vary from team to team, but for this example we'll use a simple practice -called [GitHub Flow](https://guides.github.com/introduction/flow/). - -Specifically, we'll create a new branch for a particular feature, review the -changes to that branch against our master branch, and then delete the feature -branch once we are done. - -### Creating our change - -Create the feature branch: -```shell -git checkout -b ${USER}/getting-started -git push --set-upstream origin ${USER}/getting-started -``` - -... And make some changes to it: -```shell -echo "This is an example repository used for coming up to speed" >> README.md -git commit -a -m "Added an explanation to the README file" -git push -``` - -### Requesting the review - -Up to this point we've only used the regular commands that come with git. Now, -we will use git-appraise to perform a review: - -Request a review: -```shell -git appraise request -``` - -The output of this will be a summary of the newly requested review: -``` -Review requested: -Commit: 1e6eb14c8014593843c5b5f29377585e4ed55304 -Target Ref: refs/heads/master -Review Ref: refs/heads/ojarjur/getting-started -Message: "Added an explanation to the README file" -``` - -Show the details of the current review: -```shell -git appraise show -``` - -``` -[pending] 1e6eb14c8014 - Added an explanation to the README file - "refs/heads/ojarjur/getting-started" -> "refs/heads/master" - reviewers: "" - requester: "ojarjur@google.com" - build status: unknown - analyses: No analyses available - comments (0 threads): -``` - -Show the changes included in the review: -```shell -git appraise show --diff -``` - -``` -diff --git a/README.md b/README.md -index 08fde78..85c4208 100644 ---- a/README.md -+++ b/README.md -@@ -1 +1,2 @@ - # Example Repository -+This is an example repository used for coming up to speed -``` - -### Sending our updates to the remote repository - -Before a teammate can review our change, we have to make it available to them. -This involves pushing both our commits, and our code review data to the remote -repository: -```shell -git push -git appraise pull -git appraise push -``` - -The command `git appraise pull` is used to make sure that our local code review -data includes everything from the remote repo before we try to push our changes -back to it. If you forget to run this command, then the subsequent call to -`git appraise push` might fail with a message that the push was rejected. If -that happens, simply run `git appraise pull` and try again. - -## Reviewing the change - -Your teammates can review your changes using the same tool. - -Fetch the current data from the remote repository: -```shell -git fetch origin -git appraise pull -``` - -List the open reviews: -```shell -git appraise list -``` - -The output of this command will be a list of entries formatted like this: -``` -Loaded 1 open reviews: -[pending] 1e6eb14c8014 - Added an explanation to the README file -``` - -The text within the square brackets is the status of a review, and for open -reviews will be one of "pending", "accepted", or "rejected". The text which -follows the status is the hash of the first commit in the review. This is -used to uniquely identify reviews, and most git-appraise commands will accept -this hash as an argument in order to select the review to handle. - -For instance, we can see the details of a specific review using the "show" -subcommand: -```shell -git appraise show 1e6eb14c8014 -``` - -``` -[pending] 1e6eb14c8014 - Added an explanation to the README file - "refs/heads/ojarjur/getting-started" -> "refs/heads/master" - reviewers: "" - requester: "ojarjur@google.com" - build status: unknown - analyses: No analyses available - comments (0 threads): -``` - -... or, we can see the diff of the changes under review: -```shell -git appraise show --diff 1e6eb14c8014 -``` - -``` -diff --git a/README.md b/README.md -index 08fde78..85c4208 100644 ---- a/README.md -+++ b/README.md -@@ -1 +1,2 @@ - # Example Repository -+This is an example repository used for coming up to speed -``` - -Comments can be added either for the entire review, or on individual lines: -```shell -git appraise comment -f README.md -l 2 -m "Ah, so that's what this is" 1e6eb14c8014 -``` - -These comments then show up in the output of `git appraise show`: -```shell -git appraise show 1e6eb14c8014 -``` - -``` -[pending] 1e6eb14c8014 - Added an explanation to the README file - "refs/heads/ojarjur/getting-started" -> "refs/heads/master" - reviewers: "" - requester: "ojarjur@google.com" - build status: unknown - analyses: No analyses available - comments (1 threads): - "README.md"@1e6eb14c8014 - |# Example Repository - |This is an example repository used for coming up to speed - comment: bd4c11ecafd443c9d1dde6035e89804160cd7487 - author: ojarjur@google.com - time: Fri Dec 18 10:58:54 PST 2015 - status: fyi - Ah, so that's what this is -``` - -Comments initially only exist in your local repository, so to share them -with the rest of your team you have to push your review changes back: - -```shell -git appraise pull -git appraise push -``` - -When the change is ready to be merged, you indicate that by accepting the -review: - -```shell -git appraise accept 1e6eb14c8014 -git appraise pull -git appraise push -``` - -The updated status of the review will be visible in the output of "show": -```shell -git appraise show 1e6eb14c8014 -``` - -``` -[accepted] 1e6eb14c8014 - Added an explanation to the README file - "refs/heads/ojarjur/getting-started" -> "refs/heads/master" - reviewers: "" - requester: "ojarjur@google.com" - build status: unknown - analyses: No analyses available - comments (2 threads): - "README.md"@1e6eb14c8014 - |# Example Repository - |This is an example repository used for coming up to speed - comment: bd4c11ecafd443c9d1dde6035e89804160cd7487 - author: ojarjur@google.com - time: Fri Dec 18 10:58:54 PST 2015 - status: fyi - Ah, so that's what this is - comment: 4034c60e6ed6f24b01e9a581087d1ab86d376b81 - author: ojarjur@google.com - time: Fri Dec 18 11:02:45 PST 2015 - status: fyi -``` - -## Submitting the change - -Once a review has been accepted, you can merge it with the tool: - -```shell -git appraise submit --merge 1e6eb14c8014 -git push -``` - -The submit command will pop up a text editor where you can edit the default -merge message. That message will be used to create a new commit that is a -merge of the previous commit on the master branch, and the history of all -of your changes to the review. You can see what this looks like using -the `git log --graph` command: - -``` -* commit 3a4d1b8cd264b921c858185f2c36aac283b45e49 -|\ Merge: b404fa3 1e6eb14 -| | Author: Omar Jarjur <ojarjur@google.com> -| | Date: Fri Dec 18 11:06:24 2015 -0800 -| | -| | Submitting review 1e6eb14c8014 -| | -| | Added an explanation to the README file -| | -| * commit 1e6eb14c8014593843c5b5f29377585e4ed55304 -|/ Author: Omar Jarjur <ojarjur@google.com> -| Date: Fri Dec 18 10:49:56 2015 -0800 -| -| Added an explanation to the README file -| -* commit b404fa39ae98950d95ab06012191f58507e51d12 - Author: Omar Jarjur <ojarjur@google.com> - Date: Fri Dec 18 10:48:06 2015 -0800 - - Added a README file to the repo -``` - -This is sometimes called a "merge bubble". When the review is simply accepted -as is, these do not add much value. However, reviews often go through several -rounds of changes before they are accepted. By using these merge commits, we -can preserve both the full history of individual reviews, and the high-level -(review-based) history of the repository. - -This can be seen with the history of git-appraise itself. We can see the high -level review history using `git log --first-parent`: - -``` -commit 83c4d770cfde25c943de161c0cac54d714b7de38 -Merge: 9a607b8 931d1b4 -Author: Omar Jarjur <ojarjur@google.com> -Date: Fri Dec 18 09:46:10 2015 -0800 - - Submitting review 8cb887077783 - - Fix a bug where requesting a review would fail with an erroneous message. - - We were figuring out the set of commits to include in a review by - listing the commits between the head of the target ref and the head of - the source ref. However, this only works if the source ref is a - fast-forward of the target ref. - - This commit changes it so that we use the merge-base of the target and - source refs as the starting point instead of the target ref. - -commit 9a607b8529d7483e5b323303c73da05843ff3ca9 -Author: Harry Lawrence <hazbo@gmx.com> -Date: Fri Dec 18 10:24:00 2015 +0000 - - Added links to Eclipse and Jenkins plugins - - As suggested in #11 - -commit 8876cfff2ed848d50cb559c05d44e11b95ca791c -Merge: 00c0e82 1436c83 -Author: Omar Jarjur <ojarjur@google.com> -Date: Thu Dec 17 12:46:32 2015 -0800 - - Submitting review 09aecba64027 - - Force default git editor when omitting -m - For review comments, the absence of the -m flag will now attempt to load the - user's default git editor. - - i.e. git appraise comment c0a643ff39dd - - An initial draft as discussed in #8 - - I'm still not sure whether or not the file that is saved is in the most appropriate place or not. I like the idea of it being relative to the project although it could have gone in `/tmp` I suppose. - -commit 00c0e827e5b86fb9d200f474d4f65f43677cbc6c -Merge: 31209ce 41fde0b -Author: Omar Jarjur <ojarjur@google.com> -Date: Wed Dec 16 17:10:06 2015 -0800 - - Submitting review 2c9bff89f0f8 - - Improve the error messages returned when a git command fails. - - Previously, we were simply cascading the error returned by the instance - of exec.Command. However, that winds up just being something of the form - "exit status 128", with all of the real error message going to the - Stderr field. - - As such, this commit changes the behavior to save the data written to - stderr, and use it to construct a new error to return. - -... -``` - -Here you see a linear view of the reviews that have been submitted, but if we -run the command `git log --oneline --graph`, then we can see that the full -history of each individual review is also available: - -``` -* 83c4d77 Submitting review 8cb887077783 -|\ -| * 931d1b4 Merge branch 'master' into ojarjur/fix-request-bug -| |\ -| |/ -|/| -* | 9a607b8 Added links to Eclipse and Jenkins plugins -| * c7be567 Merge branch 'master' into ojarjur/fix-request-bug -| |\ -| |/ -|/| -* | 8876cff Submitting review 09aecba64027 -|\ \ -| * | 1436c83 Using git var GIT_EDITOR rather than git config -| * | 09aecba Force default git editor when omitting -m -|/ / -| * 8cb8870 Fix a bug where requesting a review would fail with an erroneous message. -|/ -* 00c0e82 Submitting review 2c9bff89f0f8 -... -``` - -## Cleaning up - -Now that our feature branch has been merged into master, we can delete it: - -```shell -git branch -d ${USER}/getting-started -git push origin --delete ${USER}/getting-started -``` |