From 104c4dfaf5ca4490a3a493276bf9733030d741e5 Mon Sep 17 00:00:00 2001
From: Clark Boylan <clark.boylan@gmail.com>
Date: Mon, 3 Dec 2012 11:34:16 -0800
Subject: [PATCH] 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 | 1 +
doc/source/stackforge.rst | 229 ++++++++++++++++++++++++++++++++++++++
2 files changed, 230 insertions(+)
create mode 100644 doc/source/stackforge.rst
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 2680d91e54..0b4f811b67 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -36,6 +36,7 @@ Contents:
puppet_modules
jenkins_jobs
meetbot
+ stackforge
Indices and tables
==================
diff --git a/doc/source/stackforge.rst b/doc/source/stackforge.rst
new file mode 100644
index 0000000000..3341464740
--- /dev/null
+++ b/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