From c494817c6856fdd07932cc38bbd5a549fb674a03 Mon Sep 17 00:00:00 2001
From: Clark Boylan <clark.boylan@gmail.com>
Date: Wed, 14 Nov 2012 10:56:56 -0800
Subject: [PATCH] Cleanup manage_project.py documentation.

Move line that was breaking ordered list ordering and add sections about
setting the upstream for a project in the projects.yaml file. Also
replace tabs in ACL config with 8 spaces. Remove refs/* Administrator
ownership. Put ACL sections in alphabetical order.

Change-Id: Ib843379f80822ec0f03730e315e747978a7c1ee6
Reviewed-on: https://review.openstack.org/16115
Reviewed-by: Jeremy Stanley <fungi@yuggoth.org>
Reviewed-by: Paul Belanger <paul.belanger@polybeacon.com>
Approved: Clark Boylan <clark.boylan@gmail.com>
Reviewed-by: Clark Boylan <clark.boylan@gmail.com>
Tested-by: Jenkins
---
 doc/source/gerrit.rst | 42 +++++++++++++++++++++++++-----------------
 1 file changed, 25 insertions(+), 17 deletions(-)

diff --git a/doc/source/gerrit.rst b/doc/source/gerrit.rst
index 341d672fd4..c3104246a3 100644
--- a/doc/source/gerrit.rst
+++ b/doc/source/gerrit.rst
@@ -695,27 +695,26 @@ pupppet repository. To create an actual change that does all of this for
 a single project you will want to do the following:
 
 #. Add a ``modules/openstack_project/files/gerrit/acls/project-name.config``
-   file to the repo. The contents will probably end up looking like::
+   file to the repo. You can refer to the :ref:`project-config` section
+   below if you need more details on writing the project.config file,
+   but contents will probably end up looking like the below block (note
+   that the sections are in alphabetical order and each indentation is
+   8 spaces)::
 
-     [access "refs/*"]
-     	owner = group Administrators
-     [receive]
-     	requireChangeId = true
-     	requireContributorAgreement = true
-     [submit]
-     	mergeContent = true
      [access "refs/heads/*"]
-     	label-Code-Review = -2..+2 group project-name-core
-     	label-Approved = +0..+1 group project-name-core
-     	workInProgress = group project-name-core
+             label-Code-Review = -2..+2 group project-name-core
+             label-Approved = +0..+1 group project-name-core
+             workInProgress = group project-name-core
      [access "refs/heads/milestone-proposed"]
-     	label-Code-Review = -2..+2 group project-name-drivers
-     	label-Approved = +0..+1 group project-name-drivers
+             label-Code-Review = -2..+2 group project-name-drivers
+             label-Approved = +0..+1 group project-name-drivers
      [project]
-     	state = active
-
-You can refer to the :ref:`project-config` section below if you need
-more details on writing the project.config file.
+             state = active
+     [receive]
+             requireChangeId = true
+             requireContributorAgreement = true
+     [submit]
+             mergeContent = true
 
 #. Add a project entry for the project in
    ``openstack-ci-puppet/modules/openstack_project/templates/review.projects.yaml.erb``.::
@@ -723,6 +722,15 @@ more details on writing the project.config file.
      - project: openstack/project-name
        acl_config: /home/gerrit2/acls/project-name.config
 
+#. If there is an existing repo that is being replaced by this new
+   project you can set the upstream value for the project. When an
+   upstream is set, that upstream will be cloned and pushed into Gerrit
+   instead of an empty repository. eg::
+
+     - project: openstack/project-name
+       acl_config: /home/gerrit2/acls/project-name.config
+       upstream: git://github.com/awesumsauce/project-name.git
+
 That is all you need to do. Push the change to gerrit and if necessary
 modify group membership for the groups you configured in the
 ``project.config`` through Launchpad.