Update contributor guide
... or "what I wish existed when I first became PTL" Some general improvements to the contributor guide, plus new sections for PTL duties and release management. Change-Id: Ib3c1c8179adb7ad8e10d5e0223232b7a734bde53
This commit is contained in:
Mark Goddard
parent
b55fa2f8b7
commit
da16744a9a
@ -7,7 +7,7 @@ How To Contribute
|
||||
Basics
|
||||
======
|
||||
|
||||
#. Our source code is hosted on `OpenStack Kolla Git
|
||||
#. Our source code is hosted on `OpenDev Kolla Git
|
||||
<https://opendev.org/openstack/kolla/>`_. Bugs should be filed on
|
||||
`launchpad <https://bugs.launchpad.net/kolla>`_.
|
||||
|
||||
@ -27,16 +27,33 @@ Basics
|
||||
For simple changes, contributors may optionally add the text "TrivialFix" to
|
||||
the commit message footer to indicate to reviewers a bug is not required.
|
||||
|
||||
#. We use a `whiteboard <https://etherpad.openstack.org/p/KollaWhiteBoard>`__
|
||||
to keep track of CI gate status, release status, stable backports, planning
|
||||
and feature development status.
|
||||
|
||||
Please use the existing sandbox repository, available at `sandbox
|
||||
<https://opendev.org/openstack-dev/sandbox>`_,
|
||||
for learning, understanding and testing the `Gerrit Workflow
|
||||
<https://docs.openstack.org/infra/manual/developers.html#development-workflow>`_.
|
||||
|
||||
Adding a release note
|
||||
=====================
|
||||
|
||||
All new features should have a documented release note. To add a release note
|
||||
run the following command:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
tox -e venv -- reno new <feature-being-added>
|
||||
|
||||
Typically in this project we do not add release notes for bug fixes. Upgrade
|
||||
notes can be extremely helpful for operators so these are encouraged.
|
||||
|
||||
Adding a new service
|
||||
====================
|
||||
|
||||
Kolla aims to both containerise and deploy all services within the OpenStack
|
||||
"big tent". This is a constantly moving target as the ecosystem grows, so these
|
||||
ecosystem. This is a constantly moving target as the ecosystem grows, so these
|
||||
guidelines aim to help make adding a new service to Kolla a smooth experience.
|
||||
|
||||
The image
|
||||
|
||||
@ -1,13 +1,13 @@
|
||||
============
|
||||
Development
|
||||
============
|
||||
=================
|
||||
Contributor Guide
|
||||
=================
|
||||
|
||||
Contributing
|
||||
------------
|
||||
This guide is for contributors of the Kolla project. It includes information on
|
||||
proposing your first patch and how to participate in the community. It also
|
||||
covers responsibilities of core reviewers and the Project Team Lead (PTL), and
|
||||
information about development processes.
|
||||
|
||||
This guide is to tell someone who would like to contribute to
|
||||
Kolla project. Following this guide to propose your first patch for Kolla.
|
||||
And we are welcome everyone to join our project!
|
||||
We welcome everyone to join our project!
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
@ -15,3 +15,5 @@ And we are welcome everyone to join our project!
|
||||
CONTRIBUTING.rst
|
||||
running-tests
|
||||
bug-triage
|
||||
ptl-guide
|
||||
release-management
|
||||
|
||||
113
doc/source/contributor/ptl-guide.rst
Normal file
113
doc/source/contributor/ptl-guide.rst
Normal file
@ -0,0 +1,113 @@
|
||||
=========
|
||||
PTL Guide
|
||||
=========
|
||||
|
||||
This is just a reference guide that a PTL may use as an aid, if they choose.
|
||||
It is meant to complement the `official PTL guide
|
||||
<https://docs.openstack.org/project-team-guide/ptl.html>`__, and is laid out in
|
||||
rough chronological order.
|
||||
|
||||
Some or all of these tasks may be delegated to other team members.
|
||||
|
||||
New PTL
|
||||
=======
|
||||
|
||||
* Update the kolla meeting chair
|
||||
|
||||
* https://opendev.org/opendev/irc-meetings/src/branch/master/meetings/kolla-team-meeting.yaml
|
||||
|
||||
* Update the team wiki
|
||||
|
||||
* https://wiki.openstack.org/wiki/Kolla#Active_Contributors
|
||||
|
||||
* Get acquainted with the release schedule, bearing in mind that Kolla is a
|
||||
cycle-trailing project
|
||||
|
||||
* Example: https://releases.openstack.org/train/schedule.html
|
||||
|
||||
Open Infrastructure Summit
|
||||
==========================
|
||||
|
||||
Ideally the Kolla PTL will be able to attend the summit. If not, try to arrange
|
||||
for another member of the core team to represent the team. Good interaction
|
||||
with the community at these events is crucial to encourage upstream
|
||||
involvement, onboard new users, collect feedback and for the perceived health
|
||||
of the project.
|
||||
|
||||
* Create a summit planning etherpad and alert about it in the kolla IRC meeting
|
||||
and openstack-discuss mailing list
|
||||
|
||||
* Example: https://etherpad.openstack.org/p/kolla-train-summit
|
||||
|
||||
* Gather ideas for forum sessions
|
||||
|
||||
* Example: user feedback & roadmap, design sessions
|
||||
|
||||
* Prepare the project update presentation. Enlist help of others
|
||||
|
||||
* Prepare the on-boarding session materials. Enlist help of others
|
||||
|
||||
* Represent and promote the project while at the summit
|
||||
|
||||
Project Team Gathering (PTG)
|
||||
============================
|
||||
|
||||
Some of the Kolla team may decide to meet in person at the Project Team
|
||||
Gathering (PTG). Alternatively, they may decide to host a virtual PTG at a
|
||||
different time if there is not a critical mass of contributors attending the
|
||||
PTG.
|
||||
|
||||
* Create PTG planning etherpad and alert about it in the
|
||||
kolla IRC meeting and openstack-discuss mailing list
|
||||
|
||||
* Example: https://etherpad.openstack.org/p/kolla-train-ptg
|
||||
|
||||
* Run sessions at the PTG
|
||||
|
||||
* Have a discussion about priorities for the upcoming release cycle at the PTG
|
||||
|
||||
* Sign up for group photo at the PTG (if applicable)
|
||||
|
||||
After Summit & PTG
|
||||
==================
|
||||
|
||||
* Send session summaries to the openstack-discuss mailing list
|
||||
|
||||
* Update the `Kolla whiteboard
|
||||
<https://etherpad.openstack.org/p/KollaWhiteBoard>`__ with decided priorities
|
||||
for the upcoming release cycle
|
||||
|
||||
Day to Day
|
||||
==========
|
||||
|
||||
* Subscribe to the kolla projects on Launchpad to receive all bug and blueprint
|
||||
updates.
|
||||
|
||||
* :doc:`Triage new bugs <bug-triage>`
|
||||
|
||||
* Monitor the status of the CI system for all supported branches. Fix issues
|
||||
that break the gate
|
||||
|
||||
* Chair the IRC meetings
|
||||
|
||||
* Be available in IRC to help new and existing contributors
|
||||
|
||||
* Keep track of the progress of cycle priorites
|
||||
|
||||
* Monitor the core team membership, mentor potential cores
|
||||
|
||||
Release Management
|
||||
==================
|
||||
|
||||
* Follow the project's :doc:`release management <release-management>` guide
|
||||
|
||||
* Use the IRC meeting and/or mailing list to communicate release schedule to
|
||||
the team who might not be so famailiar with it
|
||||
|
||||
Handing Over
|
||||
============
|
||||
|
||||
* Support the new PTL in their new role. Try to remember the issues you
|
||||
encountered
|
||||
|
||||
* Update this page with any useful information you have learned
|
||||
199
doc/source/contributor/release-management.rst
Normal file
199
doc/source/contributor/release-management.rst
Normal file
@ -0,0 +1,199 @@
|
||||
==================
|
||||
Release Management
|
||||
==================
|
||||
|
||||
This guide is intended to complement the `OpenStack releases site
|
||||
<https://releases.openstack.org/>`__, and the project team guide's section on
|
||||
`release management
|
||||
<https://docs.openstack.org/project-team-guide/release-management.html>`__.
|
||||
|
||||
Team members make themselves familiar with the release schedule for the current
|
||||
release, for example https://releases.openstack.org/train/schedule.html.
|
||||
|
||||
Release Model
|
||||
=============
|
||||
|
||||
As a deployment project, Kolla's release model differs from many other
|
||||
OpenStack projects. Kolla follows the `cycle-trailing
|
||||
<https://docs.openstack.org/project-team-guide/release-management.html#trailing-the-common-cycle>`__
|
||||
release model, to allow time after the OpenStack coordinated release to wait
|
||||
for distribution packages and support new features. This gives us three months
|
||||
after the final release to prepare our final releases. Users are typically keen
|
||||
to try out the new release, so we should aim to release as early as possible
|
||||
while ensuring we have confidence in the release.
|
||||
|
||||
Release Schedule
|
||||
================
|
||||
|
||||
While we don't wish to repeat the OpenStack release documentation, we will
|
||||
point out the high level schedule, and draw attention to areas where our
|
||||
process is different.
|
||||
|
||||
Launchpad Admin
|
||||
---------------
|
||||
|
||||
We track series (e.g. Stein) and milestones (e.g. stein-1) on Launchpad, and
|
||||
target bugs and blueprints to these. Populating these in advance is necessary.
|
||||
This needs to be done for each of the following projects:
|
||||
|
||||
* https://launchpad.net/kolla
|
||||
|
||||
* https://launchpad.net/kolla-ansible
|
||||
|
||||
At the beginning of a cycle, ensure a named series exists for the cycle in each
|
||||
project. If not, create one via the project landing page (e.g.
|
||||
https://launchpad.net/kolla) - in the "Series and milestones" section click in
|
||||
"Register a series". Once the series has been created, create the necessary
|
||||
milestones, including the final release. Series can be marked as "Active
|
||||
Development" or "Current Stable Release" as necessary.
|
||||
|
||||
Milestones
|
||||
----------
|
||||
|
||||
At each of the various release milestones, pay attention to what other projects
|
||||
are doing.
|
||||
|
||||
Feature Freeze
|
||||
--------------
|
||||
|
||||
As with projects following the common release model, Kolla uses a feature
|
||||
freeze period to allow the code to stabilise prior to release. There is no
|
||||
official feature freeze date for the cycle-trailing model, but we typically
|
||||
freeze around **three weeks** after the common feature freeze. During this
|
||||
time, no features should be merged to the master branch.
|
||||
|
||||
Before RC1
|
||||
----------
|
||||
|
||||
Prior to creating a release candidate:
|
||||
|
||||
* test the code and fix (at a minimum) all critical bugs
|
||||
|
||||
* the release notes for each project should be tidied up
|
||||
|
||||
* this command is useful to list release notes added this cycle:
|
||||
|
||||
* ``git diff --name-only origin/stable/<previous release> --
|
||||
releasenotes/``
|
||||
|
||||
* example (kolla): https://review.opendev.org/648677/
|
||||
|
||||
* example (kolla-ansible): https://review.opendev.org/648685/
|
||||
|
||||
* mark bugs on Launchpad with the correct milestone
|
||||
|
||||
* this command is useful to check for commits that fixed bugs:
|
||||
|
||||
* ``git log origin/stable/<previous release>..origin/master | grep -i
|
||||
Closes-Bug``
|
||||
|
||||
* update dependencies for source images on master to use release candidates:
|
||||
|
||||
* ``./tools/version-check.py --openstack-release $SERIES``
|
||||
|
||||
* this will only work when release candidates have been created for the
|
||||
dependent projects
|
||||
|
||||
* add ``--include-independent`` to update projects with an independent
|
||||
release cycle
|
||||
|
||||
* example (kolla): https://review.openstack.org/647819
|
||||
|
||||
* add `cycle highlights
|
||||
<https://docs.openstack.org/project-team-guide/release-management.html#cycle-highlights>`__
|
||||
when requested by the release team
|
||||
|
||||
* example (all): https://review.opendev.org/644506/
|
||||
|
||||
RC1
|
||||
---
|
||||
|
||||
RC1 is the first release candidate, and also marks the point at which the
|
||||
stable branch is cut.
|
||||
|
||||
* create RC1 by submitting patches to the releases repository
|
||||
|
||||
* example (kolla): https://review.opendev.org/650236
|
||||
|
||||
* example (kolla-ansible): https://review.opendev.org/650237
|
||||
|
||||
* create stable branches by submitting patches to the releases repository
|
||||
|
||||
* example (kolla): https://review.opendev.org/650411
|
||||
|
||||
* example (kolla-ansible): https://review.opendev.org/650412
|
||||
|
||||
After RC1
|
||||
---------
|
||||
|
||||
* approve bot-proposed patches to master and the new stable branch
|
||||
|
||||
* revert the patch to use release candidates of dependencies on the master
|
||||
branch
|
||||
|
||||
* example (kolla): https://review.openstack.org/650419
|
||||
|
||||
* switch to use the new release of RDO on the new stable branch (master uses
|
||||
the delorean development packages)
|
||||
|
||||
* example (kolla): https://review.opendev.org/651601
|
||||
|
||||
* update previous release variables on master
|
||||
|
||||
* example (kolla-ansible): https://review.opendev.org/650854
|
||||
|
||||
* search for TODOs in the codebases describing tasks to be performed during the
|
||||
next release cycle
|
||||
|
||||
* may include deprecations, code removal, etc.
|
||||
|
||||
After OpenStack Final Release
|
||||
-----------------------------
|
||||
|
||||
* update dependencies for source images on master to use final releases:
|
||||
|
||||
* ``./tools/version-check.py --openstack-release $SERIES``
|
||||
|
||||
* example (kolla): https://review.opendev.org/651605/
|
||||
|
||||
RC2+
|
||||
----
|
||||
|
||||
Further release candidates may be created on the stable branch as necessary in
|
||||
a similar manner to RC1.
|
||||
|
||||
Final Releases
|
||||
--------------
|
||||
|
||||
A release candidate may be promoted to a final release if it has no critical
|
||||
bugs against it.
|
||||
|
||||
* create final release by submitting patches to the releases repository
|
||||
|
||||
* example (kolla): TODO
|
||||
|
||||
* example (kolla-ansible): TODO
|
||||
|
||||
Stable Releases
|
||||
===============
|
||||
|
||||
Stable branch releases should be made periodically for each supported stable
|
||||
branch, no less than once every 45 days.
|
||||
|
||||
* check for new releases of dependencies
|
||||
|
||||
* ``tools/version_check.py``
|
||||
|
||||
* example (kolla): https://review.opendev.org/652674/
|
||||
|
||||
* create stable releases by submitting patches to the releases repository
|
||||
|
||||
* follow SemVer guidelines
|
||||
|
||||
* example (kolla): https://review.opendev.org/650411
|
||||
|
||||
* example (kolla-ansible): https://review.opendev.org/650412
|
||||
|
||||
* mark milestones on Launchpad as released
|
||||
|
||||
* create new milestones on Launchpad for the next stable releases
|
||||
@ -8,7 +8,7 @@ Kolla contains a suite of tests in the
|
||||
``tests`` and ``kolla/tests`` directories.
|
||||
|
||||
Any proposed code change in gerrit is automatically rejected by the OpenStack
|
||||
`Jenkins Job Builder <https://docs.openstack.org/infra/system-config/jjb.html>`__
|
||||
`Zuul CI system <https://docs.openstack.org/infra/system-config/zuulv3.html>`__
|
||||
if the change causes test failures.
|
||||
|
||||
It is recommended for developers to run the test suite before submitting patch
|
||||
@ -46,7 +46,7 @@ To run multiple tests separate items by commas:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
tox -e py27,py35,pep8
|
||||
tox -e py27,py37,pep8
|
||||
|
||||
Running a subset of tests
|
||||
-------------------------
|
||||
|
||||
@ -21,10 +21,17 @@ Welcome to Kolla's documentation!
|
||||
Kolla's mission is to provide production-ready containers and deployment tools
|
||||
for operating OpenStack clouds.
|
||||
|
||||
This documentation is for the Kolla container images. The following subprojects
|
||||
are available to help deploy Kolla:
|
||||
Related Projects
|
||||
================
|
||||
|
||||
* `kolla-ansible <https://docs.openstack.org/kolla-ansible/latest/>`_
|
||||
This documentation is for the Kolla container images.
|
||||
|
||||
`Kolla-ansible <https://docs.openstack.org/kolla-ansible/latest/>`_ is a
|
||||
subproject of Kolla that deploys the Kolla container images using Ansible.
|
||||
|
||||
`Kayobe <https://kayobe.readthedocs.io>`__ is a related unofficial project that
|
||||
uses Kolla Ansible and Bifrost to deploy an OpenStack control plane to bare
|
||||
metal.
|
||||
|
||||
Site Notes
|
||||
==========
|
||||
@ -32,8 +39,8 @@ Site Notes
|
||||
This documentation is continually updated and may not represent the state of
|
||||
the project at any specific prior release. To access documentation for a
|
||||
previous release of kolla, append the OpenStack release name to the URL. For
|
||||
example, to access Kolla documentation for pike release:
|
||||
https://docs.openstack.org/kolla/pike
|
||||
example, to access Kolla documentation for the Stein release:
|
||||
https://docs.openstack.org/kolla/stein
|
||||
|
||||
Administrator Guide
|
||||
===================
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user