diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 0000000000..fb329f3b0c --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,19 @@ +The source repository for this project can be found at: + + https://opendev.org/openstack/kolla-ansible + +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-ansible + +For more specific information about contributing to this repository, see the +Kolla Ansible contributor guide: + + https://docs.openstack.org/kolla-ansible/latest/contributor/contributing.html diff --git a/doc/source/contributor/CONTRIBUTING.rst b/doc/source/contributor/CONTRIBUTING.rst deleted file mode 100644 index 0638c70937..0000000000 --- a/doc/source/contributor/CONTRIBUTING.rst +++ /dev/null @@ -1,182 +0,0 @@ -.. _CONTRIBUTING: - -================= -How To Contribute -================= - -Basics -====== - -#. Our source code is hosted on `OpenDev Kolla-Ansible Git - `_. Bugs should be - filed on `launchpad `_. - -#. Please follow OpenStack `Gerrit Workflow - `__ - to contribute to Kolla-ansible. - -#. 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-ansible `__ - for any significant code change and a bug for any significant bug fix, - or add a ``TrivialFix`` tag to commit message for simple changes. - See how to reference a bug or a blueprint in the `commit message - `_. - -#. TrivialFix tags or bugs are not required for documentation changes. - -#. We use a `whiteboard `__ - to keep track of CI gate status, release status, stable backports, planning - and feature development status. - -Development Environment -======================= - -Please follow our :doc:`/user/quickstart` to deploy your environment and test -your changes. - -Please use the existing sandbox repository, available at `sandbox -`_, for learning, understanding -and testing the `Gerrit Workflow -`_. - -Adding a release note -===================== - -Kolla Ansible (just like 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. - -When adding a role for a new service in Ansible, there are couple of patterns -that Kolla uses throughout that should be followed. - -* The sample inventories - - Entries should be added for the service in each of - ``ansible/inventory/multinode`` and ``ansible/inventory/all-in-one``. - -* The playbook - - The main playbook that ties all roles together is in ``ansible/site.yml``, - this should be updated with appropriate roles, tags, and conditions. Ensure - also that supporting hosts such as haproxy are updated when necessary. - -* The common role - - A ``common`` role exists which sets up logging, ``kolla-toolbox`` and other - supporting components. This should be included in all services within - ``meta/main.yml`` of your role. - -* Common tasks - - 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. - - - ``pull.yml`` : Used to pre fetch the image into the Docker image cache - on hosts, to speed up initial deploys. - - - ``upgrade.yml`` : Used for upgrading the service in a rolling fashion. May - include service specific setup and steps as not all services can be - upgraded in the same way. - -* Logrotation - - - For OpenStack services there should be a ``cron-logrotate-PROJECT.conf.j2`` - template file in ``ansible/roles/common/templates`` with the following - content: - - .. path ansible/roles/common/templates/cron-logrotate-PROJECT.conf.j2 - .. code-block:: console - - "/var/log/kolla/PROJECT/*.log" - { - } - - - For OpenStack services there should be an entry in the ``services`` list - in the ``cron.json.j2`` template file in ``ansible/roles/common/templates``. - -* Log delivery - - - For OpenStack services the service should add a new ``rewriterule`` in the - ``match`` element in the ``01-rewrite.conf.j2`` template file in - ``ansible/roles/common/templates/conf/filter`` to deliver log messages to - Elasticsearch. - -* Documentation - - - For OpenStack services there should be an entry in the list - ``OpenStack services`` in the ``README.rst`` file. - - - For infrastructure services there should be an entry in the list - ``Infrastructure components`` in the ``README.rst`` file. - -* Syntax - - - All YAML data files should start with three dashes (``---``). - -Other than the above, most service roles abide by the following pattern: - -- ``Register``: Involves registering the service with Keystone, creating - endpoints, roles, users, etc. - -- ``Config``: Distributes the config files to the nodes to be pulled into - the container on startup. - -- ``Bootstrap``: Creating the database (but not tables), database user for - the service, permissions, etc. - -- ``Bootstrap Service``: Starts a one shot container on the host to create - the database tables, and other initial run time config. - -Ansible handlers are used to create or restart containers when necessary. diff --git a/doc/source/contributor/adding-a-new-service.rst b/doc/source/contributor/adding-a-new-service.rst new file mode 100644 index 0000000000..6f6a64a0eb --- /dev/null +++ b/doc/source/contributor/adding-a-new-service.rst @@ -0,0 +1,91 @@ +==================== +Adding a new service +==================== + +When adding a role for a new service in Ansible, there are couple of patterns +which Kolla uses throughout and which should be followed. + +* The sample inventories + + Entries should be added for the service in each of + ``ansible/inventory/multinode`` and ``ansible/inventory/all-in-one``. + +* The playbook + + The main playbook that ties all roles together is in ``ansible/site.yml``, + this should be updated with appropriate roles, tags, and conditions. Ensure + also that supporting hosts such as haproxy are updated when necessary. + +* The common role + + A ``common`` role exists which sets up logging, ``kolla-toolbox`` and other + supporting components. This should be included in all services within + ``meta/main.yml`` of your role. + +* Common tasks + + 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. + + - ``pull.yml`` : Used to pre fetch the image into the Docker image cache + on hosts, to speed up initial deploys. + + - ``upgrade.yml`` : Used for upgrading the service in a rolling fashion. May + include service specific setup and steps as not all services can be + upgraded in the same way. + +* Log rotation + + - For OpenStack services there should be a ``cron-logrotate-PROJECT.conf.j2`` + template file in ``ansible/roles/common/templates`` with the following + content: + + .. path ansible/roles/common/templates/cron-logrotate-PROJECT.conf.j2 + .. code-block:: console + + "/var/log/kolla/PROJECT/*.log" + { + } + + - For OpenStack services there should be an entry in the ``services`` list + in the ``cron.json.j2`` template file in ``ansible/roles/common/templates``. + +* Log delivery + + - For OpenStack services the service should add a new ``rewriterule`` in the + ``match`` element in the ``01-rewrite.conf.j2`` template file in + ``ansible/roles/common/templates/conf/filter`` to deliver log messages to + Elasticsearch. + +* Documentation + + - For OpenStack services there should be an entry in the list + ``OpenStack services`` in the ``README.rst`` file. + + - For infrastructure services there should be an entry in the list + ``Infrastructure components`` in the ``README.rst`` file. + +* Syntax + + - All YAML data files should start with three dashes (``---``). + +Other than the above, most service roles abide by the following pattern: + +- ``Register``: Involves registering the service with Keystone, creating + endpoints, roles, users, etc. + +- ``Config``: Distributes the config files to the nodes to be pulled into + the container on startup. + +- ``Bootstrap``: Creating the database (but not tables), database user for + the service, permissions, etc. + +- ``Bootstrap Service``: Starts a one shot container on the host to create + the database tables, and other initial run time config. + +Ansible handlers are used to create or restart containers when necessary. diff --git a/doc/source/contributor/contributing.rst b/doc/source/contributor/contributing.rst new file mode 100644 index 0000000000..c4ede81de0 --- /dev/null +++ b/doc/source/contributor/contributing.rst @@ -0,0 +1,130 @@ +============================ +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 Ansible. + +Basics +~~~~~~ + +The source repository for this project can be found at: + + https://opendev.org/openstack/kolla-ansible + +Communication +~~~~~~~~~~~~~ + +Kolla Ansible shares communication channels with Kolla. + +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 | ++=======================+===============+====================================+ +| `Chason Chan`_ | chason | chason.chan@foxmail.com | ++-----------------------+---------------+------------------------------------+ +| `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 | ++-----------------------+---------------+------------------------------------+ + +.. _Chason Chan: https://launchpad.net/~chen-xing +.. _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/1637,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 Ansible 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-Ansible-specific PTL duties are listed in `Kolla Ansible PTL guide `_. diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index c0cfdb8a58..9681dc966a 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: 1 - CONTRIBUTING + contributing + adding-a-new-service + release-notes vagrant-dev-env running-tests kolla-for-openstack-development diff --git a/doc/source/contributor/release-notes.rst b/doc/source/contributor/release-notes.rst new file mode 100644 index 0000000000..739d3a0b56 --- /dev/null +++ b/doc/source/contributor/release-notes.rst @@ -0,0 +1,45 @@ +.. _release-notes: + +============= +Release notes +============= + +Kolla Ansible (just like 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.