Contribution guide

Information on how to make contributions to the hdl-registers project.

Setting up development environment

For development we have a lot more python dependencies than when simply using the package. Install further dependencies with:

python3 -m pip install --upgrade --requirement hdl_registers/requirements_develop.txt

Maintaining changelog

We maintain a changelog according to the keep a changelog format. The unreleased changelog in doc/release_notes/unreleased.rst shall be updated continuously, not just at release. Release note files are in the rst format, inspect older release note files to see the formatting details.

How to build documentation

Documentation is built using the tools/build_docs.py script. The documentation pages have information about python unit test code coverage. So before building documentation you must run pytest with coverage reports enabled like in CI:

python3 -m pytest -v --cov hdl_registers \
  --cov-report xml:generated/python_coverage.xml \
  --cov-report html:generated/python_coverage_html hdl_registers

If want to skip handling of coverage for the documentation there is a flag available in the script, see build_docs.py --help.

How to make a new release

Releases are made to the Python Packaging Index (PyPI) and can be installed with the python pip tool. To make a new release follow these steps.

Test CI pipeline

Before doing anything, launch a CI run from main branch to see that everything works as expected. The CI environment is stable but due to things like, e.g., new pylint version it can unexpectedly break. When the pipeline has finished and is green you can move on to the next step.

Review the release notes

Check the release notes file unreleased.rst. Fill in anything that is missing according to Maintaining changelog.

Determine new version number

We use the Semantic Versioning scheme. Read the Summary at the top of that page and decide the new version number accordingly.

Run release script

Run the script

python3 tools/tag_release.py X.Y.Z

where X.Y.Z is your new version number. The script will bump the hdl-registers version number and copy release notes to a new file. The changes will be committed and then tagged.

Push commit and tag

TODO fill in this once we do our first release from GitHub.