Contributing in the form of code, feedback, ideas or bug reports are welcome. Code contributions are expected to pass all tests and style checks. If there are any problems let us know.
Before doing any major changes we recommend creating an issue or chatting with us on gitter to discuss first. In this way you do not get started on the wrong track and wasting time.
Being a testing framework we value automated testing and all contributions in both the Python and VHDL/SystemVerilog domain are expected to add new tests along with the new functionality.
Any contribution must give the copyright to Lars Asplund. This is necessary to manage the project freely. Copyright is given by adding the copyright notice to the beginning of each file.
# This Source Code Form is subject to the terms of the Mozilla Public # License, v. 2.0. If a copy of the MPL was not distributed with this file, # You can obtain one at http://mozilla.org/MPL/2.0/. # # Copyright (c) 2014-2023, Lars Asplund firstname.lastname@example.org
VUnit runs all test and lint checks on both GNU/Linux and Windows with several versions of Python (typically, the oldest and newest supported by both VUnit and the CI environment). GHDL is used to run the VHDL tests of all our libraries and examples.
All tests will be automatically run on any pull request and they are expected to pass for us to approve the merge.
Any commit on master that has a successful CI run will automatically update the VUnit website
Testing with Tox#
VUnit uses the Python tox tool in the CI flow. Typically developers do not need to run this on their local machine.
Tox makes it easier to automatically test VUnit in various configurations. Tox automates creation of virtual environments and installation of dependencies needed for testing. In fact, all of the tests can be run in a single command:
vunit/ > tox
If tox is not available in your Python environment, it can be installed from PyPI with pip:
vunit/ > pip install tox
For most developers, running the full testsuite will likely lead to failed test cases because not all Python interpreters or HDL simulators are installed in their environment. More focused testing is possible by specifying which tox “environments” should be tested. For example, assume a developer uses Python 3.8 and Modelsim and would like to test changes using tools available in his environment:
vunit/ > tox -e py38-unit,py38-acceptance-modelsim
A full list of test environments can be seen by issuing the following command:
vunit/ > tox -l
Releases are automatically made by GitHub Actions on any
master commit which is tagged.
To create a new tagged release commit:
Build the docs and review the content of
If necessary, create additional news files and build the docs again.
Add the news summary as the release notes and remove news fragments:
mv docs/news.inc docs/release_notes/X.Y.Z.rst git add docs/release_notes/X.Y.Z.rst git rm -f docs/news.d/*.rst
python tools/release.py create X.Y.Z.
Will make and tag a commit with the new
about.pyversion, the release notes and removed news files.
Will make another commit setting
about.pyto the next development version.
- Push the tag to remote to trigger the release build.
git push origin vX.Y.Z
- If the release build is successful, you can push the two commits to master.
git push origin master
If, in the meantime, a new commit has come into origin/master the two commits have to be merged into origin/master.
The CI service makes a release by uploading a new package to PyPI when a tag named
vX.Y.Z is found in Git.
A new release will not be made if:
X.Y.Zrelease is already on PyPI.
The repo tag does not exist.
Release Notes Instructions#
Make sure to use full sentences in the past or present tense and use punctuation.
Each file should be named like
<issue #>.<type>.rst, where
<issue #> is the
GitHub issue or pull request number, and
<type> is one of:
breaking:may break existing functionality; such as feature removal or behavior change.
bugfix: fixes a bug.
doc: related to the documentation.
deprecation: feature deprecation.
feature: backwards compatible feature addition or improvement.
misc: a ticket was closed, but it is not necessarily important for the user.
towncrier preserves multiple paragraphs and formatting
(code blocks, lists, and so on), but for entries other than features, it is usually better to stick
to a single paragraph to keep it concise.