From ea630d96ea12dd08d7c2d2de9c18a6bfb873b1eb Mon Sep 17 00:00:00 2001 From: Mark Goddard Date: Tue, 21 May 2019 16:38:23 +0100 Subject: [PATCH] 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: If2f3b7c18de2e6c8d9bac131a16c28c2eeb348f2 (cherry picked from commit 68796d79fa52e1fadb35e987a80b263c6ff3a5dd) --- doc/source/contributor/CONTRIBUTING.rst | 26 +++++++++++++-- doc/source/contributor/index.rst | 16 +++++++-- doc/source/contributor/ptl-guide.rst | 6 ++++ doc/source/contributor/release-management.rst | 7 ++++ doc/source/contributor/running-tests.rst | 4 +-- doc/source/index.rst | 33 ++++++++++++++----- 6 files changed, 75 insertions(+), 17 deletions(-) create mode 100644 doc/source/contributor/ptl-guide.rst create mode 100644 doc/source/contributor/release-management.rst diff --git a/doc/source/contributor/CONTRIBUTING.rst b/doc/source/contributor/CONTRIBUTING.rst index cdbf7ea27d..4b43dd8747 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-Ansible Git +#. Our source code is hosted on `OpenDev Kolla-Ansible Git `_. Bugs should be filed on `launchpad `_. @@ -28,6 +28,10 @@ Basics #. TrivialFix tags or bugs are not required for documentation changes. +#. We use a `whiteboard `__ + to keep track of CI gate status, release status, stable backports, planning + and feature development status. + Development Environment ======================= @@ -39,11 +43,24 @@ Please use the existing sandbox repository, available at `sandbox and testing the `Gerrit 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 + +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. When adding a role for a new service in Ansible, there are couple of patterns @@ -70,6 +87,9 @@ that Kolla uses throughout that should be followed. All services should include the following tasks: + - ``deploy.yml`` : Used to bootstrap, configure and deploy containers + for the service. + - ``reconfigure.yml`` : Used to push new configuration files to the host and restart the service. @@ -129,4 +149,4 @@ Other than the above, most service roles abide by the following pattern: - ``Bootstrap Service``: Starts a one shot container on the host to create the database tables, and other initial run time config. -- ``Start``: Start the service(s). +Ansible handlers are used to create or restart containers when necessary. diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index b9fc723565..c0cfdb8a58 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -1,11 +1,21 @@ -Developer Docs -============== +================= +Contributor Guide +================= + +This guide is for contributors of the Kolla Ansible 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. + +We welcome everyone to join our project! .. toctree:: :maxdepth: 1 CONTRIBUTING - kolla-for-openstack-development vagrant-dev-env running-tests + kolla-for-openstack-development 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 0000000000..115874f93d --- /dev/null +++ b/doc/source/contributor/ptl-guide.rst @@ -0,0 +1,6 @@ +========= +PTL Guide +========= + +The Kolla PTL is also PTL for Kolla Ansible. See the `Kolla PTL guide +`__. diff --git a/doc/source/contributor/release-management.rst b/doc/source/contributor/release-management.rst new file mode 100644 index 0000000000..17c82181ae --- /dev/null +++ b/doc/source/contributor/release-management.rst @@ -0,0 +1,7 @@ +================== +Release Management +================== + +Release management for Kolla Ansible is very much linked to that of Kolla. See +`Kolla release management +`__. diff --git a/doc/source/contributor/running-tests.rst b/doc/source/contributor/running-tests.rst index e25cd7a0cb..d16c779ebc 100644 --- a/doc/source/contributor/running-tests.rst +++ b/doc/source/contributor/running-tests.rst @@ -7,7 +7,7 @@ Running tests Kolla-ansible contains a suit of tests in the ``tests`` directory. Any proposed code change in gerrit is automatically rejected by the -`OpenStack Jenkins server `__ +`Zuul CI system `__ if the change causes test failures. It is recommended for developers to run the test suite before submitting patch @@ -44,7 +44,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 b4b8f673e8..d840cccbf9 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -18,9 +18,6 @@ Welcome to Kolla-Ansible's documentation! ========================================= -Kolla's Mission -=============== - Kolla's mission is to provide production-ready containers and deployment tools for operating OpenStack clouds. @@ -29,20 +26,38 @@ customization. This permits operators with minimal experience to deploy OpenStack quickly and as experience grows modify the OpenStack configuration to suit the operator's exact requirements. +Related Projects +================ + +This documentation is for Kolla Ansible. + For information on building container images for use with Kolla-Ansible, please refer to the `Kolla image documentation `_. -Admin Guides -============ +`Kayobe `__ is a related unofficial project that +uses Kolla Ansible and Bifrost to deploy an OpenStack control plane to bare +metal. + +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 Ansible documentation for the Stein release: +https://docs.openstack.org/kolla-ansible/stein + +Administrator Guide +=================== .. toctree:: :maxdepth: 2 admin/index -User Guides -=========== +User Guide +========== .. toctree:: :maxdepth: 2 @@ -57,8 +72,8 @@ Reference reference/index -Developer Docs -============== +Contributor Guide +================= .. toctree:: :maxdepth: 2