[Community goal] Update the contributor guide

Co-authored-by: Radosław Piliszek <[email protected]>
Change-Id: I50e2bf6aac38624851edb15ecb108cade469ddad
Story: #2007236
Task: #38531

CONTRIBUTING.rst

@@ -0,0 +1,19 @@
+The source repository for this project can be found at:
+
+   https://opendev.org/openstack/kolla
+
+Pull requests submitted through GitHub are **not** monitored.
+
+To start contributing to OpenStack, follow the steps in the contribution guide
+to set up and use Gerrit:
+
+   https://docs.openstack.org/contributors/code-and-documentation/quick-start.html
+
+Bugs should be filed on Launchpad:
+
+   https://bugs.launchpad.net/kolla
+
+For more specific information about contributing to this repository, see the
+Kolla contributor guide:
+
+   https://docs.openstack.org/kolla/latest/contributor/contributing.html

doc/source/contributor/adding-a-new-image.rst

@@ -0,0 +1,52 @@
+==================
+Adding a new image
+==================
+
+Kolla follows `Best practices for writing Dockerfiles
+<https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/>`__
+where at all possible.
+
+We use ``jinja2`` templating syntax to help manage the volume and complexity
+that comes with maintaining multiple Dockerfiles for multiple different base
+operating systems.
+
+Images should be created under the ``docker`` directory. OpenStack services
+should inherit from the provided ``openstack-base`` image, and
+infrastructure services (for example: ``fluentd``) should inherit from
+``base``.
+
+Projects consisting of only one service should be placed in an image named the
+same as that service, for example: ``horizon``. Services that consist of
+multiple processes generally use a base image and child images, for example:
+``cinder-base``, ``cinder-api``, ``cinder-scheduler``, ``cinder-volume``,
+``cinder-backup``.
+
+Jinja2 `blocks` are employed throughout the Dockerfiles to help operators
+customise various stages of the build (refer to :ref:`Dockerfile Customisation
+<dockerfile-customisation>`)
+
+Some of these blocks are free form. However, there is a subset that should be
+common to every Dockerfile. The overall structure is as follows:
+
+.. code-block:: console
+
+   FROM {{ namespace }}/{{ image_prefix }}openstack-base:{{ tag }}
+   LABEL maintainer="{{ maintainer }}" name="{{ image_name }}" build-date="{{ build_date }}"
+
+   {% block << service >>_header %}{% endblock %}
+
+   {% import "macros.j2" as macros with context %}
+
+   << binary specific steps >>
+
+   << source specific steps >>
+
+   << common steps >>
+
+   {% block << service >>_footer %}{% endblock %}
+   {% block footer %}{% endblock %}
+
+.. note::
+
+   The generic footer block ``{% block footer %}{% endblock %}`` should **not** be
+   included in base images (for example: ``cinder-base``).

doc/source/contributor/contributing.rst

