google / git-appraise

Distributed code review system for Git repos

Distributed Code Review For Git

This repo contains a command line tool for performing code reviews on git repositories.

Overview

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 history that they can push or pull. When pulling, updates from the remote repo are automatically merged by the tool.

This design removes the need for any sort of server-side setup. As a result, this tool can work with any git hosting provider, and the only setup required is installing the client on your workstation.

Installation

Assuming you have the Go tools installed, run the following command:

go install github.com/google/git-appraise/git-appraise@latest

Then, either make sure that ${GOPATH}/bin is in your PATH, or explicitly add the "appraise" git alias by running the following command.

git config --global alias.appraise '!'"${GOPATH}/bin/git-appraise"

Windows:

git config --global alias.appraise "!%GOPATH%/bin/git-appraise.exe"

Requirements

This tool expects to run in an environment with the following attributes:

1. The git command line tool is installed, and included in the PATH.
2. The tool is run from within a git repo.
3. The git command line tool is configured with the credentials it needs to push to and pull from the remote repos.

Usage

Requesting a code review:

git appraise request

Pushing code reviews to a remote:

git appraise push [<remote>]

Pulling code reviews from a remote:

git appraise pull [<remote>]

Listing open code reviews:

git appraise list

Showing the status of the current review, including comments:

git appraise show

Showing the diff of a review:

git appraise show --diff [--diff-opts "<diff-options>"] [<review-hash>]

Commenting on a review:

git appraise comment -m "<message>" [-f <file> [-l <line>]] [<review-hash>]

Accepting the changes in a review:

git appraise accept [-m "<message>"] [<review-hash>]

Submitting the current review:

git appraise submit [--merge | --rebase]

A more detailed getting started doc is available here.

Metadata

The code review data is stored in git-notes, using the formats described below. Each item stored is written as a single line of JSON, and is written with at most one such item per line. This allows the git notes to be automatically merged using the "cat_sort_uniq" strategy.

Since these notes are not in a human-friendly form, all of the refs used to track them start with the prefix "refs/notes/devtools". This helps make it clear that these are meant to be read and written by automated tools.

When a field named "v" appears in one of these notes, it is used to denote the version of the metadata format being used. If that field is missing, then it defaults to the value 0, which corresponds to this initial version of the formats.

Code Review Requests

Code review requests are stored in the "refs/notes/devtools/reviews" ref, and annotate the first revision in a review. They must conform to the request schema.

If there are multiple requests for a single commit, then they are sorted by timestamp and the final request is treated as the current one. This sorting should be done in a stable manner, so that if there are multiple requests with the same timestamp, then the last such request in the note is treated as the current one.

This design allows a user to update a review request by re-running the git appraise request command.

Continuous Integration Status

Continuous integration build and test results are stored in the "refs/notes/devtools/ci" ref, and annotate the revision that was built and tested. They must conform to the ci schema.

Robot Comments

Robot comments are comments generated by static analysis tools. These are stored in the "refs/notes/devtools/analyses" ref, and annotate the revision. They must conform to the analysis schema.

Review Comments

Review comments are comments that were written by a person rather than by a machine. These are stored in the "refs/notes/devtools/discuss" ref, and annotate the first revision in the review. They must conform to the comment schema.

Integrations

Libraries

• Go (use git-appraise itself)
• Rust

Graphical User Interfaces

• Git-Appraise-Web

Plugins

• Eclipse
• Jenkins

Mirrors to other systems

• GitHub Pull Requests
• Phabricator Revisions

Contributing

Please see the CONTRIBUTING file for information on contributing to Git Appraise.

git-appraise's Issues

Add more sophisticated support for rebasing a review.

Right now the git appraise submit command supports a --rebase flag that will cause the review to be rebased onto the target branch as part of submitting it.

That has the side effect of the code review data being disconnected from the final, submitted commit. As such, it is only sufficient if you want to use the code review data prior to the submit and not afterwards (for, e.g. browsing review history).

It would be better if the review data was connected to the rebased commit. We still want users to be able to have their intermediate commits garbage collected (if they so desire), so this linkage needs to be done in a way that does not force the intermediate commits to be kept (such as making them a parent of a notes commit).

Since there might be comments on intermediate commits that later get garbage collected, this also requires that the tool handle that scenario gracefully.

Additionally, we may want to add a git appraise rebase command that does this rebasing without submitting the review.

