Merge branch 'stable-2.6' into stable-2.7

* stable-2.6:
  Fix spelling errors in access-control.txt
  Access control documentation: Formatting
  Access control documentation: Clean up of categories
  Access Control Documentation: Explain special and magic refs
  Set core plugins to correct revisions for 2.6-rc2
  Update developer instructions for cloning the Gerrit project
  Fix Windows build

Change-Id: Ic6a27ddffed8521f10aaca9ca6619840174be1ff

Documentation/access-control.txt

@@ -15,6 +15,7 @@ and membership management.  The identity of these groups is set
 in the `system_config` table within the database, so the groups
 can be renamed after installation if desired.
 
+
 [[administrators]]
 Administrators
 ~~~~~~~~~~~~~~
@@ -33,6 +34,7 @@ approval or submit rights in projects.  This is a feature designed
 to permit administrative users to otherwise access Gerrit as any
 other normal user would, without needing two different accounts.
 
+
 [[anonymous_users]]
 Anonymous Users
 ~~~~~~~~~~~~~~~
@@ -48,12 +50,13 @@ without requiring sign in first.  Currently it is only worthwhile
 to grant `Read` access to this group as Gerrit requires an account
 identity for all other operations.
 
+
 [[non-interactive_users]]
 Non-Interactive Users
 ~~~~~~~~~~~~~~~~~~~~~
 
 This is an internal user group, members of this group are not expected
-to perform interactive operations on the Gerrit web frontend.
+to perform interactive operations on the Gerrit web front-end.
 
 However, sometimes such a user may need a separate thread pool in
 order to prevent it from grabbing threads from the interactive users.
@@ -63,6 +66,7 @@ made by the non-interactive users from the ones made by the interactive
 users. This ensures that the interactive users can keep working when
 resources are tight.
 
+
 [[project_owners]]
 Project Owners
 ~~~~~~~~~~~~~~
@@ -80,6 +84,7 @@ project.  Having default access rights for
 avoid the need to initially configure access rights for
 newly created child projects.
 
+
 [[registered_users]]
 Registered Users
 ~~~~~~~~~~~~~~~~
@@ -134,6 +139,7 @@ This configuration can help prevent accidental submits when the
 members of `Foo` have submit rights on a project, and the members of
 `Foo-admin` typically do not need to have such rights.
 
+
 [[ldap_groups]]
 LDAP Groups
 -----------
@@ -255,6 +261,7 @@ would be needed:
 |Foo Leads       |refs/heads/qa |Code-Review| -2..+2 |
 |==============================================================
 
+
 OpenID Authentication
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -264,6 +271,7 @@ the `Anonymous Users` and `Registered Users` groups, unless *all*
 of its OpenID identities match one or more of the patterns listed
 in the `auth.trustedOpenID` list from `gerrit.config`.
 
+
 All Projects
 ~~~~~~~~~~~~
 
@@ -283,6 +291,7 @@ group gives nearly the same level of access as membership in
 `Administrators` does, as group members would be able to alter
 permissions for every managed project including global capabilities.
 
+
 Per-Project
 ~~~~~~~~~~~
 
@@ -292,24 +301,121 @@ behavior is generally only useful on the `Read` category when
 granting 'DENY' within a specific project to deny a group access.
 
 
-[[access_labels]]
-Review Labels
--------------
+[[references]]
+Special and magic references
+----------------------------
 
-For every configured label `My-Name` in the project, there is a
-corresponding permission `label-My-Name` with a range corresponding to
-the defined values.
+The reference namespaces used in git are generally two, one for branches and
+one for tags:
 
-Gerrit comes pre-configured with several default labels that can be
-granted to groups within projects, enabling functionality for that
-group's members. link:config-labels.html[Custom labels] may also be
-defined globally or on a per-project basis.
+* +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_categories]]
+Access Categories
+-----------------
+
+Gerrit has several permission categories that can be granted to groups
+within projects, enabling functionality for that group's members.
 
 With the release of the Gerrit 2.2.x series, the web GUI for ACL
 configuration was rewritten from scratch.  Use this
 <<conversion_table,table>> to better understand the access rights
 conversions from the Gerrit 2.1.x to the Gerrit 2.2.x series.
 
