Browse Source

Added an initial README file

root 5 years ago
commit
b346936104
2 changed files with 209 additions and 0 deletions
  1. 2 0
      .gitignore
  2. 207 0
      README.md

+ 2 - 0
.gitignore

@@ -0,0 +1,2 @@
+*~
+bin/

+ 207 - 0
README.md

@@ -0,0 +1,207 @@
+# Git Code Review Tool
+
+This repo contains a command line tool for performing code reviews on git
+repositories.
+
+## Installation
+
+Assuming you have the [Go tools installed](https://golang.org/doc/install), run
+the following command:
+
+    go get source.developers.google.com/id/0tH0wAQFren.git/src
+
+Then, to add "review" git alias, run the following command.
+
+    git config --global alias.review "!git-review"
+
+## 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 review request
+
+Pushing code reviews to a remote:
+
+    git review push [<remote>]
+
+Pulling code reviews from a remote:
+
+    git review pull [<remote>]
+
+Listing open code reviews:
+
+    git review list
+
+Showing the status of the current review, including comments:
+
+    git review show
+
+Commenting on a review:
+
+    git review comment -m "<message>" [<file> [<line>]]
+
+Accepting the changes in a review:
+
+    git review accept [-m "<message>"]
+
+Submitting a review:
+
+    git review submit [--merge | --rebase]
+
+Continuously push and pull reviews to/from a remote:
+
+    git review sync [<remote>]
+
+## 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.
+
+### 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 following
+schema.
+
+    {
+      "$schema": "http://json-schema.org/draft-04/schema#",
+      "type": "object",
+      "properties": {
+        "reviewRef": {
+          "id": "reviewRef",
+          "type": "string"
+        },
+        "targetRef": {
+          "id": "targetRef",
+          "type": "string"
+        },
+        "reviewers": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "description": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "targetRef"
+      ]
+    }
+
+The "reviewRef" field is used to specify a git ref that tracks the current
+revision under review, and the "targetRef" field is used to specify the git ref
+that should be updated once the review is approved.
+
+### 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 confirm to the following schema, which is taken from the Note
+protocol buffer message defined
+[here](https://github.com/google/shipshape/blob/master/shipshape/proto/note.proto).
+
+    {
+      "$schema": "http://json-schema.org/draft-04/schema#",
+      "type": "object",
+      "properties": {
+        "location": {
+          "type": "object",
+          "properties": {
+            "path": {
+              "type": "string"
+            },
+            "range": {
+              "type": "object",
+              "properties": {
+                "startLine": {
+                  "type": "integer"
+                }
+              }
+            }
+          }
+        },
+        "category": {
+          "type": "string"
+        },
+        "description": {
+          "id": "description",
+          "type": "string"
+        }
+      },
+      "required": [
+        "description"
+      ]
+    }
+
+### 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 confirm to the following
+schema.
+
+    {
+      "$schema": "http://json-schema.org/draft-04/schema#",
+      "type": "object",
+      "properties": {
+        "timestamp": {
+          "type": "string"
+        },
+        "author": {
+          "type": "string"
+        },
+        "parent": {
+          "type": "string"
+        },
+        "location": {
+          "type": "object",
+          "properties": {
+            "commit": {
+              "type": "string"
+            },
+            "path": {
+              "type": "string"
+            },
+            "range": {
+              "type": "object",
+              "properties": {
+                "startLine": {
+                  "type": "integer"
+                }
+              }
+            }
+          }
+        },
+        "description": {
+          "type": "string"
+        },
+        "resolved": {
+          "type": "boolean"
+        }
+      }
+    }
+
+When the parent is specified, it must be the SHA1 hash of another comment on
+the same revision, and it means this comment is a reply to that comment.
+
+The timestamp field represents the number of seconds since the Unix epoch, and
+is formatted as a 10 digit decimal number with zero padding. It should be the
+first field written, so that the lexicographical ordering of comments matches
+their chronological ordering.