git-appraise list -json dump full review with comments.

I'm working on vim integration for git-appraise. g
Trying to get a list of reviews programmatically, git-appraise list -json dumps the entirety of all reviews, rather than just the "headline" details. Ideally it will leave dumping of the individual review details to git-appraise show. On busy repositories, git appraise list -a -o json could be prohibitively large I guess?

git appraise comment does not work on Windows

git appraise comment without any options
does not work on Windows.

Unable to start editor: exec: "vi": executable file not found in %PATH%

I use Git for Windows 2.6.4
This is because /usr/bin/vi is a shell script, not a native Windows executable.
The actual exe is /usr/bin/vim.

'Unknown git ref' error frequently occurring

I'm receiving this error message rather frequently. I don't know in this case if I've been doing something dumb.

All I've done is simply clone git-appraise, pulled down reviews and tried to leave a comment. Upon leaving a comment I receive that particular error message.

/cc @ojarjur

Consider adding an event to represent editing a comment

The comment schema defines a record of discussion events (e.g. "User A added a comment at line B").

The schema as it currently stands can encode two types of events:

1. A user adding a new comment
2. A user responding to an existing comment

We might want to also provide a way to represent an edit event; where a user modifies an existing comment.

I do not think that support for updating a comment needs to be added to the command-line surface, as I imagine that user experience would be rather clunky. However, supporting it in the schema (and making the CLI display such comments properly) would make it easier to support comment editing in user experiences that can support it well (such as GUIs).

The simplest approach I can think of is to add an original field to the schema that would be similar to the parent field. That would specify that the comment is an update to the specified, prior comment.

We could also use this event to represent removing a comment, by having all of the fields other than original being empty.

When building the CommentThread objects, we would include all of the versions of a comment, but only display the last one. That would allow the user to still see all versions of a comment by displaying the JSON format of the review.

This would be very similar to the current support for updating a review request.

Using Robot Comments for code coverage

Hi,

we're evaluating the use of Robot Comments for code coverage in the context of Gerrit.

Have you ever thought about such a use ? Any recommendation on the Shipshape format to use ?

And an extra question, we're wondering about the benefit of storing the url to a (standardized) shipshape response, versus storing the coverage/comments (potentially using the same format) directly in the robot-comment itself.
What was the motivation for preferring the former ? (too much data ?)

Thx !

Support pulling the git-notes for reviews from an untrusted repository.

This is meant for situations where an outside contributor requests a pull from their repository to an upstream repository.

In that scenario, the outside contributor can pull reviews from the upstream repository, and can push their review metadata to their repository. However, the maintainers of the upstream repository probably do not want to pull review metadata for all reviews from that outside contributor's repository, but do want to pull review metadata for that one request.

I imagine a scenario like the following:

