Change many uses of repository to project
This is a manual that describes how to use the OpenStack project infrastructure. As the TC changes its mind on what words to use for what things, and redefines words to mean new things, this manual does not need to be updated to match. That the TC happens to use the word "project" to mean something in organizing its governance structure one day, but not the next, has little relation to how our tools are configured. Gerrit has an understanding of "projects". So does "zuul". It will be better for us to use the terminology we have traditionally used and that many of our tools and users use. We can certainly use the term "repository" when there might legitimately be confusion. But let us not force the manual into incomprehensibility by blindly adopting TC terminology where it is not needed. This is a partial revert of I574ab8e2c94eadce76cff9f7ea561dfa5d28b89c. However, that change did add many useful clarifications, so it is not a full revert. In short, I believe that this manual should use the common term "project" in almost all cases. The term "project" refers to the overall idea that there is a bunch of people working on a bunch of code/text/etc. It can also refer to that actual collection of code/text/etc (for instance, a project can be bundled up into a tarball, and extracted into a directory). When a tool interacts with that collection of code/text/etc, it interacts with the project (even if it does so via the mechanism of git). There are times when one needs to refer to the actual source code management system of the project, that is, "git", and the actual technical implementations of that SCM. In those cases where it is important to distinguish the actual attributes of the SCM from the project, it is useful to use the word "repository". Change-Id: I7cc37c32841fb33b38c3de90f426595de24a31d6
This commit is contained in:
James E. Blair
parent
e924339dd1
commit
f741b87b51
@ -1,7 +1,7 @@
|
||||
:title: Repository Creator's Guide
|
||||
:title: Project Creator's Guide
|
||||
|
||||
============================
|
||||
Repository Creator's Guide
|
||||
Project 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 Repository
|
||||
========================================
|
||||
Choosing a Good Name for Your Project
|
||||
=====================================
|
||||
|
||||
It is important to choose a descriptive name that does not conflict
|
||||
with other repositories. There are several places you'll need to
|
||||
look to ensure uniqueness and suitability of the name.
|
||||
with other projects. There are several places you'll need to look to
|
||||
ensure uniqueness and suitability of the name.
|
||||
|
||||
.. note::
|
||||
|
||||
@ -78,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
|
||||
repository is to make sure you have the right project management
|
||||
tools configured.
|
||||
project 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.
|
||||
@ -199,10 +199,10 @@ and click "Add Role".
|
||||
:height: 499
|
||||
:width: 800
|
||||
|
||||
Adding the Repository to the CI System
|
||||
======================================
|
||||
Adding the Project to the CI System
|
||||
===================================
|
||||
|
||||
To add a repository to the CI System, you need to modify some
|
||||
To add a project to the CI System, you need to modify some
|
||||
infrastructure configuration files using git and the OpenStack gerrit
|
||||
review server.
|
||||
|
||||
@ -210,12 +210,12 @@ All of the changes described in this section should be submitted
|
||||
together as one patchset to the ``openstack-infra/project-config``
|
||||
repository.
|
||||
|
||||
Add the repository to the master repositories list
|
||||
--------------------------------------------------
|
||||
Add the project to the master projects list
|
||||
-------------------------------------------
|
||||
|
||||
#. Edit ``gerrit/projects.yaml`` to add a new section like::
|
||||
|
||||
- project: openstack/<repositoryname>
|
||||
- project: openstack/<projectname>
|
||||
description: Latest and greatest cloud stuff.
|
||||
|
||||
#. Provide a very brief description of the library.
|
||||
@ -226,9 +226,9 @@ Add the repository to the master repositories list
|
||||
the publicly reachable repository and also read the information
|
||||
in :ref:`setup_review`::
|
||||
|
||||
- project: openstack/<repositoryname>
|
||||
- project: openstack/<projectname>
|
||||
description: Latest and greatest cloud stuff.
|
||||
upstream: git://github.com/awesumsauce/<repositoryname>.git
|
||||
upstream: git://github.com/awesumsauce/<projectname>.git
|
||||
|
||||
.. note::
|
||||
|
||||
@ -242,9 +242,9 @@ Add the repository to the master repositories list
|
||||
that they are associated with the https://launchpad.net/oslo
|
||||
project group for tracking bugs and milestones::
|
||||
|
||||
- project: openstack/<repositoryname>
|
||||
- project: openstack/<projectname>
|
||||
description: Latest and greatest cloud stuff.
|
||||
upstream: git://github.com/awesumsauce/<repositoryname>.git
|
||||
upstream: git://github.com/awesumsauce/<projectname>.git
|
||||
groups:
|
||||
- oslo
|
||||
|
||||
@ -253,14 +253,14 @@ Add the repository to the master repositories list
|
||||
Add Gerrit permissions
|
||||
----------------------
|
||||
|
||||
Each repository should have two gerrit groups. The first,
|
||||
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. Libraries for projects managed by the release team do not need
|
||||
this group, and should use ``library-release`` instead.
|
||||
|
||||
Create a ``gerrit/acls/openstack/<repositoryname>.config`` as
|
||||
Create a ``gerrit/acls/openstack/<projectname>.config`` as
|
||||
explained in the following sections.
|
||||
|
||||
|
||||
@ -284,7 +284,7 @@ change-ID for each change::
|
||||
Request Signing of ICLA
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If your repository requires signing of the Individual Contributor
|
||||
If your project requires signing of the Individual Contributor
|
||||
License Agreement (`ICLA
|
||||
<https://review.openstack.org/static/cla.html>`_), change the
|
||||
``receive`` section to::
|
||||
@ -294,13 +294,13 @@ License Agreement (`ICLA
|
||||
requireContributorAgreement = true
|
||||
|
||||
Note that this is mandatory for all official projects in the openstack
|
||||
namespace and should also be set for repositories that want to become
|
||||
namespace and should also be set for projects that want to become
|
||||
official.
|
||||
|
||||
Creation of Tags
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
For library repositories managed by the release team, allow the
|
||||
For library projects managed by the release team, allow the
|
||||
``library-release`` team to create tags by adding a new section
|
||||
containing::
|
||||
|
||||
@ -328,9 +328,9 @@ rule to it the ``refs/heads/*`` section::
|
||||
|
||||
Extended ACL File
|
||||
~~~~~~~~~~~~~~~~~
|
||||
So, if your repository requires the ICLA signed, has a release team
|
||||
So, if your project requires the ICLA signed, has a release team
|
||||
that will create tags and branches, create a
|
||||
``gerrit/acls/openstack/<repositoryname>.config`` like::
|
||||
``gerrit/acls/openstack/<projectname>.config`` like::
|
||||
|
||||
[access "refs/heads/*"]
|
||||
abandon = group <projectname>-core
|
||||
@ -358,21 +358,21 @@ jenkins-job-builder configuration files.
|
||||
|
||||
.. note::
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
Edit ``jenkins/jobs/projects.yaml`` to add your repository. There
|
||||
are several sections, designated in comments, for different types of
|
||||
Edit ``jenkins/jobs/projects.yaml`` to add your project. 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: <repositoryname>
|
||||
name: <projectname>
|
||||
node: 'bare-precise || bare-trusty'
|
||||
tarball-site: tarballs.openstack.org
|
||||
doc-publisher-site: docs.openstack.org
|
||||
@ -390,20 +390,20 @@ need.
|
||||
|
||||
.. note::
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
Edit ``zuul/layout.yaml`` to add your repository. There are several
|
||||
Edit ``zuul/layout.yaml`` to add your project. There are several
|
||||
sections, designated in comments, for different types of
|
||||
repositories. Find the right section and then add a new stanza like:
|
||||
projects. Find the right section and then add a new stanza like:
|
||||
|
||||
::
|
||||
|
||||
- name: openstack/<repositoryname>
|
||||
- name: openstack/<projectname>
|
||||
template:
|
||||
- name: merge-check
|
||||
- name: python-jobs
|
||||
@ -421,15 +421,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 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.
|
||||
your projects'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/<repositoryname>
|
||||
- name: openstack/<projectname>
|
||||
template:
|
||||
- name: merge-check
|
||||
- name: noop-jobs
|
||||
@ -438,9 +438,9 @@ 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 repository to be
|
||||
If you want changes proposed and merged to your project to be
|
||||
announced on IRC, edit ``gerritbot/channels.yaml`` to add your new
|
||||
repository to the list of repositories. For example, to announce
|
||||
project 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::
|
||||
|
||||
@ -533,7 +533,7 @@ library edit the "Oslo" section::
|
||||
- name: release:independent
|
||||
|
||||
When writing the commit message for this change, make this change
|
||||
depend on the repository creation change by including a link to its
|
||||
depend on the project creation change by including a link to its
|
||||
Change-ID (from the previous step)::
|
||||
|
||||
Depends-On: <Gerrit Change-Id>
|
||||
@ -545,7 +545,7 @@ that reviewers know that the governance change has been created.
|
||||
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
|
||||
direction (the project creation change should depend on the
|
||||
governance change because the TC needs to approve the new project
|
||||
team application first).
|
||||
|
||||
@ -576,39 +576,39 @@ release process can volunteer to be added as well.
|
||||
Updating devstack-vm-gate-wrap.sh
|
||||
---------------------------------
|
||||
|
||||
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
|
||||
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
|
||||
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 repository::
|
||||
``devstack-vm-gate-wrap.sh`` to add the new project::
|
||||
|
||||
PROJECTS="openstack/<repositoryname> $PROJECTS"
|
||||
PROJECTS="openstack/<projectname> $PROJECTS"
|
||||
|
||||
Keep the list in alphabetical order.
|
||||
|
||||
Add Repository to the Requirements List
|
||||
---------------------------------------
|
||||
Add Project to the Requirements List
|
||||
------------------------------------
|
||||
|
||||
The global requirements repository (openstack/requirements) controls
|
||||
which dependencies can be added to a repository to ensure that all
|
||||
which dependencies can be added to a project 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 repositories when the global
|
||||
requirements lists for OpenStack projects when the global
|
||||
requirements change.
|
||||
|
||||
If your repository is not going to participate in this requirements
|
||||
If your project 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/<repositoryname>" in the appropriate place in
|
||||
"openstack/<projectname>" in the appropriate place in
|
||||
alphabetical order.
|
||||
|
||||
Preparing a New Git Repository using cookiecutter
|
||||
=================================================
|
||||
|
||||
All OpenStack repositories should use one of our cookiecutter_
|
||||
All OpenStack projects should use one of our cookiecutter_
|
||||
templates for creating an initial repository to hold the source
|
||||
code.
|
||||
|
||||
@ -617,7 +617,7 @@ the change to project-config, you can skip this section.
|
||||
|
||||
Start by checking out a copy of your new repository::
|
||||
|
||||
$ git clone git://git.openstack.org/openstack/<repositoryname>
|
||||
$ git clone git://git.openstack.org/openstack/<projectname>
|
||||
|
||||
.. _cookiecutter: https://pypi.python.org/pypi/cookiecutter
|
||||
|
||||
@ -629,7 +629,7 @@ Choosing the Right cookiecutter Template
|
||||
----------------------------------------
|
||||
|
||||
The template in ``openstack-dev/cookiecutter`` is suitable for
|
||||
most repositories.
|
||||
most projects.
|
||||
|
||||
::
|
||||
|
||||
@ -646,15 +646,15 @@ Applying the Template
|
||||
---------------------
|
||||
|
||||
Running cookiecutter will prompt you for several settings, based on
|
||||
the template's configuration. It will then update your repository
|
||||
the template's configuration. It will then update your project
|
||||
with a skeleton, ready to have your other files added.
|
||||
|
||||
::
|
||||
|
||||
$ cd <repositoryname>
|
||||
$ cd <projectname>
|
||||
$ git review
|
||||
|
||||
If you configured all of the tests for the repository when it was
|
||||
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
|
||||
@ -664,7 +664,7 @@ Verify That Gerrit and the Test Jobs are Working
|
||||
================================================
|
||||
|
||||
The next step is to verify that you can submit a change request for
|
||||
the repository, have it pass the test jobs, approve it, and then have
|
||||
the project, have it pass the test jobs, approve it, and then have
|
||||
it merge.
|
||||
|
||||
.. _setup_review:
|
||||
@ -672,21 +672,21 @@ it merge.
|
||||
Configure ``git review``
|
||||
------------------------
|
||||
|
||||
If the new repository you have added has a specified upstream you
|
||||
If the new project 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/<repositoryname>
|
||||
$ cd <repositoryname>
|
||||
$ git clone https://git.openstack.org/openstack/<projectname>
|
||||
$ cd <projectname>
|
||||
$ git checkout -b add-gitreview
|
||||
$ cat > .gitreview <<EOF
|
||||
[gerrit]
|
||||
host=review.openstack.org
|
||||
port=29418
|
||||
project=openstack/<repositoryname>.git
|
||||
project=openstack/<projectname>.git
|
||||
EOF
|
||||
$ git review -s
|
||||
$ git add .gitreview
|
||||
@ -696,7 +696,7 @@ review and approve::
|
||||
Verify that the Tests Pass
|
||||
--------------------------
|
||||
|
||||
If you configure tests for an imported repository, ensure that all
|
||||
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.
|
||||
@ -704,14 +704,14 @@ tests locally using ``tox`` to verify that they pass.
|
||||
Verify the Gerrit Review Permissions
|
||||
------------------------------------
|
||||
|
||||
When your repository is added to gerrit, the groups defined in the
|
||||
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
|
||||
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/<repositoryname>,access``
|
||||
``https://review.openstack.org/#/admin/projects/openstack/<projectname>,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
|
||||
@ -720,22 +720,22 @@ their membership.
|
||||
Prepare an Initial Release
|
||||
==========================
|
||||
|
||||
Make Your Repository Useful
|
||||
---------------------------
|
||||
Make Your Project Useful
|
||||
------------------------
|
||||
|
||||
Before going any farther, make the repository do something useful.
|
||||
Before going any farther, make the project do something useful.
|
||||
|
||||
If you are importing an existing repository with features, you can
|
||||
If you are importing an existing project with features, you can
|
||||
go ahead.
|
||||
|
||||
If you are creating a brand new repository, add some code and tests
|
||||
If you are creating a brand new project, 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 repository.
|
||||
new project.
|
||||
|
||||
Update the rest of the documentation under ``doc/source`` with
|
||||
information about the public API, tips on adopting the tool,
|
||||
@ -746,7 +746,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 repository
|
||||
the first release, use "0.1.0". If other releases of the project
|
||||
exist, choose an appropriate next version number.
|
||||
|
||||
.. note::
|
||||
@ -767,13 +767,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 Repositories to Use Your Library
|
||||
=========================================================
|
||||
Allowing Other OpenStack 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.
|
||||
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.
|
||||
|
||||
Update the Global Requirements List
|
||||
-----------------------------------
|
||||
@ -787,27 +787,27 @@ Check out the ``openstack/requirements`` git repository and modify
|
||||
Setting up Gate Testing
|
||||
=======================
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
Updating devstack
|
||||
-----------------
|
||||
|
||||
#. Check out ``openstack-dev/devstack``.
|
||||
|
||||
#. 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``::
|
||||
#. 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``::
|
||||
|
||||
<REPOSITORYNAME>_DIR=$DEST/<repositoryname>
|
||||
<PROJECTNAME>_DIR=$DEST/<projectname>
|
||||
|
||||
#. Edit the installation function in the same file to add commands to
|
||||
check out the repository. For example, when adding an Oslo library,
|
||||
check out the project. For example, when adding an Oslo library,
|
||||
change :func:`install_oslo` in ``lib/oslo``.
|
||||
|
||||
When adding the new item, consider the installation
|
||||
@ -818,16 +818,16 @@ Updating devstack
|
||||
|
||||
function install_oslo() {
|
||||
...
|
||||
_do_install_oslo_lib "<repositoryname>"
|
||||
_do_install_oslo_lib "<projectname>"
|
||||
...
|
||||
}
|
||||
|
||||
#. Edit ``stackrc`` to add the other variables needed for configuring the
|
||||
new library::
|
||||
|
||||
# new-repository
|
||||
<REPOSITORYNAME>_REPO=${<REPOSITORYNAME>_REPO:-${GIT_BASE}/openstack/<repositoryname>.git}
|
||||
<REPOSITORYNAME>_BRANCH=${<REPOSITORYNAME>_BRANCH:-master}
|
||||
# new-project
|
||||
<PROJECTNAME>_REPO=${<PROJECTNAME>_REPO:-${GIT_BASE}/openstack/<projectname>.git}
|
||||
<PROJECTNAME>_BRANCH=${<PROJECTNAME>_BRANCH:-master}
|
||||
|
||||
Add Link to Your Developer Documentation
|
||||
========================================
|
||||
@ -837,7 +837,7 @@ 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 repository is under ``stackforge``.
|
||||
Skip this step if your project is under ``stackforge``.
|
||||
|
||||
Project Renames
|
||||
===============
|
||||
|
||||
@ -183,12 +183,12 @@ 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 Repository
|
||||
---------------------------------
|
||||
Starting Work on a New Project
|
||||
------------------------------
|
||||
|
||||
Clone a repository in the usual way, for example::
|
||||
|
||||
git clone https://git.openstack.org/openstack/<repositoryname>.git
|
||||
git clone https://git.openstack.org/openstack/<projectname>.git
|
||||
|
||||
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
|
||||
@ -196,7 +196,7 @@ 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 <repositoryname>
|
||||
cd <projectname>
|
||||
git review -s
|
||||
|
||||
Git-review checks that you can log in to Gerrit with your ssh key. It
|
||||
@ -440,7 +440,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
|
||||
repository, and the target branch to uniquely identify a change.
|
||||
project, 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
|
||||
@ -469,9 +469,8 @@ 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 repository, squash your many
|
||||
"checkpoint" commits into one commit for public consumption. Here's
|
||||
how::
|
||||
are making one "change" to the project, squash your many "checkpoint"
|
||||
commits into one commit for public consumption. Here's how::
|
||||
|
||||
git checkout master
|
||||
git pull origin master
|
||||
@ -599,13 +598,13 @@ Multiple Changes
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
A Gerrit change ID may refer to multiple changes (on multiple branches
|
||||
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.
|
||||
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.
|
||||
|
||||
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
|
||||
@ -670,11 +669,11 @@ For more details on reviews in Gerrit, check the
|
||||
Automated Testing
|
||||
-----------------
|
||||
|
||||
When a new patchset is uploaded to Gerrit, that repository's "check"
|
||||
When a new patchset is uploaded to Gerrit, that project'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 repository's "gate" tests are run
|
||||
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
|
||||
@ -702,15 +701,14 @@ 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 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.
|
||||
2. Identify which project or projects 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".
|
||||
@ -740,8 +738,8 @@ 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 repository's
|
||||
`HACKING.rst` file, if it has one. If the repository reuses
|
||||
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
|
||||
automatically for you by the continuous integration system.
|
||||
@ -814,7 +812,7 @@ reviews:
|
||||
clear instructions for the submitter how they might fix the patch.
|
||||
|
||||
There may be more specific items to be aware of inside the
|
||||
repositories' documentation for contributors.
|
||||
projects' 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
|
||||
@ -856,18 +854,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 repository are still mergeable. If any
|
||||
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.
|
||||
|
||||
After a change is merged, repository-specific post jobs are run.
|
||||
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.
|
||||
|
||||
Repository Gating
|
||||
-----------------
|
||||
Project Gating
|
||||
--------------
|
||||
|
||||
Repository gating refers to the process of running regression tests
|
||||
Project 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
|
||||
@ -889,10 +887,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 across multiple repositories. The changes are tested
|
||||
of changes to merge across multiple projects. 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 repository gating and Zuul can
|
||||
be found in the Zuul documentation, located at:
|
||||
Additional information about project gating and Zuul can be found in
|
||||
the Zuul documentation, located at:
|
||||
http://docs.openstack.org/infra/zuul/gating.html
|
||||
|
||||
@ -17,21 +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 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.
|
||||
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.
|
||||
|
||||
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.
|
||||
If more than one project is involved in a feature development effort,
|
||||
the same feature branch name should be used across all involved
|
||||
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.
|
||||
|
||||
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
|
||||
@ -41,8 +41,8 @@ Merge Commits
|
||||
-------------
|
||||
|
||||
An important activity when using feature branches is syncing to and from
|
||||
the repository's master branch. During development on a feature
|
||||
branch a repository will want to merge master into the feature branch
|
||||
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.
|
||||
@ -53,7 +53,7 @@ have access to push merge commits in Gerrit::
|
||||
[access "refs/for/refs/*"]
|
||||
pushMerge = group <projectname>-release
|
||||
|
||||
Should be added to the repository's ACL file in the project-config
|
||||
Should be added to the project's ACL file in the project-config
|
||||
repo.
|
||||
|
||||
Merge Master into Feature Branch
|
||||
@ -129,13 +129,13 @@ commit to record the state of the branch at the time.
|
||||
Create proposed/* Branch
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
For OpenStack repositories this should be performed by the OpenStack
|
||||
For OpenStack projects 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
|
||||
branches for your project you may have permission to do this
|
||||
yourself.
|
||||
|
||||
* Go to https://review.openstack.org/ and sign in
|
||||
* Select 'Admin', 'Projects', then the repository
|
||||
* Select 'Admin', 'Projects', then the project
|
||||
* Select 'Branches'
|
||||
* Enter ``proposed/<series>`` in the 'Branch Name' field, and ``HEAD``
|
||||
as the 'Initial Revision', then press 'Create Branch'.
|
||||
@ -199,7 +199,7 @@ 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
|
||||
repositories, master for clients/libraries) with a release tag and
|
||||
projects, master for clients/libraries) with a release tag and
|
||||
push that tag to Gerrit by running the following commands::
|
||||
|
||||
git checkout <branch name>
|
||||
@ -233,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 repository
|
||||
* Select 'Admin', 'Projects', then the project
|
||||
* Select 'Branches'
|
||||
* Select the checkbox next to 'proposed/<series>' and hit 'Delete'
|
||||
|
||||
@ -241,42 +241,45 @@ Targeting Blueprints
|
||||
====================
|
||||
|
||||
Blueprints for a project are generally posted to
|
||||
https://blueprints.launchpad.net/<projectname>. Project drivers need to review
|
||||
blueprints regularly and assign them to a target. For each release there are three
|
||||
milestones. Based on interactions with the proposer and/or assignee of the blueprint,
|
||||
the project driver assigns the blueprint to a milestone
|
||||
(release-1, release-2 or release-3) or defers it to a later release.
|
||||
https://blueprints.launchpad.net/<projectname>. Project drivers need
|
||||
to review blueprints regularly and assign them to a target. For each
|
||||
release there are three milestones. Based on interactions with the
|
||||
proposer and/or assignee of the blueprint, the project driver assigns
|
||||
the blueprint to a milestone (release-1, release-2 or release-3) or
|
||||
defers it to a later release.
|
||||
|
||||
Many projects have repositories entitled <projectteam>-specs. If a project has a spec
|
||||
repo, a spec needs to be submitted and linked to the launchpad blueprint. The spec
|
||||
needs to be reviewed and approved prior to the launchpad blueprint being targeted to
|
||||
a milestone.
|
||||
Many projects have repositories entitled <project>-specs. If a project
|
||||
has a spec repo, a spec needs to be submitted and linked to the
|
||||
launchpad blueprint. The spec needs to be reviewed and approved prior
|
||||
to the launchpad blueprint being targeted to a milestone.
|
||||
|
||||
Interactions with release management includes discussions of the blueprint target
|
||||
page: https://launchpad.net/<projectname>/+milestone/{release name}-{1|2|3} The more
|
||||
the blueprint target page reflects the reality of progress and intentions, the happier
|
||||
the release management team.
|
||||
Interactions with release management includes discussions of the
|
||||
blueprint target page:
|
||||
https://launchpad.net/<projectname>/+milestone/{release name}-{1|2|3}
|
||||
The more the blueprint target page reflects the reality of progress
|
||||
and intentions, the happier the release management team.
|
||||
|
||||
Gerrit IRC Notifications
|
||||
========================
|
||||
|
||||
The intent of this section is to detail how to set up notifications
|
||||
about all the repositories that are hosted on OpenStack Gerrit in
|
||||
the appropriate IRC channels.
|
||||
about all the projects 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 repository, so the
|
||||
channel can have multiple notifications per repository.
|
||||
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.
|
||||
|
||||
In order for GerritBot to post notifications on the IRC channel of the
|
||||
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/>`_.
|
||||
project 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/>`_.
|
||||
|
||||
The syntax for configuring the notifications is::
|
||||
|
||||
@ -287,12 +290,12 @@ The syntax for configuring the notifications is::
|
||||
- comment-added
|
||||
- ref-updated
|
||||
projects:
|
||||
- <repository name>
|
||||
- <project name>
|
||||
branches:
|
||||
- <branch name>
|
||||
|
||||
Please note that the text between the angle brackets are placeholder
|
||||
values. Multiple repositories and branches can be listed in the YAML
|
||||
values. Multiple projects and branches can be listed in the YAML
|
||||
file.
|
||||
|
||||
Running Jobs with Zuul
|
||||
@ -317,7 +320,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 repositories.
|
||||
a single name that can be reused across projects.
|
||||
#. 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.
|
||||
@ -325,25 +328,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 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::
|
||||
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::
|
||||
|
||||
- name: openstack/<repositoryname>
|
||||
- name: openstack/<projectname>
|
||||
template:
|
||||
- name: merge-check
|
||||
check:
|
||||
- gate-new-<repositoryname>-job
|
||||
- gate-new-<projectname>-job
|
||||
gate:
|
||||
- gate-new-<repositoryname>-job
|
||||
- gate-new-<projectname>-job
|
||||
|
||||
The template section applies the common ``merge-check`` jobs to the
|
||||
repository (every repository should use this template). Then we have
|
||||
``gate-new-<repositoryname>-job`` listed in the check and gate
|
||||
project (every project should use this template). Then we have
|
||||
``gate-new-<projectname>-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.
|
||||
``openstack/<projectname>`` that matches the check or gate pipeline
|
||||
triggers run the ``gate-new-<projectname>-job`` job against
|
||||
``openstack/<projectname>`` in the matching pipeline.
|
||||
|
||||
Integration Tests
|
||||
-----------------
|
||||
|
||||
Loading…
Reference in New Issue
Block a user