opendev/infra-manual
Code Issues Proposed changes

Project does not mean repository? Inconceivable!

Browse Source 
You keep using that word. I do not think it means what
you think it means.

Previously "project" meant a variety of different things
depending on the context in which it was used. Now that
the TC has decreed "project" is a grouping of source
code repositories managed by a "project team" we need to
be extra careful not to conflate these meanings in our
documentation, particularly for the sake of minimally
fluent readers and those not yet familiar with our
community's unique terminologies.

Change-Id: I574ab8e2c94eadce76cff9f7ea561dfa5d28b89c
This commit is contained in:
Jeremy Stanley 2015-04-22 20:17:55 +00:00 committed by Andreas Jaeger
parent 69b65073e0
commit a5050b373c
3 changed files with 328 additions and 291 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

355
doc/source/creators.rst
View File

@ -1,8 +1,8 @@
:title: Project Creator's Guide
:title: Repository Creator's Guide
=========================
Project Creator's Guide
=========================
============================
Repository Creator's Guide
============================
Before You Start
================
@ -14,12 +14,12 @@ It is important that you perform all of the steps, in the order they
are given here. Don't skip any steps. Don't try to do things in
parallel. Don't jump around.
Choosing a Good Name for Your Project
=====================================
Choosing a Good Name for Your Repository
========================================
It is important to choose a descriptive name that does not conflict
with other projects. There are several places you'll need to look to
ensure uniqueness and suitability of the name.
with other repositories. There are several places you'll need to
look to ensure uniqueness and suitability of the name.
.. note::
@ -41,7 +41,8 @@ The base name of the repository should be unique across all of the
namespace directories for git repositories under
https://git.openstack.org/cgit. That is, it is not sufficient to have
``openstack/foo`` and ``openstack-dev/foo`` because that prevents us
from moving those two projects into the same namespace at some point.
from moving those two repositories into the same namespace at some
point.
Launchpad
---------
@ -53,14 +54,15 @@ https://launchpad.net to be the same as your git repository name. Try
PyPI
----
Python projects need to have a unique name on the Python Package Index
(https://pypi.python.org) so we can publish source distributions to be
installed via pip.
Python packages need to have a unique name on the Python Package
Index (https://pypi.python.org) so we can publish source
distributions to be installed via pip.
It is best to name the project and the top level Python package the
same when possible so that the name used to install the dist and the
name used to import the package in source files match. Try "python-"
as a prefix if necessary (for example, "python-stevedore").
It is best to name the repository and the top level Python package
the same when possible so that the name used to install the dist and
the name used to import the package in source files match. Try
"python-" as a prefix if necessary (for example,
"python-stevedore").
Project Team Rules
------------------
@ -76,8 +78,8 @@ Set up Launchpad
OpenStack uses https://launchpad.net for project management tasks such
as release planning and bug tracking. The first step to importing your
project is to make sure you have the right project management tools
configured.
repository is to make sure you have the right project management
tools configured.
.. (dhellmann) This section will need to be updated when we move fully
to storyboard.
@ -171,7 +173,7 @@ team.
Give OpenStack Permission to Publish Releases
=============================================
New projects without any releases need to be manually registered on
New packages without any releases need to be manually registered on
PyPI.
If you do not have PyPI credentials, you should create them at
@ -182,11 +184,11 @@ Once you have PyPI credentials visit
https://pypi.python.org/pypi?%3Aaction=submit_form and fill in only
the required fields.
Next your project needs to be updated so the "openstackci" user has
Next your package needs to be updated so the "openstackci" user has
"Owner" permissions.
Visit
``https://pypi.python.org/pypi?:action=role_form&package_name=<projectname>``
``https://pypi.python.org/pypi?:action=role_form&package_name=<packagename>``
and add "openstackci" in the "User Name" field, set the role to "Owner",
and click "Add Role".
@ -205,40 +207,41 @@ All of the changes described in this section should be submitted
together as one patchset to the ``openstack-infra/project-config``
repository.
Add the project to the master project list
------------------------------------------
Add the repository to the master repositories list
--------------------------------------------------
#. Edit ``gerrit/projects.yaml`` to add a new section like::
- project: openstack/<projectname>
- project: openstack/<repositoryname>
description: Latest and greatest cloud stuff.
#. Provide a very brief description of the library.
#. If you have an existing repository that you want to import (for
example, when graduating an Oslo library or bringing a project into
gerrit from github), set the "upstream" field to the URL of the
publicly reachable repository and also read the information in
:ref:`setup_review`::
example, when graduating an Oslo library or bringing a repository
into gerrit from github), set the "upstream" field to the URL of
the publicly reachable repository and also read the information
in :ref:`setup_review`::
- project: openstack/<projectname>
- project: openstack/<repositoryname>
description: Latest and greatest cloud stuff.
upstream: git://github.com/awesumsauce/<projectname>.git
upstream: git://github.com/awesumsauce/<repositoryname>.git
.. note::
If the git repository short name does not match the Launchpad project
name, you need to add a "groups" list to provide the mapping. The
groups list is also used by Storyboard to be able to present grouped
views of stories and tasks across multiple related projects.
views of stories and tasks across multiple related
repositories.
For example, Oslo projects should use "oslo" to ensure that they
are associated with the https://launchpad.net/oslo project group
for tracking bugs and milestones::
For example, Oslo repositories should use "oslo" to ensure
that they are associated with the https://launchpad.net/oslo
project group for tracking bugs and milestones::
- project: openstack/<projectname>
- project: openstack/<repositoryname>
description: Latest and greatest cloud stuff.
upstream: git://github.com/awesumsauce/<projectname>.git
upstream: git://github.com/awesumsauce/<repositoryname>.git
groups:
- oslo
@ -247,12 +250,13 @@ Add the project to the master project list
Add Gerrit permissions
----------------------
Each project should have two gerrit groups. The first, "<projectname>-core", is
the normal core group, with permission to +2 changes. The second,
"<projectname>-release" is a small group of the primary maintainers
with permission to push tags to trigger releases.
Each repository should have two gerrit groups. The first,
"<projectname>-core", is the normal core group, with permission to
+2 changes. The second, "<projectname>-release" is a small group of
the primary maintainers with permission to push tags to trigger
releases.
Create ``gerrit/acls/openstack/<projectname>.config``::
Create ``gerrit/acls/openstack/<repositoryname>.config``::
[access "refs/heads/*"]
abandon = group <projectname>-core
@ -279,21 +283,21 @@ jenkins-job-builder configuration files.
.. note::
Different projects will need different jobs, depending on their
nature, implementation language, etc. This example shows how to set
up a new Python code project because that is our most common
case. If you are working on another type of project, you will want
to choose different jobs or job templates to include in the "jobs"
list.
Different repositories will need different jobs, depending on
their nature, implementation language, etc. This example shows
how to set up a new Python code repository because that is our
most common case. If you are working on another type of
repository, you will want to choose different jobs or job
templates to include in the "jobs" list.
Edit ``jenkins/jobs/projects.yaml`` to add your project. There are
several sections, designated in comments, for different types of
projects. Find the right section and then add a new stanza like:
Edit ``jenkins/jobs/projects.yaml`` to add your repository. There
are several sections, designated in comments, for different types of
repositories. Find the right section and then add a new stanza like:
::
- project:
name: <projectname>
name: <repositoryname>
node: 'bare-precise || bare-trusty'
tarball-site: tarballs.openstack.org
doc-publisher-site: docs.openstack.org
@ -311,20 +315,20 @@ need.
.. note::
Different projects will need different jobs, depending on their
nature, implementation language, etc. This example shows how to set
up the full set of gate jobs for a new Python code project because
that is our most common case. If you are working on another type of
project, you will want to choose different jobs or job templates to
include here.
Different repositories will need different jobs, depending on
their nature, implementation language, etc. This example shows
how to set up the full set of gate jobs for a new Python code
repository because that is our most common case. If you are
working on another type of repository, you will want to choose
different jobs or job templates to include here.
Edit ``zuul/layout.yaml`` to add your project. There are several
Edit ``zuul/layout.yaml`` to add your repository. There are several
sections, designated in comments, for different types of
projects. Find the right section and then add a new stanza like:
repositories. Find the right section and then add a new stanza like:
::
- name: openstack/<projectname>
- name: openstack/<repositoryname>
template:
- name: merge-check
- name: python-jobs
@ -342,15 +346,15 @@ You can find more info about job templates in the beginning of
.. note::
If you use ``pypi-jobs`` and ``publish-to-pypi``, please ensure
your project's namespace is registered on https://pypi.python.org
as described in :ref:`register-pypi`. This will be required before
your change is merged.
your repository's namespace is registered on
https://pypi.python.org as described in :ref:`register-pypi`.
This will be required before your change is merged.
If you are not ready to run any tests yet and did not configure
``python-jobs`` in ``jenkins/jobs/projects.yaml``, the entry for
``zuul/layout.yaml`` should look like this instead::
- name: openstack/<projectname>
- name: openstack/<repositoryname>
template:
- name: merge-check
- name: noop-jobs
@ -359,11 +363,11 @@ If you are not ready to run any tests yet and did not configure
Configure GerritBot to Announce Changes
---------------------------------------
If you want changes proposed and merged to your project to be
If you want changes proposed and merged to your repository to be
announced on IRC, edit ``gerritbot/channels.yaml`` to add your new
repository to the list of projects. For example, to announce changes
related to an Oslo library in the ``#openstack-oslo`` channel, add it
to the ``openstack-oslo`` section::
repository to the list of repositories. For example, to announce
changes related to an Oslo library in the ``#openstack-oslo``
channel, add it to the ``openstack-oslo`` section::
openstack-oslo:
events:
@ -408,20 +412,20 @@ attention::
Note the Change-Id in your commit message for the next step.
Add Project to the Governance Repository
----------------------------------------
Add New Repository to the Governance Repository
-----------------------------------------------
Each project managed by an official OpenStack project team needs to be
listed in ``reference/projects.yaml`` in the ``openstack/governance``
repository to indicate who owns the project so we know where ATCs
voting rights extend.
Each repository managed by an official OpenStack project team needs
to be listed in ``reference/projects.yaml`` in the
``openstack/governance`` repository to indicate who owns the
repository so we know where ATCs voting rights extend.
If your project is under the ``stackforge`` section of the git
If your repository is under the ``stackforge`` section of the git
repository structure, you can skip this step.
Find the appropriate section in ``reference/projects.yaml`` and add
the new project to the list. For example, to add a new Oslo library
edit the "Oslo" section::
the new repository to the list. For example, to add a new Oslo
library edit the "Oslo" section::
Oslo:
ptl: Doug Hellmann (dhellmann)
@ -431,28 +435,45 @@ edit the "Oslo" section::
projects. The APIs provided by these libraries should be high quality,
stable, consistent, documented and generally applicable.
url: https://wiki.openstack.org/wiki/Oslo
tags:
- name: team:diverse-affiliation
projects:
- openstack/oslo-incubator
- openstack/oslo.config
- openstack/oslo.messaging
- openstack/oslo.rootwrap
- openstack/oslo.sphinx
- openstack/oslo.version
- openstack-dev/cookiecutter
- openstack-dev/hacking
- openstack-dev/pbr
- repo: openstack/oslo-incubator
tags:
- name: release:has-stable-branches
- repo: openstack/oslo.config
tags:
- name: release:independent
- name: release:has-stable-branches
- repo: openstack/oslo.messaging
tags:
- name: release:independent
- name: release:has-stable-branches
- repo: openstack/oslo.rootwrap
tags:
- name: release:independent
- name: release:has-stable-branches
- repo: openstack/oslosphinx
tags:
- name: release:independent
- name: release:has-stable-branches
- repo: openstack-dev/cookiecutter
- repo: openstack-dev/pbr
tags:
- name: release:independent
When writing the commit message for this change, make this change
depend on the project creation change by including a link to its
depend on the repository creation change by including a link to its
Change-ID (from the previous step)::
Depends-On: <Gerrit Change-Id>
However, if you are creating an entirely new OpenStack project (i.e.,
adding a new top-level entry into projects.yaml), you should reverse
the dependency direction (the project creation change should depend on
the governance change because the TC needs to approve the project
first).
However, if you are creating an entirely new OpenStack project team
(i.e., adding a new top-level entry into
``reference/projects.yaml``), you should reverse the dependency
direction (the repository creation change should depend on the
governance change because the TC needs to approve the new project
team application first).
Wait Here
---------
@ -474,54 +495,55 @@ After the review is approved and groups are created, ask the Infra
team to add you to both groups in gerrit, and then you can add other
members.
The project PTL, at least, should be added to "<projectname>-release",
and other developers who understand the release process can volunteer
to be added as well.
The project team lead (PTL), at least, should be added to
"<projectname>-release", and other developers who understand the
release process can volunteer to be added as well.
Updating devstack-vm-gate-wrap.sh
---------------------------------
The ``devstack-gate`` tools let us install OpenStack projects in a
consistent way so they can all be tested with a common
configuration. If your project will not need to be installed for
The ``devstack-gate`` tools let us install OpenStack repositories in
a consistent way so they can all be tested with a common
configuration. If your repository will not need to be installed for
devstack gate jobs, you can skip this step.
Check out ``openstack-infra/devstack-gate`` and edit
``devstack-vm-gate-wrap.sh`` to add the new project::
``devstack-vm-gate-wrap.sh`` to add the new repository::
PROJECTS="openstack/<projectname> $PROJECTS"
PROJECTS="openstack/<repositoryname> $PROJECTS"
Keep the list in alphabetical order.
Add Project to the Requirements List
------------------------------------
Add Repository to the Requirements List
---------------------------------------
The global requirements repository (openstack/requirements) controls
which dependencies can be added to a project to ensure that all of
OpenStack can be installed together on a single system without
which dependencies can be added to a repository to ensure that all
of OpenStack can be installed together on a single system without
conflicts. It also automatically contributes updates to the
requirements lists for OpenStack projects when the global requirements
change.
requirements lists for OpenStack repositories when the global
requirements change.
If your project is not going to participate in this requirements
If your repository is not going to participate in this requirements
management, you can skip this step.
Edit the ``projects.txt`` file to add the new library, adding
"openstack/<projectname>" in the appropriate place in alphabetical
order.
"openstack/<repositoryname>" in the appropriate place in
alphabetical order.
Preparing a New Git Repository using cookiecutter
=================================================
All OpenStack projects should use one of our cookiecutter_ templates
for creating an initial repository to hold the source for the project.
All OpenStack repositories should use one of our cookiecutter_
templates for creating an initial repository to hold the source
code.
If you had an existing repository ready for import when you submitted
the change to project-config, you can skip this section.
Start by checking out a copy of the new repository for your project::
Start by checking out a copy of your new repository::
$ git clone git://git.openstack.org/openstack/<projectname>
$ git clone git://git.openstack.org/openstack/<repositoryname>
.. _cookiecutter: https://pypi.python.org/pypi/cookiecutter
@ -533,7 +555,7 @@ Choosing the Right cookiecutter Template
----------------------------------------
The template in ``openstack-dev/cookiecutter`` is suitable for
most projects.
most repositories.
::
@ -550,18 +572,19 @@ Applying the Template
---------------------
Running cookiecutter will prompt you for several settings, based on
the template's configuration. It will then update your project with a
project skeleton, ready to have your other project files added.
the template's configuration. It will then update your repository
with a skeleton, ready to have your other files added.
::
$ cd <projectname>
$ cd <repositoryname>
$ git review
If you configured all of the tests for the project when it was created
in the previous section, you will have to ensure that all of the tests
pass before the cookiecutter change will merge. You can run most of the
tests locally using ``tox`` to verify that they pass.
If you configured all of the tests for the repository when it was
created in the previous section, you will have to ensure that all of
the tests pass before the cookiecutter change will merge. You can
run most of the tests locally using ``tox`` to verify that they
pass.
Verify That Gerrit and the Test Jobs are Working
================================================
@ -575,21 +598,21 @@ it merge.
Configure ``git review``
------------------------
If the new project you have added has a specified upstream you will need
to add a ``.gitreview`` file to the project once it has been created. This
new file will allow you to use ``git review``.
If the new repository you have added has a specified upstream you
will need to add a ``.gitreview`` file to the repository once it has
been created. This new file will allow you to use ``git review``.
The basic process is clone your new repository, add file, push to Gerrit,
review and approve::
$ git clone https://git.openstack.org/openstack/<projectname>
$ cd <projectname>
$ git clone https://git.openstack.org/openstack/<repositoryname>
$ cd <repositoryname>
$ git checkout -b add-gitreview
$ cat > .gitreview <<EOF
[gerrit]
host=review.openstack.org
port=29418
project=openstack/<projectname>.git
project=openstack/<repositoryname>.git
EOF
$ git review -s
$ git add .gitreview
@ -599,22 +622,22 @@ review and approve::
Verify that the Tests Pass
--------------------------
If you configure tests for an imported project, ensure that all of the
tests pass successfully before importing. Otherwise your first change
needs to fix all test failures. You can run most of the tests locally
using ``tox`` to verify that they pass.
If you configure tests for an imported repository, ensure that all
of the tests pass successfully before importing. Otherwise your
first change needs to fix all test failures. You can run most of the
tests locally using ``tox`` to verify that they pass.
Verify the Gerrit Review Permissions
------------------------------------
When your project is added to gerrit, the groups defined in the ACLs
file (see :ref:`add-gerrit-permissions`) are created, but they are
empty by default. Someone on the infrastructure team with gerrit
When your repository is added to gerrit, the groups defined in the
ACLs file (see :ref:`add-gerrit-permissions`) are created, but they
are empty by default. Someone on the infrastructure team with gerrit
administrator privileges will need to add you to each group. After
that point, you can add other members.
To check the membership of the groups, visit
``https://review.openstack.org/#/admin/projects/openstack/<projectname>,access``
``https://review.openstack.org/#/admin/projects/openstack/<repositoryname>,access``
-- for example,
https://review.openstack.org/#/admin/projects/openstack-infra/infra-manual,access
-- and then click on the group names displayed on that page to review
@ -623,22 +646,22 @@ their membership.
Prepare an Initial Release
==========================
Make Your Project Useful
------------------------
Make Your Repository Useful
---------------------------
Before going any farther, make the project do something useful.
Before going any farther, make the repository do something useful.
If you are importing an existing project with features, you can go
ahead.
If you are importing an existing repository with features, you can
go ahead.
If you are creating a brand new project, add some code and tests to
provide some minimal functionality.
If you are creating a brand new repository, add some code and tests
to provide some minimal functionality.
Provide Basic Developer Documentation
-------------------------------------
Update the ``README.rst`` file to include a paragraph describing the
new project.
new repository.
Update the rest of the documentation under ``doc/source`` with
information about the public API, tips on adopting the tool,
@ -649,7 +672,7 @@ Tagging a Release
To verify that the release machinery works, push a signed tag to the
"gerrit" remote. Use the smallest version number possible. If this is
the first release, use "0.1.0". If other releases of the project
the first release, use "0.1.0". If other releases of the repository
exist, choose an appropriate next version number.
.. note::
@ -670,13 +693,13 @@ If you need to check the logs, you can use the `git-os-job`_ command::
.. _git-os-job: https://pypi.python.org/pypi/git-os-job
Allowing Other OpenStack Projects to Use Your Library
=====================================================
Allowing Other OpenStack Repositories to Use Your Library
=========================================================
OpenStack projects share a common global requirements list so that all
components can be installed together on the same system. If you are
importing a new library project, you need to update that list to allow
other projects to use your library.
OpenStack repositories share a common global requirements list so
that all components can be installed together on the same system. If
you are importing a new library repository, you need to update that
list to allow other repositories to use your library.
Update the Global Requirements List
-----------------------------------
@ -690,24 +713,24 @@ Check out the ``openstack/requirements`` git repository and modify
Setting up Gate Testing
=======================
The devstack gate jobs install all OpenStack projects from source so
that the appropriate git revisions (head, or revisions in the merge
queue) are tested together. To include the new library in these tests,
it needs to be included in the list of projects in the devstack gate
wrapper script. For the same feature to work for developers outside of
the gate, the project needs to be added to the appropriate library
file of devstack.
The devstack gate jobs install all OpenStack repositories from
source so that the appropriate git revisions (head, or revisions in
the merge queue) are tested together. To include the new library in
these tests, it needs to be included in the list of repositories in
the devstack gate wrapper script. For the same feature to work for
developers outside of the gate, the repository needs to be added to
the appropriate library file of devstack.
Updating devstack
-----------------
#. Check out ``openstack-dev/devstack``.
#. Edit the appropriate project file under ``lib`` to add a variable
defining where the source should go. For example, when adding a new
Oslo library add it to ``lib/oslo``::
#. Edit the appropriate repository file under ``lib`` to add a
variable defining where the source should go. For example, when
adding a new Oslo library add it to ``lib/oslo``::
<PROJECTNAME>_DIR=$DEST/<projectname>
<REPOSITORYNAME>_DIR=$DEST/<repositoryname>
#. Edit the installation function in the same file to add commands to
check out the repository. For example, when adding an Oslo library,
@ -721,16 +744,16 @@ Updating devstack
function install_oslo() {
...
_do_install_oslo_lib "<projectname>"
_do_install_oslo_lib "<repositoryname>"
...
}
#. Edit ``stackrc`` to add the other variables needed for configuring the
new library::
# new-project
<PROJECTNAME>_REPO=${<PROJECTNAME>_REPO:-${GIT_BASE}/openstack/<projectname>.git}
<PROJECTNAME>_BRANCH=${<PROJECTNAME>_BRANCH:-master}
# new-repository
<REPOSITORYNAME>_REPO=${<REPOSITORYNAME>_REPO:-${GIT_BASE}/openstack/<repositoryname>.git}
<REPOSITORYNAME>_BRANCH=${<REPOSITORYNAME>_BRANCH:-master}
Add Link to Your Developer Documentation
========================================
@ -740,4 +763,4 @@ page with a link to your documentation by checking out the
``openstack/openstack-manuals`` repository and editing
``www/developer/openstack-projects.html``.
Skip this step if your project is under ``stackforge``.
Skip this step if your repository is under ``stackforge``.

