diff --git a/README.md b/README.md index 98f29dd0..eb046810 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ repositories. ## Overview -This tool is the first *distributed* code review system for git repos. +This tool is a *distributed* code review system for git repos. By "distributed", we mean that code reviews are stored inside of the repository as git objects. Every developer on your team has their own copy of the review @@ -75,6 +75,8 @@ Submitting the current review: git appraise submit [--merge | --rebase] +A more detailed getting started doc is available [here](docs/tutorial.md). + ## Metadata The code review data is stored in git-notes, using the formats described below. diff --git a/docs/tutorial.md b/docs/tutorial.md new file mode 100644 index 00000000..671dbaad --- /dev/null +++ b/docs/tutorial.md @@ -0,0 +1,404 @@ +# 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 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 +| | Date: Fri Dec 18 11:06:24 2015 -0800 +| | +| | Submitting review 1e6eb14c8014 +| | +| | Added an explanation to the README file +| | +| * commit 1e6eb14c8014593843c5b5f29377585e4ed55304 +|/ Author: Omar Jarjur +| Date: Fri Dec 18 10:49:56 2015 -0800 +| +| Added an explanation to the README file +| +* commit b404fa39ae98950d95ab06012191f58507e51d12 + Author: Omar Jarjur + 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 +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 +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 +Date: Thu Dec 17 12:46:32 2015 -0800 + + Submitting review 09aecba64027 + + Force default git editor when omitting -m + For review comments, the absense 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 +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 +```