Guideline to contribute to this package


You’re welcome to contribute to this package with or without raising an issue before creating a PR.

Please follow the following guideline covering all necessary steps and hints for a smooth review and contribution process.


To test and verify your changes it is recommended to run all checks locally in a virtual environment. Use the following command to setup and install all tools.

python3 -m venv .venv
source .venv/bin/activate

pip install -r requirements-test.txt

For very old systems it might be necessary to use an older version of pre-commit, an “always” working version is 1.18.3 with the drawback of not having flake8 and maybe other checks in place.


The Python code format is checked by flake8 with the default line length limit of 79. Further configuration can be found in the .flake8 file in the repo root.

The YAML code format is checked by yamllint with some small adjustments as defined in the .yamllint file in the repo root.

Use the following commands (inside the virtual environment) to run the Python and YAML checks

# check Python
flake8 .

# check YAML
yamllint .


Every code should be covered by a unittest. This can be achieved for MicroPython up to some degree, as hardware specific stuff can’t be always tested by a unittest.

For now nose2 is used as tool of choice. The configuration is defined in the tests/unittest.cfg file.

All reports are placed inside the reports folder or a subfolder of it. It can be created with


After this either all or a specific unittest can be executed, see the following commands as an example

# run all tests
nose2 --config tests/unittest.cfg

# run only one specific tests
nose2 tests.test_blink.TestBlink.test_flash_led

As last step the coverage report can be generated. There might be a minimum coverage limit set up for the project. Check the value of target in the codecov.yaml file, located in the repo root.

coverage html

The coverage report is placed at reports/coverage/html/index.html

Precommit hooks

This repo is equipped with a .pre-commit-config.yaml file to combine most of the previously mentioned checks plus the changelog validation, see next section, into one handy command. It additionally allows to automatically run the checks on every commit.

In order to run this repo’s pre commit hooks, perform the following steps

# install pre-commit to run before each commit, optionally
pre-commit install

pre-commit run --all-files


The changelog format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Please add a changelog entry for every PR you contribute. The versions are seperated into MAJOR.MINOR.PATCH:

  • Increment the major version by 1 in case you created a breaking, non backwards compatible change which requires the user to perform additional tasks, adopt his currently running code or in general can’t be used as is anymore.

  • Increment the minor version by 1 on new “features” which can be used or are optional, but in either case do not require any changes by the user to keep the system running after upgrading.

  • Increment the patch version by 1 on bugfixes which fix an issue but can be used out of the box, like features, without any changes by the user. In some cases bugfixes can be breaking changes of course.

Please add the date the change has been made as well to the changelog following the format ## [MAJOR.MINOR.PATCH] - YYYY-MM-DD. It is not necessary to keep this date up to date, it is just used as meta data.

The changelog entry shall be short but meaningful and can of course contain links and references to other issues or PRs. New lines are only allowed for a new bulletpoint entry. Usage examples or other code snippets should be placed in the code documentation, README or the docs folder.


The package version file, located at <PACKAGE_NAME>/ contains the latest changelog version.

To avoid a manual sync of the changelog version and the package version file content, the changelog2version package is used. It parses the changelog, extracts the latest version and updates the version file.

The package version file can be generated with the following command consuming the latest changelog entry

changelog2version \
	--changelog_file \
	--version_file <PACKAGE_NAME>/ \
	--version_file_type py \

To validate the existing package version file against the latest changelog entry use this command

changelog2version \ \
	--version_file=<PACKAGE_NAME>/ \


On MicroPython the mip package is used to install packages instead of pip at MicroPython version 1.20.0 and newer. This utilizes a package.json file in the repo root to define all files and dependencies of a package to be downloaded by mip.

To avoid a manual sync of the changelog version and the MicroPython package file content, the setup2upypackage package is used. It parses the changelog, extracts the latest version and updates the package file version entry. It additionally parses the file and adds entries for all files contained in the package to the urls section and all other external dependencies to the deps section.

The MicroPython package file can be generated with the following command based on the latest changelog entry and setup file.

upy-package \
	--setup_file \
	--package_changelog_file \
	--package_file package.json

To validate the existing package file against the latest changelog entry and setup file content use this command

upy-package \
	--setup_file \
	--package_changelog_file \
	--package_file package.json \


Please check the docs/ file for further details.