@@ -0,0 +1,125 @@
+============================
+So You Want to Contribute...
+============================
+
+For general information on contributing to OpenStack, please check out the
+`contributor guide <https://docs.openstack.org/contributors/>`_ to get started.
+It covers all the basics that are common to all OpenStack projects: the
+accounts you need, the basics of interacting with our Gerrit review system,
+how we communicate as a community, etc.
+
+Below will cover the more project specific information you need to get started
+with Kolla.
+
+Basics
+~~~~~~
+
+The source repository for this project can be found at:
+
+   https://opendev.org/openstack/kolla
+
+Communication
+~~~~~~~~~~~~~
+
+IRC Channel
+    ``#openstack-kolla`` (`channel logs`_) on Freenode
+
+Weekly Meetings
+    On Wednesdays at 15:00 UTC in the IRC channel (`meetings logs`_)
+
+Mailing list (prefix subjects with ``[kolla]``)
+    http://lists.openstack.org/pipermail/openstack-discuss/
+
+Meeting Agenda
+    https://wiki.openstack.org/wiki/Meetings/Kolla
+
+Whiteboard (etherpad)
+    Keeping track of CI gate status, release status, stable backports,
+    planning and feature development status.
+    https://etherpad.openstack.org/p/KollaWhiteBoard
+
+.. _channel logs: http://eavesdrop.openstack.org/irclogs/%23openstack-kolla/
+.. _meetings logs:  http://eavesdrop.openstack.org/meetings/kolla/
+
+Contacting the Core Team
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The list in alphabetical order (on first name):
+
++-----------------------+---------------+------------------------------------+
+| Name                  | IRC nick      | Email address                      |
++=======================+===============+====================================+
+| `Christian Berendt`_  | berendt       | [email protected]     |
++-----------------------+---------------+------------------------------------+
+| `Dincer Celik`_       | osmanlicilegi | [email protected]              |
++-----------------------+---------------+------------------------------------+
+| `Eduardo Gonzalez`_   | egonzalez     | [email protected]                 |
++-----------------------+---------------+------------------------------------+
+| `Jeffrey Zhang`_      | Jeffrey4l     | [email protected]          |
++-----------------------+---------------+------------------------------------+
+| `Marcin Juszkiewicz`_ | hrw           | [email protected]      |
++-----------------------+---------------+------------------------------------+
+| `Mark Goddard`_       | mgoddard      | [email protected]                  |
++-----------------------+---------------+------------------------------------+
+| `Michał Nasiadka`_    | mnasiadka     | [email protected]                |
++-----------------------+---------------+------------------------------------+
+| `Radosław Piliszek`_  | yoctozepto    | [email protected]        |
++-----------------------+---------------+------------------------------------+
+| `Surya Prakash`_      | spsurya       | [email protected]       |
++-----------------------+---------------+------------------------------------+
+| `Cao Yuan`_           | caoyuan       | [email protected]               |
++-----------------------+---------------+------------------------------------+
+
+.. _Christian Berendt: https://launchpad.net/~berendt
+.. _Dincer Celik: https://launchpad.net/~osmanlicilegi
+.. _Eduardo Gonzalez: https://launchpad.net/~egonzalez90
+.. _Jeffrey Zhang: https://launchpad.net/~jeffrey4l
+.. _Marcin Juszkiewicz: https://launchpad.net/~hrw
+.. _Mark Goddard: https://launchpad.net/~mgoddard
+.. _Michał Nasiadka: https://launchpad.net/~mnasiadka
+.. _Radosław Piliszek: https://launchpad.net/~yoctozepto
+.. _Surya Prakash: https://launchpad.net/~confisurya
+.. _Cao Yuan: https://launchpad.net/~caoi-yuan
+
+The current effective list is also available from Gerrit:
+https://review.opendev.org/#/admin/groups/460,members
+
+New Feature Planning
+~~~~~~~~~~~~~~~~~~~~
+
+New features are discussed via IRC or mailing list (with [kolla] prefix).
+Kolla project keeps blueprints in `Launchpad <https://blueprints.launchpad.net/kolla>`__.
+Specs are welcome but not strictly required.
+
+Task Tracking
+~~~~~~~~~~~~~
+
+Kolla project tracks tasks in `Launchpad <https://bugs.launchpad.net/kolla>`__.
+Note this is the same place as for bugs.
+
+If you're looking for some smaller, easier work item to pick up and get started
+on, search for the 'low-hanging-fruit' tag.
+
+A more lightweight task tracking is done via etherpad - `Whiteboard <https://etherpad.openstack.org/p/KollaWhiteBoard>`__.
+
+Reporting a Bug
+~~~~~~~~~~~~~~~
+
+You found an issue and want to make sure we are aware of it? You can do so
+on `Launchpad <https://bugs.launchpad.net/kolla>`__.
+Note this is the same place as for tasks.
+
+Getting Your Patch Merged
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Most changes proposed to Kolla require two +2 votes from core reviewers before
++W. A release note is required on most changes as well. Release notes policy
+is described in :ref:`its own section <release-notes>`.
+
+Significant changes should have documentation and testing provided with them.
+
+Project Team Lead Duties
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+All common PTL duties are enumerated in the `PTL guide <https://docs.openstack.org/project-team-guide/ptl.html>`_.
+Kolla-specific PTL duties are listed in `Kolla PTL guide <https://docs.openstack.org/kolla/latest/contributor/ptl-guide.html>`_.

doc/source/contributor/index.rst

@@ -12,7 +12,9 @@ We welcome everyone to join our project!
 .. toctree::
    :maxdepth: 2
 
-   CONTRIBUTING
+   contributing
+   adding-a-new-image
+   release-notes
    running-tests
    bug-triage
    ptl-guide

doc/source/contributor/release-notes.rst

@@ -0,0 +1,45 @@
+.. _release-notes:
+
+=============
+Release notes
+=============
+
+Kolla uses the following release notes sections:
+
+- ``features`` --- for new features or functionality; these should ideally
+  refer to the blueprint being implemented;
+- ``fixes`` --- for fixes closing bugs; these must refer to the bug being
+  closed;
+- ``upgrade`` --- for notes relevant when upgrading from previous version;
+  these should ideally be added only between major versions; required when
+  the proposed change affects behaviour in a non-backwards compatible way or
+  generally changes something impactful;
+- ``deprecations`` --- to track deprecated features; relevant changes may
+  consist of only the commit message and the release note;
+- ``prelude`` --- filled in by the PTL before each release or RC.
+
+Other release note types may be applied per common sense.
+Each change should include a release note unless being a ``TrivialFix``
+change or affecting only docs or CI. Such changes should `not` include
+a release note to avoid confusion.
+Remember release notes are mostly for end users which, in case of Kolla,
+are OpenStack administrators/operators.
+In case of doubt, the core team will let you know what is required.
+
+To add a release note, run the following command:
+
+.. code-block:: console
+
+   tox -e venv -- reno new <summary-line-with-dashes>
+
+All release notes can be inspected by browsing ``releasenotes/notes``
+directory.
+
+To generate release notes in HTML format in ``releasenotes/build``, run:
+
+.. code-block:: console
+
+   tox -e releasenotes
+
+Note this requires the release note to be tracked by ``git`` so you
+have to at least add it to the ``git``'s staging area.