diff --git a/doc/source/contributor/CONTRIBUTING.rst b/doc/source/contributor/CONTRIBUTING.rst index 7b6ce18f4c..d50c344620 100644 --- a/doc/source/contributor/CONTRIBUTING.rst +++ b/doc/source/contributor/CONTRIBUTING.rst @@ -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 + `_. Bugs should be filed on + `launchpad `_. -#. Please follow OpenStack `Gerrit Workflow`_ to contribute to Kolla. +#. 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 launchpad_ blueprint for any significant code change and a bug +#. 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 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 `_. + 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 +`_, +for learning, understanding and testing the `Gerrit 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 +`__ 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 +`__) 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). diff --git a/doc/source/contributor/running-tests.rst b/doc/source/contributor/running-tests.rst index e60671c9f9..2a300bb16c 100644 --- a/doc/source/contributor/running-tests.rst +++ b/doc/source/contributor/running-tests.rst @@ -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 `__ +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 `__ +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 `_. .. rubric:: Footnotes - -.. [#f1] See https://docs.openstack.org/infra/system-config/jjb.html