Normalize Gerrit ACL documentation

It turns out that while changes to Gerrit ACLs from the WebUI will
create "Git config" format files which look somewhat like
traditional INI files with hard-tab indentation and other
unpleasantness, Gerrit will interpret more traditional INI files as
ACLs just fine and merge them to refs/meta/config unaltered. Adjust
the examples to look like the sorts of INI files with which our
developers are more familiar, and apply some other helpful
normalization like alphabetizing the section and key orders,
removing redundant default values or other no-ops, et cetera.

Change-Id: I3b9dad7b7beb05427eb4011fa6dad2a6dd4cbe72

doc/source/gerrit.rst

@@ -254,105 +254,122 @@ There will be two interesting files, `groups` and `project.config`.
 in `project.config`. UUIDs can be found on the group page in gerrit.
 Next, edit `project.config` to look like::
 
-  [project]
-      description = Rights inherited by all other projects
   [access "refs/*"]
-      read = group Anonymous Users
+  create = group Project Bootstrappers
-      pushTag = group Continuous Integration Tools
+  create = group Release Managers
-      pushTag = group Project Bootstrappers
+  forgeAuthor = group Registered Users
-      pushTag = group Release Managers
+  forgeCommitter = group Project Bootstrappers
-      forgeAuthor = group Registered Users
+  push = +force group Project Bootstrappers
-      forgeCommitter = group Project Bootstrappers
+  pushMerge = group Project Bootstrappers
-      push = +force group Project Bootstrappers
+  pushSignedTag = group Project Bootstrappers
-      create = group Project Bootstrappers
+  pushTag = group Continuous Integration Tools
-      create = group Release Managers
+  pushTag = group Project Bootstrappers
-      pushMerge = group Project Bootstrappers
+  pushTag = group Release Managers
-      pushSignedTag = group Project Bootstrappers
+  read = group Anonymous Users
-  [access "refs/heads/*"]
+
-      label-Code-Review = -2..+2 group Project Bootstrappers
-      label-Code-Review = -1..+1 group Registered Users
-      label-Verified = -2..+2 group Continuous Integration Tools
-      label-Verified = -2..+2 group Project Bootstrappers
-      label-Verified = -1..+1 group Voting Third-Party CI
-      label-Workflow = -1..+1 group Project Bootstrappers
-      label-Workflow = -1..+0 group Change Owner
-      submit = group Continuous Integration Tools
-      submit = group Project Bootstrappers
-  [access "refs/meta/config"]
-      read = group Project Owners
-  [access "refs/for/refs/*"]
-      push = group Registered Users
-  [access "refs/heads/milestone-proposed"]
-      exclusiveGroupPermissions = label-Code-Review label-Workflow
-      label-Code-Review = -2..+2 group Project Bootstrappers
-      label-Code-Review = -2..+2 group Release Managers
-      label-Code-Review = -1..+1 group Registered Users
-      owner = group Release Managers
-      label-Workflow = +0..+1 group Project Bootstrappers
-      label-Workflow = +0..+1 group Release Managers
-  [access "refs/heads/stable/*"]
-      forgeAuthor = group openstack-stable-maint
-      forgeCommitter = group openstack-stable-maint
-      exclusiveGroupPermissions = label-Code-Review label-Workflow
-      label-Code-Review = -2..+2 group Project Bootstrappers
-      label-Code-Review = -2..+2 group openstack-stable-maint
-      label-Code-Review = -1..+1 group Registered Users
-      label-Workflow = +0..+1 group Project Bootstrappers
-      label-Workflow = +0..+1 group openstack-stable-maint
-  [access "refs/meta/openstack/*"]
-      read = group Continuous Integration Tools
-      create = group Continuous Integration Tools
-      push = group Continuous Integration Tools
-  [capability]
-      administrateServer = group Administrators
-      priority = batch group Non-Interactive Users
-      createProject = group Project Bootstrappers
-      streamEvents = group Registered Users
-      runAs = group Project Bootstrappers
-  [access "refs/zuul/*"]
-      create = group Continuous Integration Tools
-      push = +force group Continuous Integration Tools
-      pushMerge = group Continuous Integration Tools
-  [access "refs/for/refs/zuul/*"]
-      pushMerge = group Continuous Integration Tools
-  [contributor-agreement "ICLA"]
-      description = OpenStack Individual Contributor License Agreement
-      requireContactInformation = true
-      agreementUrl = static/cla.html
-      autoVerify = group CLA Accepted - ICLA
-      accepted = group CLA Accepted - ICLA
-  [contributor-agreement "System CLA"]
-      description = DON'T SIGN THIS: System CLA (externally managed)
-      agreementUrl = static/system-cla.html
-      accepted = group System CLA
-  [contributor-agreement "USG CLA"]
-      description = DON'T SIGN THIS: U.S. Government CLA (externally managed)
-      agreementUrl = static/usg-cla.html
-      accepted = group USG CLA
-  [label "Verified"]
-      function = MaxWithBlock
-      value = -2 Fails
-      value = -1 Doesn't seem to work
-      value =  0 No score
-      value = +1 Works for me
-      value = +2 Verified
-  [label "Code-Review"]
-      function = MaxWithBlock
-      abbreviation = R
-      copyMinScore = true
-      copyAllScoresOnTrivialRebase = true
-      value = -2 Do not merge
-      value = -1 I would prefer that you didn't merge this
-      value =  0 No score
-      value = +1 Looks good to me, but someone else must approve
-      value = +2 Looks good to me (core reviewer)
-  [label "Workflow"]
-      function = MaxWithBlock
-      value = -1 Work in progress
-      value =  0 Ready for reviews
-      value = +1 Approved
   [access "refs/drafts/*"]
