Upgrade the rst convention of the Contributor Guide
We upgrade the rst convention by following Documentation Contributor Guide[1]. [1] https://docs.openstack.org/doc-contrib-guide/ Change-Id: Id2b804b3743efabaadfd2f7ba2c4ed4bc3b7289e Partially-Implements: blueprint optimize-the-documentation-format
This commit is contained in:
chenxing
Chason Chan
parent
323ee0b09c
commit
6fb2f385dc
@ -7,31 +7,30 @@ How To Contribute
|
||||
Basics
|
||||
======
|
||||
|
||||
#. Our source code is hosted on `OpenStack Kolla Git`_. Bugs should be filed on
|
||||
launchpad_.
|
||||
#. Our source code is hosted on `OpenStack Kolla Git
|
||||
<https://git.openstack.org/cgit/openstack/kolla/>`_. Bugs should be filed on
|
||||
`launchpad <https://bugs.launchpad.net/kolla>`_.
|
||||
|
||||
#. Please follow OpenStack `Gerrit Workflow`_ to contribute to Kolla.
|
||||
#. Please follow OpenStack `Gerrit Workflow
|
||||
<https://docs.openstack.org/infra/manual/developers.html#development-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 launchpad_ blueprint for any significant code change and a bug
|
||||
#. Please file a `blueprint of kolla <https://blueprints.launchpad.net/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 here_. For simple changes, contributors may optionally
|
||||
add the text "TrivialFix" to the commit message footer to indicate to
|
||||
reviewers a bug is not required.
|
||||
the `commit message <https://wiki.openstack.org/wiki/GitCommitMessages>`_.
|
||||
For simple changes, contributors may optionally add the text "TrivialFix" to
|
||||
the commit message footer to indicate to reviewers a bug is not required.
|
||||
|
||||
.. _OpenStack Kolla Git: https://git.openstack.org/cgit/openstack/kolla/
|
||||
.. _launchpad: https://bugs.launchpad.net/kolla
|
||||
.. _here: https://wiki.openstack.org/wiki/GitCommitMessages
|
||||
|
||||
Please use the existing sandbox repository, available at
|
||||
https://git.openstack.org/cgit/openstack-dev/sandbox, for learning, understanding
|
||||
and testing the `Gerrit Workflow`_.
|
||||
|
||||
.. _Gerrit Workflow: https://docs.openstack.org/infra/manual/developers.html#development-workflow
|
||||
Please use the existing sandbox repository, available at `sandbox
|
||||
<https://git.openstack.org/cgit/openstack-dev/sandbox>`_,
|
||||
for learning, understanding and testing the `Gerrit Workflow
|
||||
<https://docs.openstack.org/infra/manual/developers.html#development-workflow>`_.
|
||||
|
||||
Adding a new service
|
||||
====================
|
||||
@ -42,8 +41,9 @@ guidelines aim to help make adding a new service to Kolla a smooth experience.
|
||||
|
||||
The image
|
||||
---------
|
||||
Kolla follows Docker best practices
|
||||
(https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/)
|
||||
|
||||
Kolla follows `Best practices for writing Dockerfiles
|
||||
<https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/>`__
|
||||
when designing and implementing services where at all possible.
|
||||
|
||||
We use ``jinja2`` templating syntax to help manage the volume and complexity
|
||||
@ -52,37 +52,40 @@ 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 (e.g. mongodb) should inherit from ``base``.
|
||||
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, e.g. ``horizon``. Services that consist of multiple
|
||||
processes generally use a base image and child images, e.g. ``glance-base``,
|
||||
``glance-api``, and ``glance-registry``.
|
||||
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
|
||||
https://docs.openstack.org/kolla/latest/image-building.html#dockerfile-customisation)
|
||||
customise various stages of the build (refer to `Dockerfile Customisation
|
||||
<https://docs.openstack.org/kolla/latest/admin/image-building.html#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::
|
||||
is as follows:
|
||||
|
||||
FROM {{ namespace }}/{{ image_prefix }}openstack-base:{{ tag }}
|
||||
LABEL maintainer="{{ maintainer }}" name="{{ image_name }}" build-date="{{ build_date }}"
|
||||
.. code-block: none
|
||||
|
||||
{% block << service >>_header %}{% endblock %}
|
||||
FROM {{ namespace }}/{{ image_prefix }}openstack-base:{{ tag }}
|
||||
LABEL maintainer="{{ maintainer }}" name="{{ image_name }}" build-date="{{ build_date }}"
|
||||
|
||||
{% import "macros.j2" as macros with context %}
|
||||
{% block << service >>_header %}{% endblock %}
|
||||
|
||||
<< binary specific steps >>
|
||||
{% import "macros.j2" as macros with context %}
|
||||
|
||||
<< source specific steps >>
|
||||
<< binary specific steps >>
|
||||
|
||||
<< common steps >>
|
||||
<< source specific steps >>
|
||||
|
||||
{% block << service >>_footer %}{% endblock %}
|
||||
{% block footer %}{% endblock %}
|
||||
<< common steps >>
|
||||
|
||||
.. NOTE::
|
||||
The generic footer block ``{% block footer %}{% endblock %}`` should not be
|
||||
included in base images (e.g. glance-base).
|
||||
{% 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).
|
||||
|
||||
@ -8,7 +8,8 @@ Kolla contains a suite of tests in the
|
||||
``tests`` and ``kolla/tests`` directories.
|
||||
|
||||
Any proposed code change in gerrit is automatically rejected by the OpenStack
|
||||
Jenkins server [#f1]_ if the change causes test failures.
|
||||
`Jenkins Job Builder <https://docs.openstack.org/infra/system-config/jjb.html>`__
|
||||
if the change causes test failures.
|
||||
|
||||
It is recommended for developers to run the test suite before submitting patch
|
||||
for review. This allows to catch errors as early as possible.
|
||||
@ -23,65 +24,78 @@ so the only package you install is ``tox`` itself:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ pip install tox
|
||||
pip install tox
|
||||
|
||||
See `the unit testing section of the Testing wiki page`_ for more information.
|
||||
.. end
|
||||
|
||||
See the `unit testing <https://wiki.openstack.org/wiki/Testing#Unit_Tests>`__
|
||||
section of the Testing wiki page for more information.
|
||||
Following are some simple examples.
|
||||
|
||||
To run the Python 2.7 tests:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ tox -e py27
|
||||
tox -e py27
|
||||
|
||||
.. end
|
||||
|
||||
To run the style tests:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ tox -e pep8
|
||||
tox -e pep8
|
||||
|
||||
.. end
|
||||
|
||||
To run multiple tests separate items by commas:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ tox -e py27,py35,pep8
|
||||
tox -e py27,py35,pep8
|
||||
|
||||
.. _the unit testing section of the Testing wiki page: https://wiki.openstack.org/wiki/Testing#Unit_Tests
|
||||
.. end
|
||||
|
||||
Running a subset of tests
|
||||
-------------------------
|
||||
|
||||
Instead of running all tests, you can specify an individual directory, file,
|
||||
class or method that contains test code, i.e. filter full names of tests by a
|
||||
string.
|
||||
class or method that contains test code, for example, filter full names of
|
||||
tests by a string.
|
||||
|
||||
To run the tests located only in the ``kolla/tests``
|
||||
directory use:
|
||||
To run the tests located only in the ``kolla/tests`` directory:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ tox -e py27 kolla.tests
|
||||
tox -e py27 kolla.tests
|
||||
|
||||
.. end
|
||||
|
||||
To run the tests of a specific file say ``kolla/tests/test_set_config.py``:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ tox -e py27 test_set_config
|
||||
tox -e py27 test_set_config
|
||||
|
||||
.. end
|
||||
|
||||
To run the tests in the ``ConfigFileTest`` class in
|
||||
the ``kolla/tests/test_set_config.py`` file:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ tox -e py27 test_set_config.ConfigFileTest
|
||||
tox -e py27 test_set_config.ConfigFileTest
|
||||
|
||||
.. end
|
||||
|
||||
To run the ``ConfigFileTest.test_delete_path_not_exists`` test method in
|
||||
the ``kolla/tests/test_set_config.py`` file:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ tox -e py27 test_set_config.ConfigFileTest.test_delete_path_not_exists
|
||||
tox -e py27 test_set_config.ConfigFileTest.test_delete_path_not_exists
|
||||
|
||||
.. end
|
||||
|
||||
Coverage Report Generation
|
||||
--------------------------
|
||||
@ -90,7 +104,9 @@ In order to get coverage report for Kolla, run the below command.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ tox -e cover
|
||||
tox -e cover
|
||||
|
||||
.. end
|
||||
|
||||
Debugging unit tests
|
||||
--------------------
|
||||
@ -102,15 +118,19 @@ a breaking point to the code:
|
||||
|
||||
import pdb; pdb.set_trace()
|
||||
|
||||
Then run ``tox`` with the debug environment as one of the following::
|
||||
..end
|
||||
|
||||
tox -e debug
|
||||
tox -e debug test_file_name.TestClass.test_name
|
||||
Then run :command:`tox` with the debug environment as one of the following:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
tox -e debug
|
||||
tox -e debug test_file_name.TestClass.test_name
|
||||
|
||||
.. end
|
||||
|
||||
For more information see the `oslotest documentation
|
||||
<https://docs.openstack.org/oslotest/latest/user/features.html#debugging-with-oslo-debug-helper>`_.
|
||||
|
||||
|
||||
.. rubric:: Footnotes
|
||||
|
||||
.. [#f1] See https://docs.openstack.org/infra/system-config/jjb.html
|
||||
|
||||
Loading…
Reference in New Issue
Block a user