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 68796d79fa)

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
    <https://opendev.org/openstack/kolla-ansible/>`_. Bugs should be
    filed on `launchpad <https://bugs.launchpad.net/kolla-ansible>`_.
 
@@ -28,6 +28,10 @@ Basics
 
 #. TrivialFix tags or bugs are not required for documentation changes.
 
+#. 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.
+
 Development Environment
 =======================
 
@@ -39,11 +43,24 @@ Please use the existing sandbox repository, available at `sandbox
 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.
 
 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.

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

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
+<https://docs.openstack.org/kolla/latest/contributor/ptl-guide.html>`__.

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
+<https://docs.openstack.org/kolla/latest/contributor/release-management.html>`__.

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

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
 <https://docs.openstack.org/kolla/latest/>`_.
 
-Admin Guides
-============
+`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
+==========
+
+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