Merge changes Ifccd40c8,I3fc7a181 into stable

* changes:
  Access control documentation: Final cleanup
  Access control documentation: Read and Submit

4 files changed, 62 insertions, 71 deletions

diff --git a/Documentation/access-control.txt b/Documentation/access-control.txt
index ffeb62f97b..fdf40a01c3 100644
--- a/Documentation/access-control.txt
+++ b/Documentation/access-control.txt
@@ -1,17 +1,6 @@
 Gerrit Code Review - Access Controls
 ====================================
 
-.Disclaimer
-****
-This documentation is outdated.
-
-In Gerrit 2.2.x the way how the access rights are configured has
-changed, but this documentation was not updated yet.
-
-This documentation still describes the access rights configuration as
-it was in Gerrit 2.1.8 and before.
-****
-
 Access controls in Gerrit are group based.  Every user account is a
 member of one or more groups, and access and privileges are granted
 to those groups.  Access rights cannot be granted to individual
@@ -56,7 +45,7 @@ Any access rights assigned to this group are inherited by all users.
 Administrators and project owners can grant access rights to this
 group in order to permit anonymous users to view project changes,
 without requiring sign in first.  Currently it is only worthwhile
-to grant `Read Access` to this group as Gerrit requires an account
+to grant `Read` access to this group as Gerrit requires an account
 identity for all other operations.
 
 [[non-interactive_users]]
@@ -96,7 +85,7 @@ Registered Users
 ~~~~~~~~~~~~~~~~
 
 All signed-in users are automatically a member of this group (and
-also 'Anonymous Users', see above).
+also <<anonymous_users,'Anonymous Users'>>, see above).
 
 Any access rights assigned to this group are inherited by all
 users as soon as they sign-in to Gerrit.  If OpenID authentication
@@ -109,7 +98,7 @@ allowing signed-in users to vote on a change, but not actually
 cause it to become approved or rejected.
 
 Registered users are always permitted to make and publish comments
-on any change in any project they have `Read Access` to.
+on any change in any project they have `Read` access to.
 
 
 Account Groups
@@ -205,12 +194,12 @@ the `refs/heads/qa` branch, and the following ACLs are granted
 on the project:
 
 [options="header"]
