For all the code in Sahara we have a rule - it should pass PEP 8.
To check your code against PEP 8 run:
$ tox -e pep8
Note
For more details on coding guidelines see file HACKING.rst in the root of Sahara repo.
We never modify upstream files in Sahara. Any changes in upstream files should be made in the upstream project and then merged back in to Sahara. This includes whitespace changes, comments, and typos. Any change requests containing upstream file modifications are almost certain to receive lots of negative reviews. Be warned.
Examples of upstream files are default xml configuration files used to configure Hadoop, or code imported from the OpenStack Oslo project. The xml files will usually be found in resource directories with an accompanying README file that identifies where the files came from. For example:
$ pwd
/home/me/sahara/sahara/plugins/vanilla/v2_3_0/resources
$ ls
core-default.xml hdfs-default.xml oozie-default.xml README.rst
create_oozie_db.sql mapred-default.xml post_conf.template yarn-default.xml
Sahara has a suite of tests that are run on all submitted code, and it is recommended that developers execute the tests themselves to catch regressions early. Developers are also expected to keep the test suite up-to-date with any submitted code changes.
Unit tests are located at sahara/tests.
Sahara’s suite of unit tests can be executed in an isolated environment with Tox. To execute the unit tests run the following from the root of Sahara repo:
$ tox -e py27
All Sahara docs are written using Sphinx / RST and located in the main repo in doc directory. You can add/edit pages here to update http://docs.openstack.org/developer/sahara site.
The documentation in docstrings should follow the PEP 257 conventions (as mentioned in the PEP 8 guidelines).
More specifically:
Run the following command to build docs locally.
$ tox -e docs
After it you can access generated docs in doc/build/ directory, for example, main page - doc/build/html/index.html.
To make docs generation process faster you can use:
$ SPHINX_DEBUG=1 tox -e docs
or to avoid sahara reinstallation to virtual env each time you want to rebuild docs you can use the following command (it could be executed only after running tox -e docs first time):
$ SPHINX_DEBUG=1 .tox/docs/bin/python setup.py build_sphinx
Note
For more details on documentation guidelines see file HACKING.rst in the root of Sahara repo.