Contributing
Contributions and issues are most welcome! All issues and pull requests are handled through GitHub. Also, please check for any existing issues before filing a new one. If you have a great idea but it involves big changes, please file a ticket before making a pull request! We want to make sure you don’t spend your time coding something that might not fit the scope of the project.
Running the tests
To get the source source code and run the unit tests, run:
$ git clone git://github.com/DiamondLightSource/coniql.git
$ cd coniql
$ pipenv install --dev
$ pipenv run tests
While 100% code coverage does not make a library bug-free, it significantly reduces the number of easily caught bugs! Please make sure coverage remains the same or is improved by a pull request!
Code Styling
The code in this repository conforms to standards set by the following tools:
black for code formatting
flake8 for style checks
isort for import ordering
mypy for static type checking
These checks will be run by pre-commit. You can either choose to run these tests on all files tracked by git:
$ pipenv run lint
Or you can install a pre-commit hook that will run each time you do a git
commit
on just the files that have changed:
$ pipenv run pre-commit install
Docstrings are pre-processed using the Sphinx Napoleon extension. As such, google-style is considered as standard for this repository. Please use type hints in the function signature for types. For example:
def func(arg1: str, arg2: int) -> bool:
"""Summary line.
Extended description of function.
Args:
arg1: Description of arg1
arg2: Description of arg2
Returns:
Description of return value
"""
return True
Documentation
Documentation is contained in the docs
directory and extracted from
docstrings of the API.
Docs follow the underlining convention:
Headling 1 (page title)
=======================
Heading 2
---------
Heading 3
~~~~~~~~~
You can build the docs from the project directory by running:
$ pipenv run docs
$ firefox build/html/index.html
Release Process
To make a new release, please follow this checklist:
Choose a new PEP440 compliant release number
Git tag the version
Push to GitHub and the actions will make a release on pypi
Check and edit for clarity the autogenerated GitHub release
Updating the tools
This module is merged with the python3-pip-skeleton. This is a generic Python project structure which provides a means to keep tools and techniques in sync between multiple Python projects. To update to the latest version of the skeleton, see instructions.