162
doc/source/developers.rst
View File

@ -16,10 +16,11 @@ Getting Started
The goal of this document is to walk you through the concepts and
specifics that should be understood while contributing to OpenStack.
Prior to contributing to an OpenStack project a few steps need to be
completed. This document covers the steps that get you started, such as
creating a few accounts on required websites, signing a contributor
license agreement, uploading an ssh key, and installing git-review.
Prior to contributing to an OpenStack source code repository a few
steps need to be completed. This document covers the steps that get
you started, such as creating a few accounts on required websites,
signing a contributor license agreement, uploading an ssh key, and
installing git-review.
Account Setup
-------------
@ -62,17 +63,18 @@ provide contact information. The full text of the agreement will be
displayed before you can enter "I AGREE" below it, but it's also
anonymously available if you want to `preview the OpenStack
ICLA <https://review.openstack.org/static/cla.html>`_ now. Your full name
and email address will be public (since they also appear in project commit
logs) and the latter needs to match the user.email in your Git
configuration. The other contact information (postal address, phone
numbers) will be kept confidential and is only used as a fallback record in
the unlikely event The OpenStack Foundation needs to reach you directly
over code contribution related matters. This contact information can also
be easily `updated <https://review.openstack.org/#/settings/contact>`_
later if desired, but make sure the primary email address always matches
the one you set for your OpenStack Foundation Membership -- otherwise
Gerrit will give you an error message and refuse to accept your contact
information.
and email address will be public (since they also appear in
repository commit logs) and the latter needs to match the user.email
in your Git configuration. The other contact information (postal
address, phone numbers) will be kept confidential and is only used
as a fallback record in the unlikely event The OpenStack Foundation
needs to reach you directly over code contribution related matters.
This contact information can also be easily `updated
<https://review.openstack.org/#/settings/contact>`_ later if
desired, but make sure the primary email address always matches the
one you set for your OpenStack Foundation Membership -- otherwise
Gerrit will give you an error message and refuse to accept your
contact information.
Employees of the U.S. Government do not sign the Individual
CLA. Instead, someone with authority to sign on behalf of your agency
@ -178,19 +180,20 @@ You should then be prompted for your username and password (where
this is the `HTTP password generated in Gerrit
<https://review.openstack.org/#/settings/http-password>`_).
Starting Work on a New Project
------------------------------
Starting Work on a New Repository
---------------------------------
Clone a project in the usual way, for example::
Clone a repository in the usual way, for example::
git clone https://git.openstack.org/openstack/<projectname>.git
git clone https://git.openstack.org/openstack/<repositoryname>.git
You may want to ask git-review to configure your project to know about
Gerrit at this point. If you don't, it will do so the first time you
submit a change for review, but you probably want to do this ahead of
time so the Gerrit Change-Id commit hook gets installed. To do so::
You may want to ask git-review to configure your repository to know
about Gerrit at this point. If you don't, it will do so the first
time you submit a change for review, but you probably want to do
this ahead of time so the Gerrit Change-Id commit hook gets
installed. To do so::
cd <projectname>
cd <repositoryname>
git review -s
Git-review checks that you can log in to Gerrit with your ssh key. It
@ -259,7 +262,7 @@ section of the OpenStack Git Commit Good Practices wiki page.
Working on Specifications and Blueprints
----------------------------------------
Many OpenStack projects teams have a <projectteam>-specs respository which
Many OpenStack project teams have a <projectteam>-specs repository which
is used to hold approved design specifications for additions and changes to
the project team's code repositories.
@ -385,7 +388,7 @@ Understanding Changes and Patch Sets
It's important to understand how Gerrit handles changes and patch
sets. Gerrit combines the Change-Id in the commit message, the
project, and the target branch to uniquely identify a change.
repository, and the target branch to uniquely identify a change.
A new patch set is determined by any modification in the commit
hash. When a change is initially pushed up it only has one patch
@ -414,8 +417,9 @@ Squashing Changes
If you have made many small commits, you should squash them so that
they do not show up in the public repository. Remember: each commit
becomes a change in Gerrit, and must be approved separately. If you
are making one "change" to the project, squash your many "checkpoint"
commits into one commit for public consumption. Here's how::
are making one "change" to the repository, squash your many
"checkpoint" commits into one commit for public consumption. Here's
how::
git checkout master
git pull origin master
@ -477,20 +481,20 @@ resolving merge conflicts you can use git review ``-R`` as the last step
above.
Cross-Project Dependencies
--------------------------
Cross-Repository Dependencies
-----------------------------
If your change has a dependency on a change outside of a project, like
a change for another project or some manual setup, you have to ensure
that the change merge at the right time.
If your change has a dependency on a change outside of that
repository, like a change for another repository or some manual
setup, you have to ensure that the change merge at the right time.
For a change depending on a manual setup, mark your change with the
"Work in Progress" label until the manual setup is done. A core
reviewer might also block an important change with a -2 so that it
does not get merged accidentally before the manual setup is done.
If your change has a dependency on a change in another project, you
can use cross-repo dependencies (CRD) in Zuul:
If your change has a dependency on a change in another repository,
you can use cross-repo dependencies (CRD) in Zuul:
* To use them, include "Depends-On: <gerrit-change-id>" in the footer
of your commit message. Use the full Change-ID ('I' + 40
@ -543,12 +547,13 @@ Multiple Changes
^^^^^^^^^^^^^^^^
A Gerrit change ID may refer to multiple changes (on multiple branches
of the same project, or even multiple projects). In these cases, Zuul
will treat all of the changes with that change ID as dependencies. So
if you say that a tempest change Depends-On a change ID that has changes
in nova master and nova stable/juno, then when testing the tempest
change, both nova changes will be applied, and when deciding whether the
tempest change can merge, both changes must merge ahead of it.
of the same repository, or even multiple repositories). In these
cases, Zuul will treat all of the changes with that change ID as
dependencies. So if you say that a tempest change Depends-On a
change ID that has changes in nova master and nova stable/juno, then
when testing the tempest change, both nova changes will be applied,
and when deciding whether the tempest change can merge, both changes
must merge ahead of it.
A change may depend on more than one Gerrit change ID as well. So it is
possible for a change in tempest to depend on a change in devstack and a
@ -587,10 +592,11 @@ in your browser. Other reviewers can only see them after you have
submitted them as a comment on the patchset.
Any OpenStack developer may propose or comment on a change (including
voting +1/0/-1 on it). OpenStack projects have a policy requiring two
positive reviews from core reviewers. A vote of +2 is allowed from
core reviewers, and should be used to indicate that they are a core
reviewer and are leaving a vote that should be counted as such.
voting +1/0/-1 on it). OpenStack project teams have a policy
requiring two positive reviews from core reviewers. A vote of +2 is
allowed from core reviewers, and should be used to indicate that
they are a core reviewer and are leaving a vote that should be
counted as such.
When a review has two +2 reviews and one of the core team believes it
is ready to be merged, he or she should leave a +1 vote in the
@ -612,16 +618,17 @@ For more details on reviews in Gerrit, check the
Automated Testing
-----------------
When a new patchset is uploaded to Gerrit, that project's "check"
When a new patchset is uploaded to Gerrit, that repository's "check"
tests are run on the patchset by Jenkins. Once completed the test
results are reported to Gerrit by Jenkins in the form of a Verified:
+/-1 vote. After code reviews have been completed and a change
receives an Approved: +1 vote that project's "gate" tests are run on
the change by Jenkins. Jenkins reports the results of these tests back
to Gerrit in the form of a Verified: +/-2 vote. Code merging will only
occur after the gate tests have passed successfully and received a
Verified: +2. You can view the state of tests currently being run on
the `Zuul Status page <http://status.openstack.org/zuul>`_.
receives an Approved: +1 vote that repository's "gate" tests are run
on the change by Jenkins. Jenkins reports the results of these tests
back to Gerrit in the form of a Verified: +/-2 vote. Code merging
will only occur after the gate tests have passed successfully and
received a Verified: +2. You can view the state of tests currently
being run on the `Zuul Status page
<http://status.openstack.org/zuul>`_.
If a change fails tests in Jenkins, please follow the steps below:
@ -643,14 +650,15 @@ If a change fails tests in Jenkins, please follow the steps below:
1. Visit http://status.openstack.org/elastic-recheck/ to see if one
of the bugs listed there matches the error you've seen. If your
error isn't there, then:
2. Identify which project(s) are affected, and search for a related
bug on Launchpad. You can search for bugs affecting all OpenStack
Projects here: https://bugs.launchpad.net/openstack/ If you do
not find an existing bug, file a new one (be sure to include
the error message and a link to the logs for the failure). If the
problem is due to an infrastructure problem (such as Jenkins or
Gerrit), file (or search for) the bug against the openstack-gate
project.
2. Identify which repository or repositories are affected, and
search for a related bug on Launchpad. You can search for bugs
affecting all OpenStack Projects here:
https://bugs.launchpad.net/openstack/ If you do not find an
existing bug, file a new one (be sure to include the error
message and a link to the logs for the failure). If the problem
is due to an infrastructure problem (such as Jenkins or
Gerrit), file (or search for) the bug against the
openstack-gate project.
4. To re-run check or gate jobs, leave a comment on the review
with the form "recheck".
@ -674,10 +682,10 @@ great way to learn about OpenStack social norms and the development
processes. Some things are necessary to keep in mind when doing code
reviews:
1. The code should comply with everything in that project's
`HACKING.rst` file, if it has one. If the project reuses nova's
hacking guidelines, then it may have a "hacking" section in its
`tox.ini` file in which case much of this is already checked
1. The code should comply with everything in that repository's
`HACKING.rst` file, if it has one. If the repository reuses
nova's hacking guidelines, then it may have a "hacking" section in
its `tox.ini` file in which case much of this is already checked
automatically for you by the continuous integration system.
2. The code should be 'pythonic' and look like the code around it,
to make the code more uniform and easier to read.
@ -719,8 +727,8 @@ reviews:
6. The code should comply with the community `logging standards <https://wiki.openstack.org/wiki/LoggingStandards>`_.
There may be more specific items to be aware of inside the projects'
documentation for contributors.
There may be more specific items to be aware of inside the
repositories' documentation for contributors.
Contributors may notice a review that has several +1's from other
reviewers, passes the functional tests, etc. but the code still has
@ -762,18 +770,18 @@ Gerrit cannot merge a patchset, it will give a -1 review and add a
comment notifying of merge failure.
Each time a change merges, the "merge-check" pipeline verifies that
all open changes on the same project are still mergeable. If any job
is not mergeable, Jenkins will give a -1 review and add a comment
notifying of merge failure.
all open changes on the same repository are still mergeable. If any
job is not mergeable, Jenkins will give a -1 review and add a
comment notifying of merge failure.
After a change is merged, project specific post jobs are run. Most
often the post jobs publish documentation, run coverage, or send
strings to the translation server.
After a change is merged, repository-specific post jobs are run.
Most often the post jobs publish documentation, run coverage, or
send strings to the translation server.
Project Gating
--------------
Repository Gating
-----------------
Project gating refers to the process of running regression tests
Repository gating refers to the process of running regression tests
before a developer's patchset is merged. The intent of running
regression tests is to validate that new changes submitted
against the source code repository will not introduce new
@ -795,10 +803,10 @@ Once all of the jobs report success on an approved patchset in the
configured gate pipeline, then Gerrit will merge the code into trunk.
Besides running the gate tests, the gate pipeline determines the order
of changes to merge accross multiple projects. The changes are tested
of changes to merge accross multiple repositories. The changes are tested
and merged in this order, so that for each change the state of all
other repositories can be identified.
Additional information about project gating And Zuul can
Additional information about repository gating and Zuul can
be found in the Zuul documentation, located at:
http://ci.openstack.org/zuul/gating.html