+
 [[category_abandon]]
 Abandon
 ~~~~~~~
@@ -321,6 +427,7 @@ change to a given ref.
 This also grants the permission to restore a change if the change
 can be uploaded.
 
+
 [[category_create]]
 Create reference
 ~~~~~~~~~~~~~~~~
@@ -500,7 +607,7 @@ Push Merge Commits
 ~~~~~~~~~~~~~~~~~~~~
 
 The `Push Merge Commit` access right permits the user to upload merge
-commits.  It's an addon to the <<category_push,Push>> access right, and
+commits.  It's an add-on to the <<category_push,Push>> access right, and
 so it won't be sufficient with only `Push Merge Commit` granted for a
 push to happen.  Some projects wish to restrict merges to being created
 by Gerrit. By granting `Push` without `Push Merge Commit`, the only
@@ -513,6 +620,7 @@ This applies even for an entry that complements a `Push` entry for
 the intention of the `Push Merge Commit` entry is to allow direct pushes
 of merge commits.
 
+
 [[category_push_annotated]]
 Push Annotated Tag
 ~~~~~~~~~~~~~~~~~~
@@ -622,6 +730,7 @@ Users without this access right who are able to upload new patch sets
 can still do the rebase locally and upload the rebased commit as a new
 patch set.
 
+
 [[category_remove_reviewer]]
 Remove Reviewer
 ~~~~~~~~~~~~~~~
@@ -637,6 +746,20 @@ Users without this access right can only remove themselves from the
 reviewer list on a change.
 
 
+[[category_review_labels]]
+Review Labels
+~~~~~~~~~~~~~
+
+For every configured label `My-Name` in the project, there is a
+corresponding permission `label-My-Name` with a range corresponding to
+the defined values.
+
+Gerrit comes pre-configured with a default 'Code-Review' label that can
+be granted to groups within projects, enabling functionality for that
+group's members. link:config-labels.html[Custom labels] may also be
+defined globally or on a per-project basis.
+
+
 [[category_submit]]
 Submit
 ~~~~~~
@@ -711,6 +834,7 @@ rights these roles typically should be granted. You may see them as
 general guidelines for a typical way to set up your project on a
 brand new Gerrit instance.
 
+
 [[examples_contributor]]
 Contributor
 ~~~~~~~~~~~
@@ -767,7 +891,7 @@ Optional access rights to grant:
 CI system
 ~~~~~~~~~
 
-A typical Continous Integration system should be able to download new changes
+A typical Continuous Integration system should be able to download new changes
 to build and then leave a verdict somehow.
 
 As an example, the popular
@@ -840,7 +964,7 @@ power in the form of being able to delete branches.  Optionally these users
 also have the power to configure access rights in gits assigned to them.
 
 [WARNING]
-These users should be really knowledgable about git, for instance knowing why
+These users should be really knowledgeable about git, for instance knowing why
 tags never should be removed from a server.  This role is granted potentially
 destructive access rights and cleaning up after such a mishap could be time
 consuming!
@@ -854,6 +978,7 @@ Optional access right to grant:
 
 * <<category_owner,`Owner`>> in the gits they mostly work with.
 
+
 [[examples_administrator]]
 Administrator
 ~~~~~~~~~~~~~
@@ -871,6 +996,7 @@ Suggested access rights to grant:
 
 * <<examples_project-owner,Project owner rights>>
 
+
 Enforcing site wide access policies
 -----------------------------------
 
@@ -895,6 +1021,7 @@ non-blocked rules as they wish. This gives best of both worlds:
 * Project owners can manage access rights of their projects without a danger
   of violating a site wide policy
 
+
 [[block]]
 'BLOCK' access rule
 ~~~~~~~~~~~~~~~~~~~
@@ -943,6 +1070,7 @@ inside the same access section of the same project. An 'ALLOW' rule in a
 different access section of the same project or in any access section in an
 inheriting project cannot override a 'BLOCK' rule.
 
