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 <