1. A repository (that we'll call upstream) is hosted somewhere.
2. Outside contributor creates their own fork of that repository (that we'll call fork).
3. Outside contributor makes some changes in their fork.
4. The contributor requests a pull (either via git request-pull or something like a GitHub pull request) from their fork into the upstream repository.
5. The maintainers of the upstream repository fetch the changes from the fork into a branch and create a review request to merge that branch into the master branch.
6. The maintainers add some comments to the review.
7. The outside contributor runs git appraise pull <upstream> to fetch the review request and comments from the upstream repository. They then respond to the comments and run git appraise push <fork> to push their comments to their fork.
8. The upstream maintainers run something like git appraise pull --only-comments <review> <fork> to pull just the comments for that review from the fork, and then they run git appraise push <upstream> to push the combined review metadata to the upstream repository.
9. Repeat steps 6-8 until the maintainers are happy with the review and submit it.

Since the upstream only really cares about the comments from the contributor (the review requests will be different because the review refs will be different, and the maintainers may want to abandon the review), I'm thinking this can all be supported by adding a flag to the git appraise pull subcommand that tells it to only pull the notes from the refs/notes/devtools/discuss ref, and to only merge in the notes for a specified review.

The show command does not display comment status correctly

It seems that the show command always displays the status of a comment as fyi.

Steps to reproduce

git appraise comment -m 'fyi comment'
git appraise comment -lgtm -m 'lgtm comment'
git appraise comment -nmw -m 'nmw comment'

Then running git appraise show will show something like:

    comment: $SHA
      author: $AUTHOR
      time:   $TIMESTAMP
      status: fyi
      fyi comment

    comment: $SHA
      author: $AUTHOR
      time:   $TIMESTAMP
      status: fyi
      lgtm comment

    comment: $SHA
      author: $AUTHOR
      time:   $TIMESTAMP
      status: fyi
      nmw comment

On the other hand git appraise show -json displays the correct status (in the resolved property):

  "comments": [
    {
      "hash": "$SHA",
      "comment": {
        "timestamp": "$TIMESTAMP",
        "author": "$AUTHOR",
        "location": {
          "commit": "$SHA"
        },
        "description": "fyi comment"
      }
    },
    {
      "hash": "$SHA",
      "comment": {
        "timestamp": "$TIMESTAMP",
        "author": "$AUTHOR",
        "location": {
          "commit": "$SHA"
        },
        "description": "lgtm comment"
        "resolved": true
      }
    },
    {
      "hash": "$SHA",
      "comment": {
        "timestamp": "$TIMESTAMP",
        "author": "$AUTHOR",
        "location": {
          "commit": "$SHA"
        },
        "description": "nmw comment"
        "resolved": false
      }
    }

Support email integration

We would like to support both sending and receiving emails for code reviews.

My current thought is, in order to do this, we should add wrappers around git-format-patch and git-am.

More specifically, I'm thinking that we could add two new subcommands: 'git appraise format-patch' and 'git appraise am', which would call into the corresponding git commands.

For 'git appraise format-patch', we would want to additionally turn comments into mail messages that quote the patch they are commenting on.

Correspondingly, for 'git appraise am', we would want it to read replies that quote a patch and turn the non-quote lines into inline comments.

Unable to Create a Request

Downloaded and installed using "go get". On an existing git repo, every reasonable invocation of "git appraise request" results in "exit code 128".

For example, using the "git-appraise" repo as an example (thanks to Y-combinator user ktt for showing how to fetch notes https://news.ycombinator.com/item?id=10733953):

$ git appraise request -source remotes/origin/ojarjur/improve-error-messages -target origin/master
exit status 128

I'm using git 1.8.2 on CentOS 6.6. Tried both Go 1.5.1 and 1.5.2 with the same results.

Any suggestions?

I love the idea of this and really want to check it out!

Make "git-appraise" (without subcommand) list the open reviews

This would make the behavior inline with "git branch" and "git tag".

We might also want to add a "--list [<target-ref>]" flag to allow filtering the reviews listed.

This came from the suggestion @andreineculau made in #39

Add documentation about how to specify line and column ranges for comments.

Phabricator has this feature and it's really useful being able to pinpoint exactly what lines you're talking about when you make a comment.

Raw Content of Review Request not in json format

Hello,

I am trying to parse the review requests with another tool and found out that the raw content of the review request blob is not in json format but it is just the concatenation of json objects.

Is that indented behavior? Why not generate an array of json object?

Thank you for clarification.

best regards
Dominik

Code review vs. bug tracking?

Could the README possibly provide a comparison to tools like https://bugseverywhere.org/ ?

Bugs Everywhere is a “distributed bugtracker”, designed to complement distributed revision control systems. By using distributed revision control as a backend for bug state, we gain several convenient features: ....

Make the submit strategy (fast-forward, merge, rebase, etc.) configurable

The "submit" subcommand supports two flags (--merge and --rebase) for changing the way that merging is done (creating a merge bubble, rebasing the entire review, or defaulting to a fast-forward).

Having flags for this allows it to be selected per-review, but the expected scenario is that each project adopts a policy on which strategy to use, so it should be set once per repo instead of for each review.

For example, a user might want to run

git config --add appraise.submit 'merge'

And then have future calls to git appraise submit use the merge strategy by default.

We should also add a --fast-foward flag so that the user can override their per-repo configuration when submitting a review.

Can't submit a code review

Hi,
I'm having problem to submit a code review. I'm doing
$ git appraise
Loaded 2 open reviews:
[pending] 8b692d60c974
Center checkbox, add padding

Solves: Odoo #869
[accepted] a2d5c3619740
Add missing dependency

The module won't installed without it since a view has dependencies
on a view in base_geolocalize

$ git appraise submit a2d5
Refusing to submit a non-fast-forward review. First merge the target ref.

Adding some debug prints to git appraise it seems as git appraise tries to merge a2d5 to origin/master which is wrong since a2d5 is the review and not the actually branch commit that should be merged.

I'm a bit puzzled about this, because this not working should mean that git appraise doesn't work for anyone and that seems not to be the case, so it might be me doing something wrong, but what?

Feature Request: Atom Editor Integration

Hello,

I open this topic just to start a joint discussion on what it takes to offer a GUI integration for the popular Atom Editor.

I also asked in the Atom Editor Forum to find like-minded persons:

https://discuss.atom.io/t/gui-for-git-appraise-code-review-comments/52261

Comment location parameters are checked after invoking editor

In the git-appraise repo, I did

$ git appraise comment -f .travis.yml -l 10 bd714f195655

and composed a review comment in my editor. After I was done I got

Unable to comment on the given location: Line number 10 does not exist in file ".travis.yml"

This was just my off-by-one error, I should have used -l 9.

Unfortunately, .git/APPRAISE_COMMENT_EDITMSG was deleted despite the error, so I had to write it again.
I think we should either check for errors upfront, or preserve APPRAISE_COMMENT_EDITMSG in case of errors.

(I pushed my review to my fork, I'm not sure if that will reach the PR here?)

Add a "status" field to the robot comment metadata

For continuous integration metadata, we have a "status" field that indicates the overall status of the continuous integration run (e.g. "success" or "failure"). However, for robot comments we did not include an equivalent.

The result of this, is that for the tool to know whether or not the analyses produced messages it has to actually download the referenced Shipshape results, and parse them. This is both expensive and redundant if the analyses produced no messages, so we should add a "status" field indicating the high-level results of the analyses. Since these are robot comments, it makes sense for the status field to have the same potential status as human comments:

1. "nmw" (Needs More Work) - meaning that the analyses produced messages indicating an issue
2. "fyi" - meaning that the analyses produced messages that are just informational
3. "lgtm" (Looks Good To Me) - meaning that the analyses ran successfully, but produced no messages

$EDITOR with args isn't working

My EDITOR is set to emacsclient -tty. This works fine with all common command line tools. It fails in git appraise with the following message:

Unable to start editor: exec: "emacsclient -tty": executable file not found in $PATH

git appraise review to act as a standard unix filter

hello,

i would like to use git appraise review with -F filename (- for stdin) instead of using an editor (as in git commit -F). this could be very usefull for many cases.

regards

Make the status string shown for subthreads consistent

As pointed out by @linquize, we are not being consistent here: f355377#diff-9c7a05e4295bdceebccd9558859ab151R123

In one case we use the acronym "lgtm" and in the other we spell it out as "needs work". We should pick one approach (acronyms or spelled-out) and be consistent with it.

Any plan to support authorization on reviewers ?

Hello,
Is there any plan to support authorization on reviewers ?
Could we choose who has the right to reviews code ?

Or you let this part to the Git provider ?
Thanks

Add instructions for setting up the Git alias for Windows

I used git config --global alias.appraise "%GOPATH%/bin/git-appraise.exe" to set up the Git alias. I verified the git-appraise.exe file exists.

Invoking it manually makes it say it needs to run within a context of a Git repository.

Running git appraise request gives me Expansion of alias 'appraise' failed; 'C:/Users/Tom/go/bin/git-appraise.exe' is not a git command. What I am doing differently from people who did get this run on Windows? Going through closed issues at least one person managed to. @linquize?

I am using Windows Command Prompt. I am willing to use PowerShell or WSL but not MSYS. Is that going to be a problem for me?

Is there an emacs UI anywhere ?

Add timestamp flag for request, comment, accept

I propose to add an optional -timestamp flag to the following commands:

• git appraise request
• git appraise comment
• git appraise accept

If the flag is not specified, it will default to the current timestamp. The timestamp will then be used for the request and comment JSON objects.

This will make it easy to script importing historical code reviews from other systems. No special code will be required, just normal shell commands. (User can be easily set in the shell with git config.)

Document what to do with duplicate items

I can probably work out what to do by checking the code, but it would be good for this to be defined as part of the format. An example is for the review on fd4109d, this has reviews stored under note e81a4e0ea017 and CI status under note 4914d5adea78. Using git show to view the notes directly gives

Review

> git show e81a4e0ea017
{"timestamp":"1450125974","targetRef":"refs/heads/master","reviewRef":"refs/pull/5/head","requester":"stp-ip","description":"Fix typo in README"}
{"timestamp":"1450215328","targetRef":"refs/heads/master","reviewRef":"refs/pull/5/head","requester":"stp-ip","description":"Fix typo in README"}
{"timestamp":"1450219553","targetRef":"refs/heads/master","reviewRef":"refs/pull/5/head","requester":"stp-ip","description":"Fix typo in README"}
{"timestamp":"1450222101","targetRef":"refs/heads/master","reviewRef":"refs/pull/5/head","requester":"stp-ip","description":"Fix typo in README"}
{"timestamp":"1450338870","targetRef":"refs/heads/master","reviewRef":"refs/pull/5/head","requester":"stp-ip","description":"Fix typo in README"}
{"timestamp":"1450338936","targetRef":"refs/heads/master","reviewRef":"refs/pull/5/head","requester":"stp-ip","description":"Fix typo in README"}

{"timestamp":"1450338936","reviewRef":"refs/pull/5/head","targetRef":"refs/heads/master","requester":"stp-ip","description":"Fix typo in README","baseCommit":"6302bf385c36958fb8881e43f11daeeb4ed42cc0"}

For this I assume just taking the latest instance would be appropriate.

Although how to determine latest? Judging by the duplicates on the last two entries timestamp is not guaranteed to be monotonically increasing, and even if it were on a single machine then what happens with edits to the same review from multiple machines?

CI Status

> git show 4914d5adea78
{"timestamp":"1450504163","v":0,"agent":"Jenkins(1.627) GitNotesJobLogger","url":"https://jenkins-dot-developer-tools-bundle.appspot.com/job/git-appraise/118/"}

{"timestamp":"1450504169","v":0,"agent":"Jenkins(1.627) GitNotesJobLogger","url":"https://jenkins-dot-developer-tools-bundle.appspot.com/job/git-appraise/118/","status":"success"}

{"timestamp":"1450219554","status":"success","agent":"cla/google"}

{"timestamp":"1450126113","url":"https://travis-ci.org/google/git-appraise/builds/96828980","status":"success","agent":"continuous-integration/travis-ci/pr"}

{"timestamp":"1450126043","url":"https://travis-ci.org/google/git-appraise/builds/96828980","agent":"continuous-integration/travis-ci/pr"}

{"timestamp":"1450125975","url":"https://travis-ci.org/google/git-appraise/builds/96828980","agent":"continuous-integration/travis-ci/pr"}

Since there are multiple agents submitting their CI status I guess the latest entry from each unique url (or agent when url is missing?) value may be appropriate.

Here you can actually see that different machines have different timestamps. In this case it doesn't really matter as each agent is on a unique machine so that when partitioned by url or agent the timestamp is at least increasing, even if not guaranteed to be monotonic. But I can imagine some form of CI agent that involves passing the job through multiple machines as it works, which could result in non-increasing timestamps for a single job.

 

It might be worth adding a required third-party id entry to allow agents without a url (like cla/google) to add multiple statuses and update them?

 

Also just noticed that it appears the travis-ci implementation is actually prepending its new statuses as it works rather than appending like the rest seem to.

These are the only parts of the spec that I've really looked into so far. A quick glance at robot comments seems like it should be ok since there's nothing there to update, I'll take a deeper look at review comments and add an update.

Use `gpg.program` in Git config

Currently, use of gpg is hardcoded. Instead, it ought to check whether a user has the config key gpg.program set, and use it if so. If not, it can fall back on a default.

Github integration?

Bit of an odd question.

I've been using "ghi" for a majority of my time on github, with the inclusion of it's experimental PR for reviewing and accepting PR's. See https://github.com/stephencelis/ghi

Now I've seen git-appraise and it fits (mostly) into what I've been looking at for reviewing PR requests on the command line without having to jump through hoops in a web-interface.

Would you be open for plugin-like contributions (for example, connecting to the Github API for reading comments on GHI requests, giving your praise, etc.).

Eventually Gitlab integration, gogs (https://github.com/gogits/gogs), etc. So having more than one option for just Github would be great.

I don't have a general outline yet, but thought I'd throw it up in the air.

Make the "git appraise show" command accept the same diff flags as the "git show" command.

In particular, "git show" supports -p/-u/--patch flags for generating the diff (patch).

If we go with the -p/-u/--patch flag, then we should also add a -s/--no-patch and make the default configurable. I'd also want to keep the --diff option so as to not break any scripts that have been written against the tool.

Another thing to consider is whether or not diff should be promoted to its own subcommand (e.g. "git appraise diff"). If we do that, then we should try to make it as consistent as possible with "git diff".

This came from the suggestion @andreineculau made in #39

Change the repository.PullNotes command to remove a redundant call to "ls-remote"

As noted by @linquize here, the call to "ls-remote" in the PullNotes method is redundant; it follows a fetch of the remote refs, so they can just be listed locally instead of calling out to the remote repo again.

Add a tutorial doc on rebasing reviews

We need to document how rewriting history works with keeping review metadata in git.

Ability to write more detailed review comments

When writing a comment on a review, you're able to pass -m followed by the message, as you'd expect. The <file> and <line> at this point are both optional however, so something like the following would be fine:

git appraise comment -m "Nice code!" 2c9bff89f0f8

Would it be unreasonable to suggest allowing the commenter to leave out the -m, much like how you'd write a proper commit message, by opening the text editor associated with git, to then write a more detailed comment?

Change the docs to refer to "Robot Comments" as "Analyses Notes" instead

The meaning of the term "Robot Comments" is not intuitively obvious, so we should switch to something that is.

This came from the suggestion @andreineculau made in #39

panic while execute accept command

Base on the README.md file, while execute 'accept' command it panic:

/tmp/appraise: git appraise accept 41592
panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x1 addr=0xa0 pc=0x121de63]

goroutine 1 [running]:
github.com/google/git-appraise/review.GetSummary(0x13d8f20, 0xc4200771f0, 0x7fff5fbff1f4, 0x5, 0xc42004fd00, 0x0, 0x0)
/Users/jiaxi/code/golang/src/github.com/google/git-appraise/review/review.go:245 +0x173
github.com/google/git-appraise/review.Get(0x13d8f20, 0xc4200771f0, 0x7fff5fbff1f4, 0x5, 0x0, 0x0, 0x0)
/Users/jiaxi/code/golang/src/github.com/google/git-appraise/review/review.go:286 +0x4d
github.com/google/git-appraise/commands.acceptReview(0x13d8f20, 0xc4200771f0, 0xc42007c0b0, 0x1, 0x1, 0x100d374, 0x12b7601)
/Users/jiaxi/code/golang/src/github.com/google/git-appraise/commands/accept.go:48 +0xb7
github.com/google/git-appraise/commands.glob..func4(0x13d8f20, 0xc4200771f0, 0xc42007c0b0, 0x1, 0x1, 0xc420064d00, 0x9)
/Users/jiaxi/code/golang/src/github.com/google/git-appraise/commands/accept.go:93 +0x53
github.com/google/git-appraise/commands.(*Command).Run(0x13f60c0, 0x13d8f20, 0xc4200771f0, 0xc42007c0b0, 0x1, 0x1, 0x0, 0xc42007cdb0)
/Users/jiaxi/code/golang/src/github.com/google/git-appraise/commands/commands.go:39 +0x5c
main.main()
/Users/jiaxi/code/golang/src/github.com/google/git-appraise/git-appraise/git-appraise.go:100 +0x38c

Add -z flag for parsing output

Add -z flag for parsing output of command line.
Like git command line option -z.
use \0 instead of '\n' to separate multiple entries.

Filename or path using in comment is not validated

The command below falsely succeeds, even though the filename or path is invalid:
git appraise comment -f missspelled.go -m 'some message'

These comments seem to end up in the object referenced by .git/refs/notes/devtools/discuss and cause an error when listing with:

git appraise show <sha>
> comments (2 threads):
> ... comment 1 ...
> fatal: Path 'missspelled.go' does not exist in '<sha>'

All comments, including the bad one, can be seen in the --json output.

It would also be nice to have guidance on editing/amending comments before pushing, since naively using git notes remove <sha> does not appear to work(?)

In the meantime I discovered that it was possible to checkout the comments into their own branch and remove the problem comment usinggit rebase --interactive:

git checkout -B comments refs/notes/devtools/discuss
git rebase -i HEAD~2
drop the commit, and manually fix the merge after git rebase --continue
git update-ref refs/notes/devtools/discuss comments
git checkout master
git branch -D comments

Better support the 0-state

Right now git-appraise assumes that there is an existing target ref and review ref, which have different head commits but for which there is a merge base.

Those assumptions are fine for most usage, but it is easy for someone just trying out git-appraise for the first time to not satisfy them, and the existing error message can be quite cryptic when that happens.

To improve this situation, we should change the user experience in the following situations:

1. If the target ref (by default refs/heads/master) does not exist, but the review ref does:
   We should support this as a valid use case, and create a review anchored at the first (oldest) commit.
2. If both the target ref and review ref exist, but they have no commits in common (and, thus, no merge base):
   This is conceptually quite similar to the first scenario. We should support this as a valid use case, and create a review anchored at the first (oldest) commit in the review ref.
3. If neither the target nor the review ref exists:
   This is not a valid use case, but the current error message ("fatal: 'refs/heads/master' - not a valid ref") does not explain that. We should change this to something like "You cannot create a review in an empty repository. First, commit the changes that you want to review".
4. If the target and review ref are the same:
   This is not a valid use case, but the current error message ("There are no commits included in the review request") does not explain that. We should change this to something like "Before you can create a review you need to have two different branches to compare".

There is also the scenario that the target ref exists but the review ref does not. However, that is not a valid scenario, and the current error message is probably sufficient.

All possible validation checks should be done before prompting the user to enter a message

In comment.go the user may be prompted to enter a message via their configured text editor. The same issue applies to pull request #18

Command line argument checks (e.g. "You cannot combine the flags -lgtm and -nmw") and other checks (e.g. "There is no matching review") are currently performed after the user had already entered their commit message.

These checks should be done before prompting the user for a message. Otherwise the user will be prompted to enter their message again and again, whilst they get the command arguments right, or whilst they figure out what the cause of the error message is.

Go Module support

This tool is installable via brew. As go 1.17 comes out unless this project adds go module support it will not be installable and it may have to be removed from brew.

Would it be possible to migrate to using go modules

See Homebrew/homebrew-core#47627

Support GPG signing review metadata.

It would be a big improvement if we provided a way of authenticating review metadata (i.e. git-notes).

To do that, I think we should try to imitate the model git uses for GPG signing commits.

This would mean adding a -S flag to all of the git appraise subcommands that generate review metadata (e.g. review requests, comments, etc). That metadata would then be signed prior to being written. We would use the user's GPG key defined in the user.signingkey config setting to generate this signature. Additionally, the generated git-notes commits would be signed with that same key.

When displaying reviews/comments/etc, we would include information about whether or not the metadata was signed and whether or not the signature could be verified.

We would also want to add a --verify-signatures flag to the git appraise pull command which would cause the merge to fail if any of the incoming git-notes commits or review metadata were not verifiably signed. This would correspond to the same, existing flag in the git merge command. The git appraise pull command should also take a -S flag to cause the git-notes merge commit to be signed. If the --verify-signatures flag is provided then the -S flag should be implied.

To sign a metadata entry, we could do something like the following:

1. Add a signature field to the various JSON schemas.
2. Initially fill in that field with a placeholder value like gpgsignature.
3. Serialize the JSON object as a single line string.
4. Generate a detached GPG signature of this string.
5. Encode the generated signature as a single-line JSON string.
6. Replace the placeholder value with the encoded signature.
7. Write out this final value as the actual git-notes entry.
8. Verifying the signature would then involve running that process in reverse.

This would mean that signing changes and checking signatures would be an optional feature that each individual community could decide for itself whether or not to adopt.

We should also provide some way of distributing the public GPG keys of contributors inside of the repository. The best approach would probably be to replicate the logic we are using in #88 for storing the list of forks in the repository.

Parent comment hash is not validated

The command below falsely succeeds, even though the parent hash is invalid:
git appraise comment -p anyArbitraryString -m 'some message'

These orphan comments seem to end up in the object referenced by .git/refs/notes/devtools/discuss:

$ git appraise comment -p anyArbitraryString -m message1
$ git appraise comment -p anything -m message2
$ git appraise comment -p blah -m message3

$ cat .git/refs/notes/devtools/discuss
963045ca0ab34dcd5917fec785beddff37dc997d

$ git show 963045ca0ab34dcd5917fec785beddff37dc997d
 {"timestamp":"$TIMESTAMP","author":"$AUTHOR","parent":"someArbitraryString","location":{"commit":"c685f115aa84e8bf7b795eceaf38b95fc0b18414"},"description":"message1","resolved":false}

 {"timestamp":"$TIMESTAMP","author":"$AUTHOR","parent":"anything","location":{"commit":"c685f115aa84e8bf7b795eceaf38b95fc0b18414"},"description":"message2","resolved":false}
+
+{"timestamp":"$TIMESTAMP","author":"$AUTHOR","parent":"blah","location":{"commit":"c685f115aa84e8bf7b795eceaf38b95fc0b18414"},"description":"message3","resolved":false}

Submitting a rewritten branch creates a new review

I have submitted a first version of my branch for review, the review was rejected because I needed to fix something. I fixed what I was asked to, used commit --amend, and submitted again. Instead of reusing the existing (rejected) review and appending to the discussion, it created a brand new review as if the first one didn't exist, thus losing history.

Community chat ?

Is there a place where the community hangs for discussions ? I'd have many questions .. I'd like to learn more about appraise, the plans the direction, etc.. what about gophers.slack.com ?

Missing endLine property for range in comment schema?

I just came across this project, looks very interesting!

While browsing the comment schema, I saw that a range has a startLine but no endLine:

https://github.com/google/git-appraise/blob/master/schema/comment.json#L35

Was this an oversight or am I just missing something? (The latter is more likely I think)

Add manpage

it would be nice to have a manpage (maybe just including some of the current docs) that can show up in git help appraise

Link to Eclipse and Jenkins plugins in README?

It's currently kinda hard to find out about them. It would also be good to show off how git-appraise shines when integrated into other tools.

Support comments that are detached from any review.

The git-appraise tool supports commenting on arbitrary locations in the repository, but it only does so in the context of reviewing a commit.

It would be nice if we could also support commenting on arbitrary locations in the source code without having to wait for a code review.

For example, this could allow someone to pair git-appraise with the git-sync-changes tool to build real-time pair-programming tools on top of git.

My initial thoughts on how this could be done:

1. Extend git appraise comment by adding a -d flag to indicate that the comment is attached to any review.
2. Extend the git appraise show command by allowing you to specify a file path instead of a review hash, and then having it show you the detached comments for that path.

Since git-notes always have to be attached to a git-object, we could define a fixed, well-known object to anchor these detached comments. For example, we could pick a "zero" commit of 71ee2d2204443f001fde5aa510ec956d7f90e5e1, which can always be recreated with the following command:

echo "" | \
    GIT_AUTHOR_NAME="nobody" \
    GIT_AUTHOR_EMAIL="nobody" \
    GIT_AUTHOR_DATE="100000000 +0000" \
    GIT_COMMITTER_NAME="nobody" \
    GIT_COMMITTER_EMAIL="nobody" \
    GIT_COMMITTER_DATE="100000000 +0000" \
    git commit-tree `git hash-object -t tree /dev/null`

We could then save that commit to a ref like refs/devtools/archives/71ee2d2204443f001fde5aa510ec956d7f90e5e1 to make sure it does not get garbage collected.

When adding a comment for a path, we would create a new comment struct for that path at the specified commit (defaulting to HEAD if no commit is specified), serialize it, and add it to the git notes for the well-known commit under refs/notes/discuss.

When listing the comments for a path, we would parse the git-notes for the well-known commit under refs/notes/discuss, and then filter out any whose location does not match the provided path.

That would not preserve comments after a file rename, but a caller could account for this by computing the previous file names using the command git log --follow --name-only --pretty=format:"" ${FILENAME}, and then listing all of the detached comments for every previous path.

There is a risk that the use of a single well-known commit might pose a scaling bottleneck, so we will have to load test this with lots of comments to see how well it scales. If that is a issue, then we could use a different, reproducible commit object for each path (such as by adding a message to the otherwise empty commit specifying the matching path).

rejecting/closing a request?

Hey team, what is the best approach to reject/close a request?

An argument could be made that keeping a history of comments on rejected requests might be useful so that mistakes are not repeated.

Provide a way to comment commits other than at branch head

For example: refs/heads/feature -> 0123456789012345678901234567890123456789
parent commit 01234567890123456789012345678901234567AB
parent commit 01234567890123456789012345678901234567CD
parent commit (refs/heads/master) -> 01234567890123456789012345678901234567EF

I can only comment on 0123456789012345678901234567890123456789.
I need to also comment on 01234567890123456789012345678901234567CD