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 2019-05-21 16:26:52 +01:00
parent b55fa2f8b7
commit da16744a9a
6 changed files with 355 additions and 17 deletions

View File

@ -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

View File

@ -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

View 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

View 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

View File

@ -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
-------------------------

View File

@ -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
===================