Instructions for Contributors

Note: Development of TUF occurs on the “develop” branch of this repository.

Contributions can be made by submitting GitHub pull requests. Submitted code should follow our code style guidelines, which are enforced with linters and auto-formatters (details below).

Contributors must also indicate acceptance of the Developer Certificate of Origin (DCO) when making a contribution to the project. Acceptance of the DCO can be established by appending a Signed-off-by: Your Name <example@domain.com> to the Git commit message. For example:

Commit message

Signed-off-by: Vladimir Diaz <vladimir.v.diaz@gmail.com>

The required Signed-off-by text can be automatically appended to the commit message via the -s command-line option to git commit:

$ git commit -s -m "Commit message"

The full text of the DCO:

Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
1 Letterman Drive
Suite D4700
San Francisco, CA, 94129

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.

Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I have the
right to submit it under the open source license indicated in the file; or

(b) The contribution is based upon previous work that, to the best of my
knowledge, is covered under an appropriate open source license and I have
the right under that license to submit that work with modifications,
whether created in whole or in part by me, under the same open source
license (unless I am permitted to submit under a different license), as
indicated in the file; or

(c) The contribution was provided directly to me by some other person who
certified (a), (b) or (c) and I have not modified it.

(d) I understand and agree that this project and the contribution are
public and that a record of the contribution (including all personal
information I submit with it, including my sign-off) is maintained
indefinitely and may be redistributed consistent with this project or the
open source license(s) involved.

To facilitate development and installation of edited version of the code base, developers are encouraged to install Virtualenv, which is a tool to create isolated Python environments. It includes pip and setuptools, Python packages that can be used to install TUF and its dependencies. All installation methods of virtualenv are outlined in the installation section, and instructions for installing locally from source are provided here:

$ curl -O https://pypi.python.org/packages/source/v/virtualenv/virtualenv-15.0.3.tar.gz
$ tar xvfz virtualenv-15.0.3.tar.gz
$ cd virtualenv-15.0.3
$ python3 virtualenv.py myVE

Development Installation

To work on the TUF project, it’s best to perform a development install.

First, install non-Python dependencies.
Then clone this repository:

$ git clone https://github.com/theupdateframework/python-tuf

Then perform a full, editable/development install. This will include all optional cryptographic support, the testing/linting dependencies, etc. With a development installation, modifications to the code in the current directory will affect the installed version of TUF.

$ python3 -m pip install -r requirements-dev.txt

Auto-formatting

CI/CD will check that new TUF code is formatted with black and isort. Auto-formatting can be done on the command line:

$ # TODO: configure black and isort args in pyproject.toml (see #1161)
$ black --line-length 80 tuf/api
$ isort --line-length 80 --profile black -p tuf tuf/api

or via source code editor plugin [black, isort] or pre-commit-powered git hooks [black, isort].

Testing

The Update Framework’s unit test suite can be executed by invoking the test aggregation script inside the tests subdirectory. tuf and its dependencies must already be installed (see above).

$ cd tests
$ python3 aggregate_tests.py

Individual tests can also be executed. Optional ‘-v’ flags can be added to increase log level up to DEBUG (‘-vvvv’).

$ python3 test_updater.py # run a specific test file
$ python3 test_updater.py TestUpdater.test_4_refresh # run a specific test
$ python3 test_updater.py -vvvv TestUpdater.test_4_refresh # run test with DEBUG log level

All of the log levels and the corresponding options that could be used for testing are:

Option	Log Level
default (no argument passed)	ERROR (test names are not printed)
-v	ERROR (test names are printed at this level and above)
-vv	WARNING
-vvv	INFO
-vvvv	DEBUG

To run the tests and measure their code coverage, the aggregation script can be invoked with the coverage tool (requires installation of coverage, e.g. via PyPI).

$ coverage run aggregate_tests.py && coverage report

To develop and test tuf with above commands alongside its in-house dependency securesystemslib, it is recommended to first make an editable install of tuf (in a venv), and then install securesystemslib in editable mode too (in the same venv).

$ cd path/to/tuf
$ python3 -m pip install -r requirements-dev.txt
$ cd path/to/securesystemslib
$ python3 -m pip install -r requirements-dev.txt

With tox the test suite can be executed in a separate venv for each supported Python version. While the supported Python versions must already be available, tox will install tuf and its dependencies anew in each environment.

$ tox

An additional non-default tox environment is available and can be used to test tuf against the tip of development of securesystemslib on GitHub, to e.g. prepare the former for a new release of the latter.

$ tox -e with-sslib-master