Merge "Documentation: Add documentation of refs/notes/review"

Documentation/index.txt

@@ -22,6 +22,7 @@ User Guide
 * link:user-custom-dashboards.html[Custom Dashboards]
 * link:user-notify.html[Subscribing to Email Notifications]
 * link:user-submodules.html[Subscribing to Git Submodules]
+* link:refs-notes-review.html[The `refs/notes/review` namespace]
 
 Installation
 ------------

Documentation/pgm-ExportReviewNotes.txt

@@ -3,7 +3,7 @@ ExportReviewNotes
 
 NAME
 ----
-ExportReviewNotes - Export successful reviews to refs/notes/review
+ExportReviewNotes - Export successful reviews to link:refs-notes-review.html[refs/notes/review]
 
 SYNOPSIS
 --------

Documentation/refs-notes-review.txt

@@ -0,0 +1,111 @@
+The refs/notes/review namespace
+===============================
+
+Summary
+-------
+
+`refs/notes/review` is a special reference that Gerrit creates on repositories
+to store information about code reviews.
+
+When a repository is cloned from Gerrit, the `refs/notes/review` reference is
+not included by default.  It has to be manually fetched:
+
+====
+  $ git fetch origin refs/notes/review:refs/notes/review
+====
+
+It is also possible to
+link:http://www.kernel.org/pub/software/scm/git/docs/git-config.html[configure git]
+to always fetch `refs/notes/review`:
+
+====
+  $ git config --add remote.origin.fetch refs/notes/review:refs/notes/review
+  $ git fetch
+====
+
+When `refs/notes/review` is fetched on a repository, the Gerrit review
+information can be included in the git log output:
+
+====
+   $ git log --show-notes=review
+====
+
+Content of refs/notes/review
+----------------------------
+
+For each commit, Gerrit stores the following review information in
+`refs/notes/review`:
+
+[[submitted_by]]
+Submitted-by
+~~~~~~~~~~~~
+
+The name and email address of the Gerrit user that submitted the change in
+link:http://www.ietf.org/rfc/rfc2822.txt[RFC 2822] format.
+
+====
+  Submitted-by: Random J Developer <random@developer.example.org>
+====
+
+[[submitted_at]]
+Submitted-at
+~~~~~~~~~~~~
+
+The time the commit was submitted in RFC 2822 time stamp format.
+
+====
+  Submitted-at: Mon, 25 Jun 2012 16:15:57 +0200
+====
+
+[[reviewed_on]]
+Reviewed-on
+~~~~~~~~~~~
+
+The URL to the change on the Gerrit server.
+
+====
+  Reviewed-on: http://path.to.gerrit/12345
+====
+
+[[review_scores]]
+Review Labels and Scores
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Review label and score, and the name and email address of the Gerrit user that
+gave it in RFC 2822 format:
+
+====
+  Code-Review+2: A. N. Other <another@developer.example.org>
+  Verified+1: A. N. Other <another@developer.example.org>
+====
+
+Commonly used review labels are "Code-Review" and "Verified", but any label
+configured in Gerrit can be included.
+
+All review labels and scores present on the change at the time of submit are
+included.
+
+[[project]]
+Project
+~~~~~~~
+
+The name of the project in which the commit was made.
+
+====
+  Project: kernel/common
+====
+
+[[branch]]
+Branch
+~~~~~~
+
+The name of the branch on which the commit was made.
+
+====
+  Branch: refs/heads/master
+====
+
+
+GERRIT
+------
+Part of link:index.html[Gerrit Code Review]