How To Contribute

Basics

  1. Our source code is hosted on OpenDev Kolla Git. Bugs should be filed on launchpad.

  2. Please follow OpenStack Gerrit Workflow to contribute to Kolla.

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

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

  5. 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:

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:

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

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