Contributing to COT¶
Please do contribute! We only have a few simple requirements for diffs and pull requests.
- Follow coding guidelines
- Add automated unit tests
- Update documentation
- Add yourself as a contributor
- Open a pull request
Follow coding guidelines¶
Logging level usage¶
COT uses logging levels (including the additional intermediate logging levels provided by the verboselogs package) as follows:
Something is definitely wrong, but COT is able to proceed, at least for the moment. COT may raise an exception at some later point due to this issue.
If continuing is already known to be impossible, you should raise an exception now instead of logging an ERROR message.
Something potentially wrong, or at least risky, happened that the user should be informed of.
This includes cases where, due to insufficient information provided by the user, COT had to make an uncertain choice on its own (or was unable to make such a decision but is continuing nonetheless).
Something noteworthy happened that is not necessarily a problem, but deserves the user's attention.
This is the lowest logging level enabled by default, so messages generated at and above this level should be succinct and meaningful to all users.
|INFO||Status updates about normal operation of the software.||
|VERBOSE||Detailed information of interest to an expert or very curious user.||
|DEBUG||Highly detailed information, probably only useful to a developer familiar with the code.||
|SPAM||Extremely detailed or repetitive info that even a developer will rarely want to see.||
We try to keep COT's code base compliant with Python coding standards including
PEP 8 and PEP 257. We use the flake8 and Pylint tools and their
extension packages to verify this as part of our test automation.
To run coding style analysis independently of the other test automation, you
tox -e flake8,pylint, or you can install these tools and run them
cot/$ sudo pip install --upgrade flake8 cot/$ sudo pip install --upgrade pydocstyle cot/$ sudo pip install --upgrade flake8-docstrings cot/$ sudo pip install --upgrade pep8-naming cot/$ sudo pip install --upgrade mccabe cot/$ flake8 ./COT/ovf/item.py:229:1: C901 'OVFItem.value_replace_wildcards' is too complex (11) ./COT/ovf/item.py:603:1: C901 'OVFItem.generate_items' is too complex (11) ./COT/ovf/ovf.py:461:1: C901 'OVF.validate_hardware' is too complex (14)
cot/$ sudo pip install --upgrade pylint cot/$ pylint COT ************* Module COT.ovf.item E:331,24: Instance of 'list' has no 'split' member (no-member) R:334,16: Redefinition of value type from list to tuple (redefined-variable-type) R:603, 4: Too many branches (13/12) (too-many-branches) ************* Module COT.ovf.ovf C: 1, 0: Too many lines in module (2646/2600) (too-many-lines) R:177, 0: Too many public methods (76/74) (too-many-public-methods)
Fix any errors and warnings these tools report, and run again until no errors are reported.
When adding or modifying CLI, keep the following guidelines in mind:
- All subcommands must support
--help. Never redefine
-hto mean something other than "get help".
- All commands that modify files must define
--outputto specify a new file to create instead of overwriting any input file. If and only if the command does not modify the input file, you may use
-oto mean something else (e.g.,
cot deploy ...has
- Best effort: use consistent argument names and short argument names unless
there's an unavoidable conflict. Examples:
cot remove-fileabbreviates it as
-ibecause it uses
--file-path. In retrospect, using
--file-pathwould have allowed COT to be more self-consistenct.
--profilesto specify one or more configuration profiles to operate on.
cot deploy esxiuses
--configurationto specify the configuration profile to deploy. In this case, this is somewhat unavoidable as
--cpus(no reasonable alternative) and
cot deploy esxiuses
- In cases where short argument names unavoidably differ between commands,
support the same set of long names if at all possible. For example,
cot deploy esxishould both support both
--configuration(s) as synonymous long names that can be used interchangeably to specify a configuration profile.
Add automated unit tests¶
Whether adding new functionality or fixing a bug, please add appropriate
unit test case(s) under
(as appropriate) to cover your changes. Your changes must pass all existing
and new automated test cases before your code will be accepted.
You can run the COT automated tests under a single Python version by
python ./setup.py test.
For full testing under all supported versions as well as verifying code
coverage for your tests, you should install tox (
pip install tox) and
pip install coverage) then run
tox from the COT directory:
cot/$ tox ... py27 runtests: commands | coverage run --append setup.py test --quiet ... py33 runtests: commands | coverage run --append setup.py test --quiet ... py34 runtests: commands | coverage run --append setup.py test --quiet ... py35 runtests: commands | coverage run --append setup.py test --quiet ... py36 runtests: commands | coverage run --append setup.py test --quiet ... pypy runtests: commands | coverage run --append setup.py test --quiet ... flake8 runtests: commands | flake8 ... pylint runtests: commands | pylint COT ... docs runtests: commands | sphinx-build -W -b html -d ... ... stats runtests: commands | coverage combine stats runtests: commands | coverage report -i Name Stmts Miss Branch BrPart Cover ---------------------------------------------------------------------- COT/__init__.py 5 0 0 0 100% COT/add_disk.py 168 3 66 3 97% COT/add_file.py 45 0 12 0 100% COT/cli.py 254 15 95 9 93% COT/data_validation.py 124 2 44 1 98% COT/deploy.py 154 6 62 6 94% COT/deploy_esxi.py 196 0 68 1 99% COT/disks/__init__.py 23 0 10 0 100% COT/disks/disk.py 56 1 20 1 97% ... COT/vm_description.py 166 4 4 0 98% COT/vm_factory.py 26 0 4 0 100% COT/xml_file.py 121 3 54 1 98% ---------------------------------------------------------------------- TOTAL 5122 114 1908 105 97% stats runtests: commands | coverage html -i _______________ summary _______________ setup: commands succeeded py27: commands succeeded py33: commands succeeded py34: commands succeeded py35: commands succeeded py36: commands succeeded pypy: commands succeeded flake8: commands succeeded pylint: commands succeeded docs: commands succeeded stats: commands succeeded congratulations :)
tox you can check the code coverage details by opening
htmlcov/index.html in a web browser.
If you add or change any COT CLI or APIs, or add or remove any external dependencies, please update the relevant documentation.
Add yourself as a contributor¶
If you haven't contributed to COT previously, be sure to add yourself as a
contributor in the