Merge "PatchSetInserter"
diff --git a/Documentation/access-control.txt b/Documentation/access-control.txt
index a3dc9d1..73072a7 100644
--- a/Documentation/access-control.txt
+++ b/Documentation/access-control.txt
@@ -292,6 +292,108 @@
granting 'DENY' within a specific project to deny a group access.
+[[references]]
+Special and magic references
+----------------------------
+
+The reference namespaces used in git are generally two, one for branches and
+one for tags:
+
+* +refs/heads/*+
+* +refs/tags/*+
+
+However, every reference under +refs/*+ is really available, and in Gerrit this
+opportunity for giving other refs a special meaning is used. In Gerrit they
+are sometimes used as magic/virtual references that give the push to Gerrit a
+special meaning.
+
+
+[[references_special]]
+Special references
+~~~~~~~~~~~~~~~~~~
+
+The special references have content that's either generated by Gerrit or
+contains important project configuration that Gerrit needs. When making
+changes to these references, Gerrit will take extra precautions to verify the
+contents compatibility at upload time.
+
+
+refs/changes/*
+^^^^^^^^^^^^^^
+
+Under this namespace each uploaded patch set for every change gets a static
+reference in their git. The format is convenient but still intended to scale to
+hundreds of thousands of patch sets. To access a given patch set you will
+need the change number and patch set number.
+
+[verse]
+'refs/changes/'<last two digits of change number>/
+ <change number>/
+ <patch set number>
+
+You can also find these static references linked on the page of each change.
+
+
+refs/meta/config
+^^^^^^^^^^^^^^^^
+
+This is where the Gerrit configuration of each project is residing. This
+branch contains several files of importance: +project.config+, +groups+ and
++rules.pl+. Torgether they control access and behaviour during the change
+review process.
+
+
+refs/meta/dashboards/*
+^^^^^^^^^^^^^^^^^^^^^^
+
+There's a dedicated page where you can read more about
+link:user-dashboards.html[User Dashboards].
+
+
+refs/notes/review
+^^^^^^^^^^^^^^^^^
+
+Autogenerated copy of review notes for all changes in the git. Each log entry
+on the refs/notes/review branch also references the patch set on which the
+review is made. This functionality is provided by the review-notes plugin.
+
+
+[[references_magic]]
+Magic references
+~~~~~~~~~~~~~~~~
+
+These are references with added functionality to them compared to a regular
+git push operation.
+
+
+refs/for/<branch ref>
+^^^^^^^^^^^^^^^^^^^^^
+
+Most prominent is the `refs/for/<branch ref>` reference which is the reference
+upon which we build the code review intercept before submitting a commit to
+the branch it's uploaded to.
+
+Further documentation on how to push can be found on the
+link:user-upload.html#push_create[Upload changes] page.
+
+
+refs/publish/*
+^^^^^^^^^^^^^^
+
+`refs/publish/*` is an alternative name to `refs/for/*` when pushing new changes
+and patch sets.
+
+
+refs/drafts/*
+^^^^^^^^^^^^^
+
+Push to `refs/drafts/*` creates a change like push to `refs/for/*`, except the
+resulting change remains hidden from public review. You then have the option
+of adding individual reviewers before making the change public to all. The
+change page will have a 'Publish' button which allows you to convert individual
+draft patch sets of a change into public patch sets for review.
+
+
[[access_labels]]
Review Labels
-------------
diff --git a/Documentation/dev-readme.txt b/Documentation/dev-readme.txt
index 2a9925b..73f1d68 100644
--- a/Documentation/dev-readme.txt
+++ b/Documentation/dev-readme.txt
@@ -165,6 +165,51 @@
----
+[[test-rest-api]]
+Testing the REST API
+~~~~~~~~~~~~~~~~~~~~
+
+Basic testing of REST API functionality can be done with `curl`:
+
+----
+ curl http://localhost:8080/path/to/api/
+----
+
+By default, `curl` sends `GET` requests. To test APIs with `PUT` or `POST`,
+an additional argument is required:
+
+----
+ curl -X PUT http://localhost:8080/path/to/api/
+ curl -X POST http://localhost:8080/path/to/api/
+----
+
+Some REST APIs accept data in the request body of `PUT` and `POST` requests.
+
+Test data can be included from a local file:
+
+----
+ curl -X PUT -d@testdata.txt --header "Content-Type: application/json" http://localhost:8080/path/to/api/
+----
+
+To test APIs that require authentication, the username and password must be specified on
+the command line:
+
+----
+ curl --digest --user username:password http://localhost:8080/path/to/api
+----
+
+This makes it easy to switch users for testing of permissions.
+
+It is also possible to test with a username and password from the `.netrc`
+file (on Windows, `_netrc`):
+
+----
+ curl --digest -n http://localhost:8080/a/path/to/api/
+----
+
+In both cases, the password should be the user's link:user-upload.html#http[HTTP password].
+
+
Release Builds
--------------
diff --git a/Documentation/rest-api.txt b/Documentation/rest-api.txt
index 303fc4b..195ca9b 100644
--- a/Documentation/rest-api.txt
+++ b/Documentation/rest-api.txt
@@ -5,6 +5,8 @@
The API is suitable for automated tools to build upon, as well as
supporting some ad-hoc scripting use cases.
+See also: link:dev-readme.html#test-rest-api[Developer setup: Testing the REST API].
+
Endpoints
---------
link:rest-api-accounts.html[/accounts/]::
diff --git a/pom.xml b/pom.xml
index b2aa21e..07c8992 100644
--- a/pom.xml
+++ b/pom.xml
@@ -46,7 +46,7 @@
</issueManagement>
<properties>
- <jgitVersion>2.3.1.201302201838-r.208-g75e1bdb</jgitVersion>
+ <jgitVersion>2.3.1.201302201838-r.211-g36144e1</jgitVersion>
<gwtormVersion>1.6</gwtormVersion>
<gwtjsonrpcVersion>1.3</gwtjsonrpcVersion>
<gwtVersion>2.5.0</gwtVersion>
