opendev/infra-manual
Code Issues Proposed changes

OpenDev Update for Creator's Guide

Browse Source 
This is a first iteration on making the Creator's Guide ready for
OpenDev. The whole file needs some more sections moved out, let's tackle
those separately.

It removes the section "Updating devstack-vm-gate-wrap.sh" since that is
not needed anymore.

Remove section "Add Project to the Requirements List" since the syncing
is not done anymore.

Change-Id: Idd949b3459cb136391abea8039d44ee80e8b1992
This commit is contained in:
Andreas Jaeger 2020-03-05 09:55:56 +01:00
parent a711d9ebb3
commit e8e73d18f4
1 changed files with 70 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

148
doc/source/creators.rst
View File

@ -14,28 +14,35 @@ 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 are given here. Don't skip any steps. Don't try to do things in
parallel. Don't jump around. parallel. Don't jump around.
If your project is already set up in the OpenStack CI infrastructure, If your project is already set up in the OpenDev infrastructure,
you might want to see :ref:`zuul_best_practices` for information on you might want to see :ref:`zuul_best_practices` for information on
adding new tests to a repository. adding new tests to a repository.
Decide Status of your Project Decide Status and Namespace of your Project
============================= ===========================================
The OpenStack CI infrastructure can be used both by official OpenStack OpenDev is used by different projects which often use different
projects and also by OpenStack-related projects. namespaces. Some of these namespaces have special policies.
Official projects are those that have applied for this status with the If your project does not fit into one of the existing namespaces, you
technical committee. The `governance site`_ contains details on how may create a new one, or use the catch-all ``x`` namespace if you
to become one and the list of current `OpenStack Project Teams`_. The cannot decide.
`Project Team Guide`_ explains how OpenStack project teams work.
If you add a new repository, you can make it part of an existing For OpenStack and thus the ``openstack`` namespace, the policies are:
official OpenStack project, use it to start a new official project, or
start as a `related project`_ (formerly known as *StackForge*).
Note that only official OpenStack projects may use certain parts of * Official OpenStack projects are those that have applied for this
the OpenStack infrastructure, especially the docs.openstack.org and status with the technical committee. The `governance site`_ contains
specs.openstack.org server. details on how to become one and the list of current `OpenStack
Project Teams`_. The `Project Team Guide`_ explains how OpenStack
project teams work.
* If you add a new repository, you can make it part of an existing
official OpenStack project, use it to start a new official project, or
start as a `related project`_ (formerly known as *StackForge*).
* Note that only official OpenStack projects may use certain parts of
the OpenStack infrastructure, especially the docs.openstack.org and
specs.openstack.org server.
.. _governance site: https://governance.openstack.org .. _governance site: https://governance.openstack.org
.. _OpenStack Project Teams: https://governance.openstack.org/tc/reference/projects/index.html .. _OpenStack Project Teams: https://governance.openstack.org/tc/reference/projects/index.html
@ -88,19 +95,19 @@ the name used to import the package in source files match. Try
Project Team Rules Project Team Rules
------------------ ------------------
Some OpenStack project teams have naming conventions that must be Some hosted project teams have naming conventions that must be
followed. For example, the Oslo team has `instructions for choosing a followed. For example, the OpenStack Oslo team has `instructions for
name`_ for new Oslo libraries. choosing a name`_ for new Oslo libraries.
.. _instructions for choosing a name: https://wiki.openstack.org/wiki/Oslo/CreatingANewLibrary#Choosing_a_Name .. _instructions for choosing a name: https://wiki.openstack.org/wiki/Oslo/CreatingANewLibrary#Choosing_a_Name
.. _register-pypi: .. _register-pypi:
Give OpenStack Permission to Publish Releases Give OpenDev Permission to Publish Releases
============================================= ===========================================
New packages without any releases need to be manually registered on New Python packages without any releases need to be manually
PyPI. registered on PyPI.
If you do not have PyPI credentials, you should create them at If you do not have PyPI credentials, you should create them at
https://pypi.org/account/register/ as they are https://pypi.org/account/register/ as they are
@ -134,20 +141,22 @@ Adding the Project to the CI System
=================================== ===================================
To add a project 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 infrastructure configuration files using git and the OpenDev gerrit
review server. review server.
Note that you need two changes to set up your new project Note that you need two changes to set up your new project
for testing with OpenStack CI systems. for testing with OpenDev CI systems.
* First change to create the git repository, configure ACLs, and add * First change to create the git repository, configure ACLs, and add
the git repository to the OpenStack CI system, see the git repository to the OpenDev CI system, see
:ref:`add_project_to_master_projects_list` and following sections. :ref:`add_project_to_master_projects_list` and following sections.
For official projects, this change should also link via
For official OpenStack projects, this change should also link via
``Needed-By`` to a change for the ``openstack/governance`` ``Needed-By`` to a change for the ``openstack/governance``
repository to add the new repository under the project team, see repository to add the new repository under the project team, see
:ref:`add-to-governance-repo`. This change is for :ref:`add-to-governance-repo`.
``openstack/project-config`` repository.
This change is for ``openstack/project-config`` repository.
* Second change to add jobs to your project, see * Second change to add jobs to your project, see
:ref:`add_jobs_for_project`. This one can only pass Zuul internal :ref:`add_jobs_for_project`. This one can only pass Zuul internal
@ -163,30 +172,25 @@ Add the project to the master projects list
.. code-block:: yaml .. code-block:: yaml
- project: openstack/<projectname> - project: <namespace>/<projectname>
description: Latest and greatest cloud stuff. description: Latest and greatest cloud stuff.
use-storyboard: true use-storyboard: true
Note: All projects should use the ``openstack/`` namespace The ``use-storyboard: true`` is added so that repos will be automatically
regardless of whether they are or intend to become official created as projects in `StoryBoard <https://docs.openstack.org/infra/storyboard/>`_
OpenStack projects. (community tool for managing work being done in your project and tracking tasks).
.. note:: #. Provide a very brief description of the project.
The ``use-storyboard: true`` is added so that repos will be automatically
created as projects in `StoryBoard <https://docs.openstack.org/infra/storyboard/>`_
(community tool for managing work being done in your project and tracking tasks).
#. Provide a very brief description of the library.
#. If you have an existing repository that you want to import (for #. If you have an existing repository that you want to import (for
example, when graduating an Oslo library or bringing a repository example, when bringing a repository
into gerrit from github), set the "upstream" field to the URL of into gerrit from github), set the "upstream" field to the URL of
the publicly reachable repository and also read the information the publicly reachable repository and also read the information
in :ref:`setup_review`: in :ref:`setup_review`:
.. code-block:: yaml .. code-block:: yaml
- project: openstack/<projectname> - project: <namespace>/<projectname>
description: Latest and greatest cloud stuff. description: Latest and greatest cloud stuff.
upstream: https://github.com/awesumsauce/<projectname>.git upstream: https://github.com/awesumsauce/<projectname>.git
@ -212,7 +216,7 @@ Add the project to the master projects list
.. code-block:: yaml .. code-block:: yaml
- project: openstack/<projectname> - project: <namespace>/<projectname>
description: Latest and greatest cloud stuff. description: Latest and greatest cloud stuff.
use-storyboard: true use-storyboard: true
upstream: https://github.com/awesumsauce/<projectname>.git upstream: https://github.com/awesumsauce/<projectname>.git
@ -237,12 +241,12 @@ Each project should have a gerrit group "<projectname>-core",
containing the normal core group, with permission to containing the normal core group, with permission to
+2 changes. +2 changes.
Release management of official projects is handled by the Release For official OpenStack projects, release management is handled by the Release
Management team through the ``openstack/releases`` repository, the Management team through the ``openstack/releases`` repository, the
default settings allow the "``Release Managers``" team to push tags default settings allow the "``Release Managers``" team to push tags
and create branches. and create branches.
For unofficial projects, a second "<projectname>-release" team should For all other projects, a second "<projectname>-release" team should
be created and populated with a small group of the primary maintainers be created and populated with a small group of the primary maintainers
with permission to push tags to trigger releases. with permission to push tags to trigger releases.
@ -260,7 +264,7 @@ explained in the following sections.
.. code-block:: yaml .. code-block:: yaml
- project: openstack/<projectname> - project: <namespace>/<projectname>
description: Latest and greatest cloud stuff. description: Latest and greatest cloud stuff.
acl-config: /home/gerrit2/acls/openstack/other-project.config acl-config: /home/gerrit2/acls/openstack/other-project.config
@ -304,8 +308,9 @@ should also be set for projects that want to become official.
Creation of Tags Creation of Tags
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~
For unofficial projects, you can allow the project-specific release If your project is not handled by the OpenStack release team, you can
team to create tags by adding a new section containing: allow the project-specific release team to create tags by adding a new
section containing:
.. code-block:: ini .. code-block:: ini
@ -329,7 +334,8 @@ OpenStack infrastructure which fire on tags, will have that tag indefinitely.
Creation of Branches Creation of Branches
~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~
For unofficial projects, to allow creation of branches to the release For projects not handled by the Openstack release team, to allow
creation of branches to the project release
team, add a ``create`` rule to it the ``refs/heads/*`` section: team, add a ``create`` rule to it the ``refs/heads/*`` section:
.. code-block:: ini .. code-block:: ini
@ -344,7 +350,7 @@ Deletion of Branches
~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~
Members of a team that can create branches do not have access to delete Members of a team that can create branches do not have access to delete
branches. Instead, someone on the infrastructure team with gerrit administrator branches. Instead, someone on the OpenDev team with gerrit administrator
privileges will need to complete this request. privileges will need to complete this request.
Stable Maintenance Team Stable Maintenance Team
@ -402,7 +408,7 @@ Extended ACL File
So, if your official project requires the ICLA signed and allow voting So, if your official project requires the ICLA signed and allow voting
third-party CI systems, create a third-party CI systems, create a
``gerrit/acls/openstack/<projectname>.config`` like: ``gerrit/acls/<namespace>/<projectname>.config`` like:
.. code-block:: ini .. code-block:: ini
@ -419,9 +425,9 @@ third-party CI systems, create a
[submit] [submit]
mergeContent = true mergeContent = true
If your unofficial project requires the ICLA signed, has a release If your project does not require the ICLA signed, has a release
team that will create tags and branches, and allow voting third-party team that will create tags and branches, and allow voting third-party
CI systems, create a ``gerrit/acls/openstack/<projectname>.config`` CI systems, create a ``gerrit/acls/<namespace>/<projectname>.config``
like: like:
.. code-block:: ini .. code-block:: ini
@ -438,7 +444,6 @@ like:
[receive] [receive]
requireChangeId = true requireChangeId = true
requireContributorAgreement = true
[submit] [submit]
mergeContent = true mergeContent = true
@ -459,7 +464,7 @@ 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 project to be
announced on IRC, edit ``gerritbot/channels.yaml`` to add your new announced on IRC, edit ``gerritbot/channels.yaml`` to add your new
project to the list of projects. For example, to announce project to the list of projects. For example, to announce
changes related to an Oslo library in the ``#openstack-oslo`` changes related to an OpenStack Oslo library in the ``#openstack-oslo``
channel, add it to the ``openstack-oslo`` section: channel, add it to the ``openstack-oslo`` section:
.. code-block:: yaml .. code-block:: yaml
@ -583,7 +588,8 @@ Central Config Exceptions
There are several notable exceptions for job configs that should remain There are several notable exceptions for job configs that should remain
in the central config repository ``openstack/project-config``: in the central config repository ``openstack/project-config``:
* Translation jobs for all branches. * Translation jobs for all branches, note that only OpenStack official
projects are translated.
* Jobs that should only run against the master branch of the project * Jobs that should only run against the master branch of the project
they are applied to. they are applied to.
@ -692,8 +698,8 @@ coordinate with the Infra team, and read ahead, but don't do any of
these other steps until the import is complete and the new repository these other steps until the import is complete and the new repository
is configured. is configured.
The Infra team can be contacted by pinging ``infra-root`` in the The OpenDev team can be contacted by pinging ``infra-root`` in the
``#openstack-infra`` channel on Freenode IRC, or via email to the `openstack-infra ``#opendev`` channel on Freenode IRC, or via email to the `openstack-infra
<http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-infra>`_ <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-infra>`_
mail list. mail list.
@ -733,23 +739,6 @@ Check out ``openstack/devstack-gate`` and edit
Keep the list in alphabetical order. Keep the list in alphabetical order.
Add Project 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
conflicts. It also automatically contributes updates to the
requirements lists for OpenStack projects when the global
requirements change.
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/<projectname>" in the appropriate place in
alphabetical order.
Preparing a New Git Repository using cookiecutter Preparing a New Git Repository using cookiecutter
================================================= =================================================
@ -835,7 +824,7 @@ Adding In-Repo Zuul Jobs
Every project needs test jobs. Every project needs test jobs.
OpenStack has a number of jobs and project-templates that can be used OpenDev has a number of jobs and project-templates that can be used
directly in your project's Zuul config. You can also make new jobs that directly in your project's Zuul config. You can also make new jobs that
inherit from existing jobs or or you can write your own from scratch. inherit from existing jobs or or you can write your own from scratch.
@ -920,7 +909,7 @@ You can then use the secret in a job inheriting from
- job: - job:
name: <project>-upload-git-mirror name: <project>-upload-git-mirror
parent: upload-git-mirror parent: upload-git-mirror
description: Mirrors openstack/<project> to neworg/<project> description: Mirrors <namespace>/<project> to neworg/<project>
vars: vars:
git_mirror_repository: neworg/<project> git_mirror_repository: neworg/<project>
secrets: secrets:
@ -969,14 +958,14 @@ review and approve:
.. code-block:: console .. code-block:: console
$ git clone https://opendev.org/openstack/<projectname> $ git clone https://opendev.org/<namespace>/<projectname>
$ cd <projectname> $ cd <projectname>
$ git checkout -b add-gitreview $ git checkout -b add-gitreview
$ cat > .gitreview <<EOF $ cat > .gitreview <<EOF
[gerrit] [gerrit]
host=review.opendev.org host=review.opendev.org
port=29418 port=29418
project=openstack/<projectname>.git project=<namespace>/<projectname>.git
EOF EOF
$ git review -s $ git review -s
$ git add .gitreview $ git add .gitreview
@ -1078,7 +1067,8 @@ other projects to use your library.
Update the Global Requirements List Update the Global Requirements List
----------------------------------- -----------------------------------
Check out the ``openstack/requirements`` git repository and modify If you have a library that is used by OpenStack repositories,
check out the ``openstack/requirements`` git repository and modify
``global-requirements.txt`` to: ``global-requirements.txt`` to:
#. add the new library #. add the new library
@ -1141,6 +1131,8 @@ documentation by following the instructions at `Template generator details
Enabling Translation Infrastructure Enabling Translation Infrastructure
=================================== ===================================
If your project is not an official OpenStack project, skip this section.
Once you have your project set up, you might want to enable Once you have your project set up, you might want to enable
translations. For this, you first need to mark all strings so that translations. For this, you first need to mark all strings so that
they can be localized, use `oslo.i18n`_ for this and follow the they can be localized, use `oslo.i18n`_ for this and follow the