Add StackForge Documentation.

Add a page for StackForge that includes a blurb about what StackForge is
and is not, and how to add a StackForge project.

Change-Id: I474b626423952018eb23929d395ac038c082cd25
Reviewed-on: https://review.openstack.org/17411
Reviewed-by: Jeremy Stanley <fungi@yuggoth.org>
Approved: Monty Taylor <mordred@inaugust.com>
Reviewed-by: Monty Taylor <mordred@inaugust.com>
Tested-by: Jenkins

doc/source/index.rst

@@ -36,6 +36,7 @@ Contents:
    puppet_modules
    jenkins_jobs
    meetbot
+   stackforge
 
 Indices and tables
 ==================

doc/source/stackforge.rst

@@ -0,0 +1,229 @@
+:title: StackForge
+
+StackForge
+##########
+
+StackForge is the way that OpenStack related projects can consume and
+make use of the OpenStack project infrastructure. This includes Gerrit
+code review, Jenkins continuous integration, GitHub repository
+mirroring, and various small things like IRC bots, pypi uploads, RTFD
+updates. Projects should make use of StackForge if they want to run
+their project with Gerrit code review and have a trunk gated by Jenkins.
+
+StackForge projects are expected to be self sufficient when it comes to
+configuring Gerrit/Jenkins/Zuul etc. The openstack-infra team can
+provide assistance as resources allow, but should not be relied on.
+
+What StackForge is not:
+
+* Official endorsement of a project by OpenStack.
+* Access to a GitHub organization (StackForge projects are mirrored to
+  GitHub, this is all the GitHub org is used for).
+* A guarantee of eventual OpenStack incubation (Though it is a good
+  first step in that process as it exposes the project to the OpenStack
+  way of doing things).
+
+Add a Project to StackForge
+***************************
+
+Create Core Group in Launchpad
+==============================
+
+StackForge uses Launchpad for group management. The first step in
+creating a StackForge project is to create a team on Launchpad called
+``your-project-name-core``. Members of this team will have permissions
+to approve code changes to your project.
+
+You can create launchpad teams at https://launchpad.net/people/+newteam.
+
+Create a new StackForge Project with Puppet
+===========================================
+
+OpenStack uses Puppet and a management script to create Gerrit projects
+with simple changes to the openstack-ci-puppet repository. To start make
+sure you have cloned the openstack-ci-puppet repository
+``git clone https://github.com/openstack/openstack-ci-puppet``.
+
+First you need to add your StackForge project to the master project
+list. Edit
+``openstack-ci-puppet/modules/openstack_project/templates/review.projects.yaml.erb``
+and add a new section for your project at the end of the file. It should
+look something like::
+
+  - project: stackforge/project-name
+    description: Latest and greatest cloud stuff.
+    acl_config: /home/gerrit2/acls/stackforge/project-name.config
+    upstream: git://github.com/awesumsauce/project-name.git
+
+The description will set the project description on the GitHub
+StackForge mirror, and the upstream should point at an existing
+repository that should be used to preseed Gerrit. Both of these options
+are optional, but you must have an acl_config. Note that the current
+tools assume that the upstream repo will have a master branch.
+
+The next step is to add a Gerrit ACL config file. Edit
+``openstack-ci-puppet/modules/openstack_project/files/gerrit/acls/stackforge/project-name.config``
+and make it look like::
+
+  [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
+  [project]
+          state = active
+  [receive]
+          requireChangeId = true
+          requireContributorAgreement = true
+  [submit]
+          mergeContent = true
+
+That is all that is necessary to add a StackForge project to Gerrit;
+however, this project isn't very useful until we setup Jenkins jobs for
+it and configure Zuul to run those jobs. Continue reading to configure
+these additional tools.
+
+Add Jenkins Jobs to StackForge Projects
+=======================================
+
+In the same openstack-ci-puppet repository (and in the same change if
+you like) we need to edit two additional files to setup Jenkins jobs
+and Zuul for the new StackForge project.
+
+Edit
+``openstack-ci-puppet/modules/openstack_project/files/jenkins_job_builder/config/projects.yaml``
+and add a new section for your project at the end of the file. It should
+look something like::
+
+  - project:
+      name: project-name
+      github-org: stackforge
+      node: precise
+
+      jobs:
+        - gate-{name}-merge
+
+This will add a single Jenkins job for your project called
+gate-project-name-merge. This job will return success if the submitted
+change can be merged into the current state of your project's master
+branch and failure otherwise.
+
+The above config is the bare minimum Jenkins job config needed. If you
+are interested in using the standard python Jenkins jobs (docs, pep8,
+python 2.6 and 2.7 unittests, and coverage) your entry in
+``projects.yaml`` should look like this instead::
+
+  - project:
+      name: project-name
+      github-org: stackforge
+      # Requires additional config please discuss docs with infra team.
+      doc-publisher-site: some.ftp.host
+      node: precise
+
+      jobs:
+        - python-jobs
+
+Now that we have a Jenkins job we need to tell Zuul to run that job when
+appropriate. Edit
+``openstack-ci-puppet/modules/openstack_project/files/zuul/layout.yaml``
+and add a new section for your project at the end of the file. It should
+look something like::
+
+  - name: stackforge/project-name
+    check:
+      - gate-project-name-merge
+    gate:
+      - gate-project-name-merge
+
+This configures zuul to check if change patchsets can merge on every
+submission to Gerrit and will check that the change can merge before
+attempting to merge approved changes.
+
+If you configured the ``python-jobs`` your ``zuul/layout.yaml`` should
+look like this instead::
+
+  - name: stackforge/project-name
+    check:
+      - gate-project-name-merge
+        - gate-project-name-docs
+        - gate-project-name-pep8
+        - gate-project-name-python26
+        - gate-project-name-python27
+    gate:
+      - gate-project-name-merge
+        - gate-project-name-docs
+        - gate-project-name-pep8
+        - gate-project-name-python26
+        - gate-project-name-python27
+    post:
+      - project-name-coverage
+      - project-name-docs
+    publish:
+      - project-name-docs
+
+That concludes the bare minimum openstack-ci-puppet changes necessary to
+add a project to StackForge. You can commit these changes and submit
+them to review.openstack.org at this point, or you can wait a little
+longer and add your project to GerritBot first.
+
+Configure StackForge Project to use GerritBot
+=============================================
+
+To have GerritBot send Gerrit events for your project to a Freenode IRC
+channel edit
+``openstack-ci-puppet/modules/gerritbot/files/gerritbot_channel_config.yaml``.
+If you want to configure GerritBot to leave alerts in a channel
+GerritBot has always joined just add your project to the project list
+for that channel::
+
+  stackforge-dev:
+      events:
+        - patchset-created
+        - change-merged
+        - x-vrif-minus-2
+      projects:
+        - stackforge/libra
+        - stackforge/python-reddwarfclient
+        - stackforge/reddwarf
+        - stackforge/project-name
+      branches:
+        - master
+
+If you want to join GerritBot to a new channel add a new section to the
+end of this file that looks like::
+
+  project-name-dev:
+      events:
+        - patchset-created
+        - change-merged
+        - x-vrif-minus-2
+      projects:
+        - stackforge/project-name
+      branches:
+        - master
+
+And thats it. At this point you will want to submit these edits as a
+change to review.openstack.org.
+
+Add .gitreview file to project
+==============================
+
+Once the change created following the above steps is merged and applied
+to Gerrit, Jenkins, et al you will want to add a ``.gitreview`` file to
+your repository in order to use the ``git review`` tool.
+
+The basic process is clone from stackforge, add file, push to Gerrit,
+review and approve.::
+
+  git clone https://github.com/stackforge/project-name
+  cd project-name
+  git checkout -b add-gitreview
+  cat > .gitreview <<EOF
+  [gerrit]
+  host=review.openstack.org
+  port=29418
+  project=stackforge/project-name.git
+  EOF
+  git review -s
+  git add .gitreview
+  git commit -m 'Add .gitreview file.'
+  git review