-      push = block group Registered Users
+  push = block group Registered Users
+
+  [access "refs/for/refs/*"]
+  push = group Registered Users
+
+  [access "refs/for/refs/zuul/*"]
+  pushMerge = group Continuous Integration Tools
+
+  [access "refs/heads/*"]
+  label-Code-Review = -2..+2 group Project Bootstrappers
+  label-Code-Review = -1..+1 group Registered Users
+  label-Verified = -2..+2 group Continuous Integration Tools
+  label-Verified = -2..+2 group Project Bootstrappers
+  label-Verified = -1..+1 group Voting Third-Party CI
+  label-Workflow = -1..+0 group Change Owner
+  label-Workflow = -1..+1 group Project Bootstrappers
+  submit = group Continuous Integration Tools
+  submit = group Project Bootstrappers
+
+  [access "refs/heads/milestone-proposed"]
+  exclusiveGroupPermissions = label-Code-Review label-Workflow
+  label-Code-Review = -2..+2 group Project Bootstrappers
+  label-Code-Review = -2..+2 group Release Managers
+  label-Code-Review = -1..+1 group Registered Users
+  label-Workflow = +0..+1 group Project Bootstrappers
+  label-Workflow = +0..+1 group Release Managers
+  owner = group Release Managers
+
+  [access "refs/heads/stable/*"]
+  exclusiveGroupPermissions = label-Code-Review label-Workflow
+  forgeAuthor = group openstack-stable-maint
+  forgeCommitter = group openstack-stable-maint
+  label-Code-Review = -2..+2 group Project Bootstrappers
+  label-Code-Review = -2..+2 group openstack-stable-maint
+  label-Code-Review = -1..+1 group Registered Users
+  label-Workflow = +0..+1 group Project Bootstrappers
+  label-Workflow = +0..+1 group openstack-stable-maint
+
+  [access "refs/meta/config"]
+  read = group Project Owners
+
+  [access "refs/meta/openstack/*"]
+  create = group Continuous Integration Tools
+  push = group Continuous Integration Tools
+  read = group Continuous Integration Tools
+
+  [access "refs/zuul/*"]
+  create = group Continuous Integration Tools
+  push = +force group Continuous Integration Tools
+  pushMerge = group Continuous Integration Tools
+
+  [capability]
+  administrateServer = group Administrators
+  createProject = group Project Bootstrappers
+  priority = batch group Non-Interactive Users
+  runAs = group Project Bootstrappers
+  streamEvents = group Registered Users
+
+  [contributor-agreement "ICLA"]
+  accepted = group CLA Accepted - ICLA
+  agreementUrl = static/cla.html
+  autoVerify = group CLA Accepted - ICLA
+  description = OpenStack Individual Contributor License Agreement
+  requireContactInformation = true
+
+  [contributor-agreement "System CLA"]
+  accepted = group System CLA
+  agreementUrl = static/system-cla.html
+  description = DON'T SIGN THIS: System CLA (externally managed)
+
+  [contributor-agreement "USG CLA"]
+  accepted = group USG CLA
+  agreementUrl = static/usg-cla.html
+  description = DON'T SIGN THIS: U.S. Government CLA (externally managed)
+
+  [label "Code-Review"]
+  abbreviation = R
+  copyAllScoresOnTrivialRebase = true
+  copyMinScore = true
+  function = MaxWithBlock
+  value = -2 Do not merge
+  value = -1 I would prefer that you didn't merge this
+  value = 0 No score
+  value = +1 Looks good to me, but someone else must approve
+  value = +2 Looks good to me (core reviewer)
+
+  [label "Verified"]
+  function = MaxWithBlock
+  value = -2 Fails
+  value = -1 Doesn't seem to work
+  value = 0 No score
+  value = +1 Works for me
+  value = +2 Verified
+
+  [label "Workflow"]
+  function = MaxWithBlock
+  value = -1 Work in progress
+  value = 0 Ready for reviews
+  value = +1 Approved
+
+  [project]
+  description = Rights inherited by all other projects
 
 Now edit the groups file. The format is::
 

