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 of the skeleton-repo with a PR raised back to the main branch from here: PR.
Changes to the docs or commandline tool should be made on a branch in the cli-repo with with a PR raised back to the main branch here: PR2

Apart from this, main branch in both repos should always be deployable, and are considered the latest release.

Running the tests

Both the skeleton and main repos have different tests, but the process to run them is the same. You can run in a container using the supplied devcontainer or you can run them locally.

To run in a container

Use vscode devcontainer as follows:

$ git clone git://github.com/epics-containers/python3-pip-skeleton.git
$ vscode python3-pip-skeleton
Click on 'Reopen in Container' when prompted
In a vscode Terminal:
$ tox -p

To run locally

Get the source source code and run the unit tests directly on your workstation as follows:

$ git clone git://github.com/epics-containers/python3-pip-skeleton.git
$ cd python3-pip-skeleton
$ virtualenv .venv
$ source .venv/bin/activate
$ pip install -e .[dev]
$ tox -p

Checks

In both cases tox -p runs in parallel the following checks.

Build Sphinx Documentation

run pytest on all tests in ./tests

run mypy linting on all files in ./src ./tests

run pre-commit checks:

run flake8 style checks against all source

run black formatting checks against all source

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

flake8 and black and isort are run by pre-commit. You can run the above checks on all files with this command:

$ tox -e pre-commit,mypy

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. Note that mypy is not in the pre-commit because it is a little slow

$ 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:

$ tox -e 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 (see https://peps.python.org/pep-0440/)
Go to the GitHub release page
Choose Draft New Release
Click Choose Tag and supply the new tag you chose (click create new tag)
Click Generate release notes, review and edit these notes
Choose a title and click Publish Release

Note that tagging and pushing to the main branch has the same effect except that you will not get the option to edit the release notes.

Checking Dependencies

To see a graph of the python package dependency tree type:

pipdeptree