diff options
| -rw-r--r-- | doc/source/contributor/CONTRIBUTING.rst | 21 | ||||
| -rw-r--r-- | doc/source/contributor/index.rst | 18 | ||||
| -rw-r--r-- | doc/source/contributor/ptl-guide.rst | 113 | ||||
| -rw-r--r-- | doc/source/contributor/release-management.rst | 199 | ||||
| -rw-r--r-- | doc/source/contributor/running-tests.rst | 4 | ||||
| -rw-r--r-- | doc/source/index.rst | 17 |
6 files changed, 355 insertions, 17 deletions
diff --git a/doc/source/contributor/CONTRIBUTING.rst b/doc/source/contributor/CONTRIBUTING.rst index ac0871935..3d86d1c06 100644 --- a/doc/source/contributor/CONTRIBUTING.rst +++ b/doc/source/contributor/CONTRIBUTING.rst @@ -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 diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 13430a481..44766f0f6 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -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 diff --git a/doc/source/contributor/ptl-guide.rst b/doc/source/contributor/ptl-guide.rst new file mode 100644 index 000000000..5f13a1a3f --- /dev/null +++ b/doc/source/contributor/ptl-guide.rst @@ -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 diff --git a/doc/source/contributor/release-management.rst b/doc/source/contributor/release-management.rst new file mode 100644 index 000000000..f32e9f0f8 --- /dev/null +++ b/doc/source/contributor/release-management.rst @@ -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 diff --git a/doc/source/contributor/running-tests.rst b/doc/source/contributor/running-tests.rst index cb3cc4bdf..ebd82007c 100644 --- a/doc/source/contributor/running-tests.rst +++ b/doc/source/contributor/running-tests.rst @@ -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 ------------------------- diff --git a/doc/source/index.rst b/doc/source/index.rst index 8556819a0..929471af8 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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 =================== |