From f3f471b41e6702d30ff45b4fb25b8b84bb030b52 Mon Sep 17 00:00:00 2001 From: Michal Nasiadka Date: Fri, 14 Feb 2020 11:03:02 +0100 Subject: [PATCH] [Community goal] Update the contributor guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Radosław Piliszek Change-Id: I50e2bf6aac38624851edb15ecb108cade469ddad Story: #2007236 Task: #38531 --- CONTRIBUTING.rst | 19 +++ doc/source/contributor/CONTRIBUTING.rst | 136 ------------------ doc/source/contributor/adding-a-new-image.rst | 52 +++++++ doc/source/contributor/contributing.rst | 125 ++++++++++++++++ doc/source/contributor/index.rst | 4 +- doc/source/contributor/release-notes.rst | 45 ++++++ 6 files changed, 244 insertions(+), 137 deletions(-) create mode 100644 CONTRIBUTING.rst delete mode 100644 doc/source/contributor/CONTRIBUTING.rst create mode 100644 doc/source/contributor/adding-a-new-image.rst create mode 100644 doc/source/contributor/contributing.rst create mode 100644 doc/source/contributor/release-notes.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 0000000000..2c4d6c5022 --- /dev/null +++ b/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 diff --git a/doc/source/contributor/CONTRIBUTING.rst b/doc/source/contributor/CONTRIBUTING.rst deleted file mode 100644 index b598178bc8..0000000000 --- a/doc/source/contributor/CONTRIBUTING.rst +++ /dev/null @@ -1,136 +0,0 @@ -================= -How To Contribute -================= - -Basics -====== - -#. Our source code is hosted on `OpenDev Kolla Git - `_. Bugs should be filed on - `launchpad `_. - -#. Please follow OpenStack `Gerrit Workflow - `__ - to contribute to Kolla. - -#. Note the branch you're proposing changes to. ``master`` is the current focus - of development. Kolla project has a strict policy of only allowing backports - in ``stable/branch``, unless when not applicable. A bug in a - ``stable/branch`` will first have to be fixed in ``master``. - -#. Please file a `blueprint of kolla `__ - for any significant code change and a bug - for any significant bug fix. See how to reference a bug or a blueprint in - the `commit message `_. - For simple changes, contributors may optionally add the text "TrivialFix" to - the commit message footer to indicate to reviewers a bug is not required. - -#. We use a `whiteboard `__ - to keep track of CI gate status, release status, stable backports, planning - and feature development status. - -Please use the existing sandbox repository, available at `sandbox -`_, -for learning, understanding and testing the `Gerrit Workflow -`_. - -Adding a release note -===================== - -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 - -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. - -Adding a new service -==================== - -Kolla aims to both containerise and deploy all services within the OpenStack -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. - -The image ---------- - -Kolla follows `Best practices for writing Dockerfiles -`__ -when designing and implementing services 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, while supporting and -infrastructure services (for example, mongodb) should inherit from ``base``. - -Services 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, -``glance-base``, ``glance-api``, and ``glance-registry``. - -Jinja2 'blocks' are employed throughout the Dockerfile's to help operators -customise various stages of the build (refer to :ref:`Dockerfile Customisation -`) - -Some of these blocks are free form however, there are a subset that should be -common to every Dockerfile. The overall structure for a multi container service -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, glance-base). diff --git a/doc/source/contributor/adding-a-new-image.rst b/doc/source/contributor/adding-a-new-image.rst new file mode 100644 index 0000000000..db3f19b503 --- /dev/null +++ b/doc/source/contributor/adding-a-new-image.rst @@ -0,0 +1,52 @@ +================== +Adding a new image +================== + +Kolla follows `Best practices for writing Dockerfiles +`__ +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 +`) + +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``). diff --git a/doc/source/contributor/contributing.rst b/doc/source/contributor/contributing.rst new file mode 100644 index 0000000000..264e1b86e1 --- /dev/null +++ b/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 `_ 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 | berendt@betacloud-solutions.de | ++-----------------------+---------------+------------------------------------+ +| `Dincer Celik`_ | osmanlicilegi | hello@dincercelik.com | ++-----------------------+---------------+------------------------------------+ +| `Eduardo Gonzalez`_ | egonzalez | dabarren@gmail.com | ++-----------------------+---------------+------------------------------------+ +| `Jeffrey Zhang`_ | Jeffrey4l | jeffrey.zhang@99cloud.net | ++-----------------------+---------------+------------------------------------+ +| `Marcin Juszkiewicz`_ | hrw | marcin.juszkiewicz@linaro.org | ++-----------------------+---------------+------------------------------------+ +| `Mark Goddard`_ | mgoddard | mark@stackhpc.com | ++-----------------------+---------------+------------------------------------+ +| `Michał Nasiadka`_ | mnasiadka | mnasiadka@gmail.com | ++-----------------------+---------------+------------------------------------+ +| `Radosław Piliszek`_ | yoctozepto | radoslaw.piliszek@gmail.com | ++-----------------------+---------------+------------------------------------+ +| `Surya Prakash`_ | spsurya | singh.surya64mnnit@gmail.com | ++-----------------------+---------------+------------------------------------+ +| `Cao Yuan`_ | caoyuan | cao.yuan@99cloud.net | ++-----------------------+---------------+------------------------------------+ + +.. _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 `__. +Specs are welcome but not strictly required. + +Task Tracking +~~~~~~~~~~~~~ + +Kolla project tracks tasks in `Launchpad `__. +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 `__. + +Reporting a Bug +~~~~~~~~~~~~~~~ + +You found an issue and want to make sure we are aware of it? You can do so +on `Launchpad `__. +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 `. + +Significant changes should have documentation and testing provided with them. + +Project Team Lead Duties +~~~~~~~~~~~~~~~~~~~~~~~~ + +All common PTL duties are enumerated in the `PTL guide `_. +Kolla-specific PTL duties are listed in `Kolla PTL guide `_. diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 40c5b0d190..6e49472375 100644 --- a/doc/source/contributor/index.rst +++ b/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 diff --git a/doc/source/contributor/release-notes.rst b/doc/source/contributor/release-notes.rst new file mode 100644 index 0000000000..854fc88fc1 --- /dev/null +++ b/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 + +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.