-|=====================================================
-|Group            |Reference Name|Category   |Range
-|Registered Users |refs/heads/*  |Code Review| -1..+1
-|Foo Leads        |refs/heads/*  |Code Review| -2..+2
-|QA Leads         |refs/heads/qa |Code Review| -2..+2
-|=====================================================
+|===============================================================
+|Group            |Reference Name|Category   |Range   |Exclusive
+|Registered Users |refs/heads/*  |Code Review| -1..+1 |
+|Foo Leads        |refs/heads/*  |Code Review| -2..+2 |
+|QA Leads         |refs/heads/qa |Code Review| -2..+2 |
+|===============================================================
 
 Then the effective range permitted to be used by the user is
 `-2..+2`, as the user's membership of `Foo Leads` effectively grant
@@ -220,20 +209,21 @@ Gerrit also supports exclusive reference-level access control.
 
 It is possible to configure Gerrit to grant an exclusive ref level
 access control so that only users of a specific group can perform
-an operation on a project/reference pair. This is done by prefixing
-the reference specified with a `'-'`.
+an operation on a project/reference pair. This is done by ticking
+the exclusive flag when setting the permission for the
+`refs/heads/qa` branch.
 
 For example, if a user who is a member of `Foo Leads` tries to
 review a change destined for branch `refs/heads/qa` in a project,
 and the following ACLs are granted:
 
 [options="header"]
-|=====================================================
-|Group           |Reference Name|Category   |Range
-|Registered Users|refs/heads/*  |Code Review| -1..+1
-|Foo Leads       |refs/heads/*  |Code Review| -2..+2
-|QA Leads        |-refs/heads/qa|Code Review| -2..+2
-|=====================================================
+|==============================================================
+|Group           |Reference Name|Category   |Range   |Exclusive
+|Registered Users|refs/heads/*  |Code Review| -1..+1 |
+|Foo Leads       |refs/heads/*  |Code Review| -2..+2 |
+|QA Leads        |refs/heads/qa |Code Review| -2..+2 |X
+|==============================================================
 
 Then this user will not have `Code Review` rights on that change,
 since there is an exclusive access right in place for the
@@ -246,13 +236,13 @@ In order to grant the ability to `Code Review` to the members of
 would be needed:
 
 [options="header"]
-|=====================================================
-|Group           |Reference Name|Category   |Range
-|Registered Users|refs/heads/*  |Code Review| -1..+1
-|Foo Leads       |refs/heads/*  |Code Review| -2..+2
-|QA Leads        |-refs/heads/qa|Code Review| -2..+2
-|Foo Leads       |refs/heads/qa |Code Review| -2..+2
-|=====================================================
+|==============================================================
+|Group           |Reference Name|Category   |Range   |Exclusive
+|Registered Users|refs/heads/*  |Code Review| -1..+1 |
+|Foo Leads       |refs/heads/*  |Code Review| -2..+2 |
+|QA Leads        |refs/heads/qa |Code Review| -2..+2 |X
+|Foo Leads       |refs/heads/qa |Code Review| -2..+2 |
+|==============================================================
 
 OpenID Authentication
 ~~~~~~~~~~~~~~~~~~~~~
@@ -287,9 +277,8 @@ Per-Project
 
 The per-project ACL is evaluated before the global `All-Projects` ACL,
 permitting some limited override capability to project owners. This
-behavior is generally only useful on the `Read Access` category when
-granting `-1 No Access` within a specific project to deny access to
-a group.
+behavior is generally only useful on the `Read` category when
+granting 'DENY' within a specific project to deny a group access.
 
 
 [[access_category]]
@@ -490,7 +479,6 @@ you grant the users the push force permission to be able to clean up
 stale branches.
 
 
-
 [[category_forge_author]]
 Forge Author
 ~~~~~~~~~~~~
@@ -676,38 +664,40 @@ To delete or overwrite an existing tag, grant `Push` with the force
 option enabled for reference name `refs/tags/*`, as deleting a tag
 requires the same permission as deleting a branch.
 
-[[category_READ]]
-Read Access
-~~~~~~~~~~~
 
-The `Read Access` category controls visibility to the project's
+[[category_read]]
+Read
+~~~~
+
+The `Read` category controls visibility to the project's
 changes, comments, code diffs, and Git access over SSH or HTTP.
-A user must have `Read Access +1` in order to see a project, its
+A user must have this access granted in order to see a project, its
 changes, or any of its data.
 
 This category has a special behavior, where the per-project ACL is
 evaluated before the global all projects ACL.  If the per-project
-ACL has granted `Read Access -1`, and does not otherwise grant
-`Read Access \+1`, then a `Read Access +1` in the all projects ACL
+ACL has granted `Read` with 'DENY', and does not otherwise grant
+`Read` with 'ALLOW', then a `Read` in the all projects ACL
 is ignored.  This behavior is useful to hide a handful of projects
 on an otherwise public server.
 
 For an open source, public Gerrit installation it is common to grant
-`Read Access +1` to `Anonymous Users` in the `\-- All Projects
-\--` ACL, enabling casual browsing of any project's changes,
-as well as fetching any project's repository over SSH or HTTP.
-New projects can be temporarily hidden from public view by granting
-`Read Access -1` to `Anonymous Users` and granting `Read Access +1`
-to the project owner's group within the per-project ACL.
+`Read` to `Anonymous Users` in the `All-Projects` ACL, enabling
+casual browsing of any project's changes, as well as fetching any
+project's repository over SSH or HTTP.  New projects can be
+temporarily hidden from public view by granting `Read` with 'DENY'
+to `Anonymous Users` and granting `Read` to the project owner's
+group within the per-project ACL.
 
 For a private Gerrit installation using a trusted HTTP authentication
-source, granting `Read Access +1` to `Registered Users` may be more
+source, granting `Read` to `Registered Users` may be more
 typical, enabling read access only to those users who have been
 able to authenticate through the HTTP access controls.  This may
 be suitable in a corporate deployment if the HTTP access control
 is already restricted to the correct set of users.
 
-[[category_SUBM]]
+
+[[category_submit]]
 Submit
 ~~~~~~
 
@@ -728,17 +718,15 @@ Your Category Here
 
 Gerrit administrators can also make up their own categories.
 
-See above for descriptions of how `Verified` and `Code Review` work,
-and insert your own category with `function_name = 'MaxWithBlock'`
-to get the same behavior over your own range of values, in any
-category you desire.
+See above for descriptions of how <<category_verified,`Verified`>>
+and <<category_review,`Code Review`>> work, and insert your own
+category with `function_name = 'MaxWithBlock'` to get the same
+behavior over your own range of values, in any category you desire.
 
 Ensure `category_id` is unique within your `approval_categories`
 table.  The default values `VRIF` and `CVRF` used for the categories
 described above are simply that, defaults, and have no special
-meaning to Gerrit.  The other standard category_id values like
-`OWN`, `READ`, `SUBM`, `pTAG` and `pHD` have special meaning and
-should not be modified or reused.
+meaning to Gerrit.
 
 The `position` column of `approval_categories` controls which column
 of the 'Approvals' table the category appears in, providing some
diff --git a/Documentation/error-not-a-gerrit-project.txt b/Documentation/error-not-a-gerrit-project.txt
index f6e90fa77f..368a102a9a 100644
--- a/Documentation/error-not-a-gerrit-project.txt
+++ b/Documentation/error-not-a-gerrit-project.txt
@@ -16,10 +16,11 @@ If you are facing this problem, do the following:
 . Verify that you are pushing to the correct Gerrit server.
 . Go in the Gerrit WebUI to 'Admin' -> 'Projects' and check that the
   project is listed. If the project is not listed the project either
-  does not exist or you don't have read access ('+1 Read Access' in
-  the link:access-control.html#category_READ['Read Access'] category) for it. This means if you certain that
-  the project name is right you should contact the Gerrit
-  Administrator or project owner to request access to the project.
+  does not exist or you don't have
+  link:access-control.html#category_read['Read'] access for it. This
+  means if you certain that the project name is right you should
+  contact the Gerrit Administrator or project owner to request access
+  to the project.
 
 This error message might be misleading if the project actually exists
 but the push is failing because the pushing user has no read access
diff --git a/Documentation/error-not-allowed-to-upload-merges.txt b/Documentation/error-not-allowed-to-upload-merges.txt
index 3b52bc249a..9aa144a028 100644
--- a/Documentation/error-not-allowed-to-upload-merges.txt
+++ b/Documentation/error-not-allowed-to-upload-merges.txt
@@ -6,13 +6,15 @@ pushing user has no permissions to upload merge commits for the
 project to which the push is done.
 
 If you need to upload merge commits, you can contact one of the
-project owners and request for this project permissions to upload
-merge commits (access right '+3 Upload merges permission' in the
-link:access-control.html#category_READ['Read Access'] category).
+project owners and request permissions to upload merge commits
+(access right link:access-control.html#category_push['Push'] and
+link:access-control.html#category_push_merge['Push merge']) for this
+project.
 
 If one of your changes could not be merged in Gerrit due to conflicts
 and you created the merge commit to resolve the conflicts, you might
-want to revert the merge and instead of this do a link:http://www.kernel.org/pub/software/scm/git/docs/git-rebase.html[rebase].
+want to revert the merge and instead of this do a
+link:http://www.kernel.org/pub/software/scm/git/docs/git-rebase.html[rebase].
 
 
 GERRIT
diff --git a/Documentation/error-upload-denied.txt b/Documentation/error-upload-denied.txt
index 947280f71a..5dec8abf09 100644
--- a/Documentation/error-upload-denied.txt
+++ b/Documentation/error-upload-denied.txt
@@ -8,8 +8,8 @@ push was done.
 There are two possibilities how to continue in this situation:
 
 . contact one of the project owners and request upload permissions
-  for the project (access right '+2 Upload permission' in the
-  link:access-control.html#category_READ['Read Access'] category)
+  for the project (access right
+  link:access-control.html#category_push['Push'])
 . export your commit as a patch using the link:http://www.kernel.org/pub/software/scm/git/docs/git-format-patch.html[git format-patch] command
   and provide the patch file to one of the project owners