doc/source/jeepyb.rst

@@ -88,18 +88,19 @@ a single project you will want to do the following:
    and each indentation is 8 spaces)::
 
      [access "refs/heads/*"]
-             label-Code-Review = -2..+2 group project-name-core
+     label-Code-Review = -2..+2 group project-name-core
-             label-Workflow = -1..+1 group project-name-core
+     label-Workflow = -1..+1 group project-name-core
+
      [access "refs/heads/milestone-proposed"]
-             label-Code-Review = -2..+2 group project-name-milestone
+     label-Code-Review = -2..+2 group project-name-milestone
-             label-Workflow = -1..+1 group project-name-milestone
+     label-Workflow = -1..+1 group project-name-milestone
-     [project]
+
-             state = active
      [receive]
-             requireChangeId = true
+     requireChangeId = true
-             requireContributorAgreement = true
+     requireContributorAgreement = true
+
      [submit]
-             mergeContent = true
+     mergeContent = true
 
 #. Add a project entry for the project in
    ``modules/openstack_project/files/review.projects.yaml``.::

doc/source/stackforge.rst

@@ -74,16 +74,19 @@ The next step is to add a Gerrit ACL config file. Edit
 and make it look like::
 
   [access "refs/heads/*"]
-          label-Code-Review = -2..+2 group project-name-core
+  abandon = group project-name-core
-          label-Workflow = -1..+1 group project-name-core
+  label-Code-Review = -2..+2 group project-name-core
-          abandon = group project-name-core
+  label-Workflow = -1..+1 group project-name-core
+
   [access "refs/tags/*"]
-          pushSignedTag = group project-name-ptl
+  pushSignedTag = group project-name-ptl
+
   [receive]
-          requireChangeId = true
+  requireChangeId = true
-          requireContributorAgreement = true
+  requireContributorAgreement = true
+
   [submit]
-          mergeContent = true
+  mergeContent = true
 
 The access sections in the example ACL grant the project's core group
 approval privileges and the ability so set/un-set Workflow status on