Contributing

Contributing to the skeleton repository is different to other repos. There are two sorts of contributions:

  • Changes to the skeleton structure should be made on a branch, then a PR raised back to the skeleton branch.

  • Changes to the docs or commandline tool should be made directly on master

Running the tests

Both the skeleton and master branch have different tests, but the process to run them is the same:

$ git clone git://github.com/dls-controls/dls-python3-skeleton.git
$ cd dls-python3-skeleton
$ pipenv install --dev
$ pipenv run tests

Please note that Pipfile.lock is only committed on master, not on skeleton

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

Releases are only made when the commandline tool needs to be released. When this happens:

  • Choose a new PEP440 compliant release number

  • Git tag the version

  • Push to github and the actions will make a release on pypi

  • Push to internal gitlab and do a dls-release.py of the tag

  • Check and edit for clarity the autogenerated GitHub release

Apart from this, master and skeleton should always be deployable, and are considered the latest release.