about summary refs log tree commit diff
path: root/third_party/go/git-appraise/docs/tutorial.md
diff options
context:
space:
mode:
Diffstat (limited to 'third_party/go/git-appraise/docs/tutorial.md')
-rw-r--r--third_party/go/git-appraise/docs/tutorial.md404
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
-```