Developers Guide¶

The project is hosted on GitHub. and uses GitHub Actions for Continuous Integration.

If you have found a bug or have an idea for an enhancement that would improve the library, use the bug tracker.

To develop aioprometheus you’ll need Python 3.6+, some dependencies and the source code.

Get the source¶

$ git clone git@github.com:claws/aioprometheus.git
$ cd aioprometheus

Setup¶

The best way to work on aioprometheus is to create a virtual env. This isolates your work from other project’s dependencies and ensures that any commands are pointing at the correct tools.

Note

You may need to explicitly specify which Python to use if you have multiple Python’s available on your system (e.g. python3, python3.8).

$ python3 -m venv venv --prompt aioprom
$ source venv/bin/activate
(aioprom) $
(aioprom) $ pip install pip --upgrade

Note

The following steps assume you are operating in a virtual environment.

To exit the virtual environment simply type deactivate.

Install Development Environment¶

Rules in the convenience Makefile depend on the development dependencies being installed. The development dependencies also include various web application frameworks to assist verifying integration methods. Install the developmental dependencies using pip. Then install the aioprometheus package (and its optional dependencies). in a way that allows you to edit the code after it is installed so that any changes take effect immediately.

(aioprom) $ pip install -r requirements.dev.txt
(aioprom) $ pip install -e .[aiohttp,binary]

Code Style¶

This project uses the Black code style formatter and isort to sort imports for consistent code style. A Makefile convenience rule is available to apply code style compliance.

(aioprom) $ make style

Linting¶

This project uses Pylint to perform static analysis. A Makefile convenience rule is available to check linting.

(aioprom) $ make check-lint

Type Annotations¶

The code base uses type annotations to provide helpful typing information that can improve code comprehension which can help with future enhancements.

The type annotations checker mypy should run cleanly with no warnings.

Use the Makefile convenience rule to check no issues are reported.

(aioprom) $ make check-types

Test¶

The easiest method to run all of the unit tests is to run the make test rule from the top level directory. This runs the standard library unittest tool which discovers all the unit tests and runs them.

(aioprom) $ make test

Or, you can call the standard library unittest module directly.

(aioprom) $ python -m unittest discover -s tests -v

Individual unit tests can be run using the standard library unittest package too.

(aioprom) $ cd aioprometheus/tests
(aioprom) $ python -m unittest test_negotiate

Coverage¶

A Makefile convenience rule is available to check how much of the code is covered by tests.

(aioprom) $ make coverage

The test code coverage report for the current release can be found here

Documentation¶

To rebuild the project documentation, developers should run the make docs rule from the top level directory. It performs a number of steps to create a new set of sphinx html content.

(aioprom) $ make docs

To view the rendered docs locally run the serve-docs rule from the top level directory to start a simple Python web server.

(aioprom) $ make serve-docs

Then open a browser to the docs content.

Version¶

aioprometheus uses a three segment CalVer versioning scheme comprising a short year, a zero padded month and then a micro version. The YY.MM part of the version are treated similarly to a SemVer major version. So when backwards incompatible or major functional changes occur the YY.MM will be rolled up. For all other minor changes only the micro part will be incremented.

Release Process¶

Assuming that the tests are passing, the docs build without warnings and the type annotations check passes without warnings then a release can be made.

The following steps are used to make a new software release:

Ensure that the version label in __init__.py is correct. It must comply with the Version scheme.
Create the distribution. This project produces an artefact called a pure Python wheel. Only Python3 is supported by this package.
```
(aioprom) $ make dist
```
Test distribution. This involves creating a virtual environment, installing the distribution in it and running the tests. These steps have been captured for convenience in a Makefile rule.
```
(aioprom) $ make test-dist
```
Upload to PyPI using
```
(aioprom) $ make upload-dist
```

Create and push a repo tag to Github.

$ git tag YY.MM.MICRO -m "A meaningful release tag comment"
$ git tag  # check release tag is in list
$ git push --tags origin master

Github will create a release tarball at:

https://github.com/{username}/{repo}/tarball/{tag}.tar.gz