diff --git a/doc/source/contributor/CONTRIBUTING.rst b/doc/source/contributor/CONTRIBUTING.rst
index cdbf7ea27d16b1607648e0db8be37d7a6cc16355..4b43dd8747b6b194739f3a5991dedca80cb24013 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
<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.
diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst
index b9fc723565ffb6e6dd1da2ddb802f308489e0c1d..c0cfdb8a581cd26cc0a4fa4c9ea8d98438584497 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 0000000000000000000000000000000000000000..115874f93d6fa300accfa0ac7f6d4ee724143861
--- /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
+<https://docs.openstack.org/kolla/latest/contributor/ptl-guide.html>`__.
diff --git a/doc/source/contributor/release-management.rst b/doc/source/contributor/release-management.rst
new file mode 100644
index 0000000000000000000000000000000000000000..17c82181ae04325d134fe8f3e6f40c9628bbca85
--- /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
+<https://docs.openstack.org/kolla/latest/contributor/release-management.html>`__.
diff --git a/doc/source/contributor/running-tests.rst b/doc/source/contributor/running-tests.rst
index e25cd7a0cba63bff3a6e873d9694c411906ec149..d16c779ebc434ff3268684ff63f44a203b49c051 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 <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
-------------------------
diff --git a/doc/source/index.rst b/doc/source/index.rst
index b4b8f673e8ccfbdf5f7b79d57cc6bb9e5c4d2065..d840cccbf955c9a7cee1ea99fd8a8bf4662662de 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
<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