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
This commit is contained in:
Mark Goddard 2019-05-21 16:38:23 +01:00
parent 22a6e0216e
commit 68796d79fa
6 changed files with 75 additions and 17 deletions

View File

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

View File

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

View File

@ -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>`__.

View File

@ -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>`__.

View File

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

View File

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