102
doc/source/drivers.rst
View File

@ -17,20 +17,21 @@ proposed change.
To get started with a feature branch you will need to create the new
branch in Gerrit with the 'feature/' prefix. Note that Gerrit ACLs do
not allow for pushing of new branches via git, but specific groups of
Gerrit users can create new branches. For OpenStack projects the
Release Manager creates feature branches. Stackforge projects may
update their Gerrit ACLs to allow their release teams to create these
branches. For similar Gerrit ACL reasons branch deletion is typically
limited to the Infra team. Keep this in mind before creating many
branches that will need cleanup.
Gerrit users can create new branches. For OpenStack repositories the
Release Manager creates feature branches. Stackforge repositories
may update their Gerrit ACLs to allow their release teams to create
these branches. For similar Gerrit ACL reasons branch deletion is
typically limited to the Infra team. Keep this in mind before
creating many branches that will need cleanup.
If more than one project is involved in a feature development effort,
the same feature branch name should be used across all such projects.
This will cause integration testing with Zuul to use the respective
feature branch from any project that carries it. Projects without an
equivalently named feature branch will use master instead. Use care
not to create a feature branch with the same name as a feature branch
for an unrelated effort in another project.
If more than one repository is involved in a feature development
effort, the same feature branch name should be used across all such
repositories. This will cause integration testing with Zuul to use
the respective feature branch from any repository that carries it.
Repositories without an equivalently named feature branch will use
master instead. Use care not to create a feature branch with the
same name as a feature branch for an unrelated effort in another
repository.
One additional thing to keep in mind is that feature branches should be
treated like master in most cases. They are specifically not for sustained
@ -40,18 +41,20 @@ Merge Commits
-------------
An important activity when using feature branches is syncing to and from
the project's master branch. During development on a feature branch a
project will want to merge master into the feature branch periodically
to keep up to date with changes over time. Then when development on the
feature branch is complete, it will need to be merged into master.
the repository's master branch. During development on a feature
branch a repository will want to merge master into the feature branch
periodically to keep up to date with changes over time. Then when
development on the feature branch is complete, it will need to be
merged into master.
Before this can happen the project's release group will need to have
access to push merge commits in Gerrit::
Before this can happen the project team's release group will need to
have access to push merge commits in Gerrit::
[access "refs/for/refs/*"]
pushMerge = group <project>-release
pushMerge = group <projectname>-release
Should be added to the project's ACL file in the project-config repo.
Should be added to the repository's ACL file in the project-config
repo.
Merge Master into Feature Branch
--------------------------------
@ -126,12 +129,13 @@ commit to record the state of the branch at the time.
Create proposed/* Branch
~~~~~~~~~~~~~~~~~~~~~~~~
For OpenStack projects this should be performed by the OpenStack
Release Manager at the Release Branch Point. If you are managing
branches for your project you may have permission to do this yourself.
For OpenStack repositories this should be performed by the OpenStack
Release Manager at the Release Branch Point. If you are managing
branches for your repository you may have permission to do this
yourself.
* Go to https://review.openstack.org/ and sign in
* Select 'Admin', 'Projects', then the project
* Select 'Admin', 'Projects', then the repository
* Select 'Branches'
* Enter ``proposed/<series>`` in the 'Branch Name' field, and ``HEAD``
as the 'Initial Revision', then press 'Create Branch'.
@ -195,8 +199,8 @@ the release is made. If you are managing your own releases, you may
have permission to do this yourself.
Tag the tip of the appropriate branch (proposed/<series> for server
projects, master for clients/libraries) with a release tag and push
that tag to Gerrit by running the following commands::
repositories, master for clients/libraries) with a release tag and
push that tag to Gerrit by running the following commands::
git checkout <branch name>
git pull --ff-only
@ -229,7 +233,7 @@ even after the branch is deleted, making it possible to restore the
state of the tree.
* Go to https://review.openstack.org/ and sign in
* Select 'Admin', 'Projects', then the project
* Select 'Admin', 'Projects', then the repository
* Select 'Branches'
* Select the checkbox next to 'proposed/<series>' and hit 'Delete'
@ -257,19 +261,19 @@ Gerrit IRC Notifications
========================
The intent of this section is to detail how to set up notifications
about all the projects that are hosted on OpenStack Gerrit in the
appropriate IRC channels.
about all the repositories that are hosted on OpenStack Gerrit in
the appropriate IRC channels.
GerritBot is an IRC bot that listens to the OpenStack Gerrit server
for events and notifies those on Freenode's OpenStack channels.
GerritBot is able to notify the channel for events like creation of patchsets, changes merged,
comments added to patchsets and updates to refs.
These event notifications can be configured per project, so the channel can have multiple
notifications per project.
These event notifications can be configured per repository, so the
channel can have multiple notifications per repository.
In order for GerritBot to post notifications on the IRC channel of the
project you are configuring,
repository you are configuring,
you need to add your GerritBot configuration into
``modules/gerritbot/files/gerritbot_channel_config.yaml``.
This file is hosted in `openstack-infra/config <http://git.openstack.org/cgit/openstack-infra/config/>`_.
@ -283,12 +287,13 @@ The syntax for configuring the notifications is::
- comment-added
- ref-updated
projects:
- <project name>
- <repository name>
branches:
- <branch name>
Please note that the text between the angle brackets are placeholder values. Multiple projects and branches can be
listed in the YAML file.
Please note that the text between the angle brackets are placeholder
values. Multiple repositories and branches can be listed in the YAML
file.
Running Jobs with Zuul
======================
@ -312,7 +317,7 @@ into several sections.
pipelines but they provide information on why each pipeline exists
and when it is triggered. This section is good as a reference.
#. Project templates. Useful if you want to collect several jobs under
a single name that can be reused across projects.
a single name that can be reused across repositories.
#. Job specific overrides. This section is where you specify that a
specific job should not vote or run only against a specific set
of branches.
@ -320,24 +325,25 @@ into several sections.
your time. Note it is organized into alphabetical subsections based
on git repo name prefix.
To add a job to a project you will need to edit your project in the
projects list or add your project to the list if it does not exist.
You should end up with something like::
To add a job to a repository you will need to edit your repository
in the projects list or add your repository to the list if it does
not exist. You should end up with something like::
- name: openstack/<project>
- name: openstack/<repositoryname>
template:
- name: merge-check
check:
- gate-new-<project>-job
- gate-new-<repositoryname>-job
gate:
- gate-new-<project>-job
- gate-new-<repositoryname>-job
The template section applies the common ``merge-check`` jobs to the
project (every project should use this template). Then we have
``gate-new-<project>-job`` listed in the check and gate pipelines. This
says if an event comes in for ``openstack/<project>`` that matches the
check or gate pipeline triggers run the ``gate-new-<project>-job``
job against ``openstack/<project>`` in the matching pipeline.
repository (every repository should use this template). Then we have
``gate-new-<repositoryname>-job`` listed in the check and gate
pipelines. This says if an event comes in for
``openstack/<repositoryname>`` that matches the check or gate
pipeline triggers run the ``gate-new-<repositoryname>-job`` job
against ``openstack/<repositoryname>`` in the matching pipeline.
Zuul comes with extensive `documentation <http://ci.openstack.org/zuul/>`_
too and should be referenced for more information.