From: Rex Lee <limingjiang@huawei.com>
Date: Tue, 30 Oct 2018 09:04:45 +0000 (+0000)
Subject: Merge "[docs] Add developer guidelines for contribution"
X-Git-Tag: opnfv-8.0.0~170
X-Git-Url: https://gerrit.opnfv.org/gerrit/gitweb?a=commitdiff_plain;h=a74d79472dedf193e00905840d53cdee48e74f82;p=yardstick.git

Merge "[docs] Add developer guidelines for contribution"
---

a74d79472dedf193e00905840d53cdee48e74f82
diff --cc docs/testing/developer/devguide/devguide.rst
index 447ec445c,43672cbda..4fe01c12b
--- a/docs/testing/developer/devguide/devguide.rst
+++ b/docs/testing/developer/devguide/devguide.rst
@@@ -566,58 -570,92 +570,143 @@@ The process for backporting is as follo
  A backported change needs a ``+1`` and a ``+2`` from a committer who didn’t
  propose the change (i.e. minimum 3 people involved).
  
+ Development guidelines
+ ----------------------
+ This section provides guidelines and best practices for feature development
+ and bug fixing in Yardstick.
+ 
+ In general, bug fixes should be submitted as a single patch.
+ 
+ When developing larger features, all commits on the local topic branch can be
+ submitted together, by running ``git review`` on the tip of the branch. This
+ creates a chain of related patches in gerrit.
+ 
+ Each commit should contain one logical change and the author should aim for no
+ more than 300 lines of code per commit. This helps to make the changes easier
+ to review.
+ 
+ Each feature should have the following:
+ 
+ * Feature/bug fix code
+ * Unit tests (both positive and negative)
+ * Functional tests (optional)
+ * Sample testcases (if applicable)
+ * Documentation
+ * Update to release notes
+ 
+ Coding style
+ ~~~~~~~~~~~~
+ .. _`OpenStack Style Guidelines`: https://docs.openstack.org/hacking/latest/user/hacking.html
+ .. _`OPNFV coding guidelines`: https://wiki.opnfv.org/display/DEV/Contribution+Guidelines
+ 
+ Please follow the `OpenStack Style Guidelines`_ for code contributions (the
+ section on Internationalization (i18n) Strings is not applicable).
+ 
+ When writing commit message, the `OPNFV coding guidelines`_ on git commit
+ message style should also be used.
+ 
+ Running tests
+ ~~~~~~~~~~~~~
+ Once your patch has been submitted, a number of tests will be run by Jenkins
+ CI to verify the patch. Before submitting your patch, you should run these
+ tests locally. You can do this using ``tox``, which has a number of different
+ test environments defined in ``tox.ini``.
+ Calling ``tox`` without any additional arguments runs the default set of
+ tests (unit tests, functional tests, coverage and pylint).
+ 
+ If some tests are failing, you can save time and select test environments
+ individually, by passing one or more of the following command-line options to
+ ``tox``:
+ 
+ * ``-e py27``: Unit tests using Python 2.7
+ * ``-e py3``: Unit tests using Python 3
+ * ``-e pep8``: Linter and style checks on updated files
+ * ``-e functional``: Functional tests using Python 2.7
+ * ``-e functional-py3``: Functional tests using Python 3
+ * ``-e coverage``: Code coverage checks
+ 
+ .. note:: You need to stage your changes prior to running coverage for those
+    changes to be checked.
+ 
+ In addition to the tests run by Jenkins (listed above), there are a number of
+ other test environments defined.
+ 
+ * ``-e pep8-full``: Linter and style checks are run on the whole repo (not
+   just on updated files)
+ * ``-e os-requirements``: Check that the requirements are compatible with
+   OpenStack requirements.
+ 
+ Working with tox
+ ++++++++++++++++
+ .. _virtualenv: https://virtualenv.pypa.io/en/stable/
+ 
+ ``tox`` uses `virtualenv`_ to create isolated Python environments to run the
+ tests in. The test environments are located at
+ ``.tox/<environment_name>`` e.g. ``.tox/py27``.
+ 
+ If requirements are changed, you will need to recreate the tox test
+ environment to make sure the new requirements are installed. This is done by
+ passing the additional ``-r`` command-line option to ``tox``::
+ 
+     tox -r -e ...
+ 
+ This can also be achieved by deleting the test environments manually before
+ running ``tox``::
+ 
+    rm -rf .tox/<environment_name>
+    rm -rf .tox/py27
  
 +Writing unit tests
 +~~~~~~~~~~~~~~~~~~
 +For each change submitted, a set of unit tests should be submitted, which
 +should include both positive and negative testing.
 +
 +In order to help identify which tests are needed, follow the guidelines below.
 +
 +* In general, there should be a separate test for each branching point, return
 +  value and input set.
 +* Negative tests should be written to make sure exceptions are raised and/or
 +  handled appropriately.
 +
 +The following convention should be used for naming tests::
 +
 +    test_<method_name>_<some_comment>
 +
 +The comment gives more information on the nature of the test, the side effect
 +being checked, or the parameter being modified::
 +
 +    test_my_method_runtime_error
 +    test_my_method_invalid_credentials
 +    test_my_method_param1_none
 +
 +Mocking
 ++++++++
 +The ``mock`` library is used for unit testing to stub out external libraries.
 +
 +The following conventions are used in Yardstick:
 +
 +* Use ``mock.patch.object`` instead of ``mock.patch``.
 +
 +* When naming mocked classes/functions, use ``mock_<class_and_function_name>``
 +  e.g. ``mock_subprocess_call``
 +
 +* Avoid decorating classes with mocks. Apply the mocking in ``setUp()``::
 +
 +    @mock.patch.object(ssh, 'SSH')
 +    class MyClassTestCase(unittest.TestCase):
 +
 +  should be::
 +
 +    class MyClassTestCase(unittest.TestCase):
 +        def setUp(self):
 +            self._mock_ssh = mock.patch.object(ssh, 'SSH')
 +            self.mock_ssh = self._mock_ssh.start()
 +
 +            self.addCleanup(self._stop_mocks)
 +
 +        def _stop_mocks(self):
 +            self._mock_ssh.stop()
 +
  Plugins
  -------