+
 Examples
 ~~~~~~~~
 
@@ -972,6 +1100,7 @@ owners>> are allowed to create tags, we would extend the example above:
     pushTag = group Project Owners
 ====
 
+
 Let only a dedicated group vote in a special category
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -985,10 +1114,11 @@ category. In the "`All-Projects`" we define the following rules:
 
 ====
   [access "refs/heads/stable*"]
-    label-Release-Proces = block -1..+1 group Anonymous Users
-    label-Release-Proces = -1..+1 group Release Engineers
+    label-Release-Process = block -1..+1 group Anonymous Users
+    label-Release-Process = -1..+1 group Release Engineers
 ====
 
+
 [[conversion_table]]
 Conversion table from 2.1.x series to 2.2.x series
 --------------------------------------------------
@@ -1020,7 +1150,7 @@ Conversion table from 2.1.x series to 2.2.x series
 In Gerrit 2.2.x, the way to set permissions for upload has changed entirely.
 To upload a change for review is no longer a separate permission type,
 instead you grant ordinary push permissions to the actual
-recieving reference. In practice this means that you set push permissions
+receiving reference. In practice this means that you set push permissions
 on `refs/for/refs/heads/<branch>` rather than permissions to upload changes
 on `refs/heads/<branch>`.
 
@@ -1084,6 +1214,7 @@ Allow project creation.  This capability allows the granted group to
 either link:cmd-create-project.html[create new git projects via ssh]
 or via the web UI.
 
+
 [[capability_emailReviewers]]
 Email Reviewers
 ~~~~~~~~~~~~~~~
@@ -1094,6 +1225,7 @@ Instead, only the authors of the change and those who starred it will be
 emailed.  The allow rules are evaluated before deny rules, however the default
 is to allow emailing, if no explicit rule is matched.
 
+
 [[capability_flushCaches]]
 Flush Caches
 ~~~~~~~~~~~~
@@ -1113,7 +1245,7 @@ Kill Task
 Allow the operation of the link:cmd-kill.html[kill command over ssh].  The
 kill command ends tasks that currently occupy the Gerrit server, usually
 a replication task or a user initiated task such as an upload-pack or
-recieve-pack.
+receive-pack.
 
 
 [[capability_priority]]

Documentation/config-labels.txt

@@ -4,9 +4,9 @@ Gerrit Code Review - Review Labels
 As part of the code review process, reviewers score each change with
 values for each label configured for the project.  The label values that
 a given user is allowed to set are defined according to the
-link:access-control.html#access_labels[access controls].  Gerrit comes
-pre-configured with the Code-Review label that can be granted to groups
-within projects, enabling functionality for that group's members.
+link:access-control.html#category_review_labels[access controls].  Gerrit
+comes pre-configured with the Code-Review label that can be granted to
+groups within projects, enabling functionality for that group's members.
 
 
 [[label_Code-Review]]

Documentation/dev-readme.txt

@@ -11,10 +11,13 @@ Get the Source
 Create a new client workspace:
 
 ----
-  git clone https://gerrit.googlesource.com/gerrit
+  git clone --recursive https://gerrit.googlesource.com/gerrit
   cd gerrit
 ----
 
+The `--recursive` option is needed on `git clone` to ensure that
+the core plugins, which are included as git submodules, are also
+cloned.
 
 Configuring Eclipse
 -------------------

tools/version.sh

@@ -52,7 +52,7 @@ case "$V" in
 v*) V=$(echo "$V" | perl -pe s/^v//) ;;
 esac
 
-perl -pi -e '
+perl -pi.bak -e '
 	if ($ARGV ne $old_argv) {
 		$seen_version = 0;
 		$old_argv = $ARGV;
@@ -62,3 +62,8 @@ perl -pi -e '
 		s{(<version>).*(</version>)}{${1}'"$V"'${2}};
 	}
 	' $POM_FILES
+
+for pom in $POM_FILES
+do
+	rm -f ${pom}.bak
+done