mirror of
https://github.com/theupdateframework/python-tuf
synced 2026-05-24 10:08:28 +00:00
4d1fad233a
Rename CONTRIBUTORS.rst -> CONTRIBUTING.rst. The new name is what GitHub expects and will make the document more discoverable, e.g. on https://github.com/theupdateframework/python-tuf/contribute. More details under: https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors Note: I searched all repositories in theupdateframework GitHub organization for references (there were none) and will update the links in the CII Best Practice badge app for tuf. Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
111 lines
3.4 KiB
ReStructuredText
111 lines
3.4 KiB
ReStructuredText
Instructions for Contributors
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Contribute to python-tuf by submitting pull requests against the "develop"
|
|
branch of this repository. Detailed instructions are available in our
|
|
`development guidelines
|
|
<https://github.com/secure-systems-lab/lab-guidelines/blob/master/dev-workflow.md>`_.
|
|
All submitted code should follow our `style guidelines
|
|
<https://github.com/secure-systems-lab/code-style-guidelines/blob/master/python.md>`_
|
|
and must be `unit tested <#unit-tests>`_.
|
|
|
|
Development Installation
|
|
========================
|
|
|
|
To work on the TUF project, it's best to perform a development install.
|
|
|
|
To facilitate development and installation of edited version of the code base,
|
|
developers are encouraged to use `venv <https://docs.python.org/3/library/venv.html>`_.
|
|
|
|
1. First, `install non-Python dependencies
|
|
<https://theupdateframework.readthedocs.io/en/latest/INSTALLATION.html#non-python-dependencies>`_.
|
|
|
|
2. Then clone this repository:
|
|
|
|
::
|
|
|
|
$ git clone https://github.com/theupdateframework/python-tuf
|
|
|
|
3. 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
|
|
|
|
|
|
Testing
|
|
=======
|
|
|
|
With `tox <https://testrun.org/tox/>`_ the whole test suite can be executed in
|
|
a separate *virtual environment* for each supported Python version available on
|
|
the system. ``tuf`` and its dependencies are installed automatically for each
|
|
tox run.
|
|
|
|
::
|
|
|
|
$ tox
|
|
|
|
Below, you will see more details about each step managed by ``tox``, in case
|
|
you need debug/run outside ``tox``.
|
|
|
|
Unit tests
|
|
----------
|
|
|
|
More specifically, the Update Framework's test suite can be executed by invoking
|
|
the test aggregation script inside the *tests* subdirectory. ``tuf`` and its
|
|
dependencies must already be installed.
|
|
::
|
|
|
|
$ 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``).
|
|
::
|
|
|
|
$ cd tests/
|
|
$ python3 test_updater_ng.py -v
|
|
|
|
|
|
Coverage
|
|
--------
|
|
|
|
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).
|
|
::
|
|
|
|
$ cd tests/
|
|
$ coverage run aggregate_tests.py && coverage report
|
|
|
|
|
|
Auto-formatting
|
|
---------------
|
|
|
|
CI/CD will check that new TUF code is formatted with `black
|
|
<https://black.readthedocs.io/>`__ and `isort <https://pycqa.github.io/isort>`__.
|
|
Auto-formatting can be done on the command line:
|
|
::
|
|
|
|
$ black <filename>
|
|
$ isort <filename>
|
|
|
|
or via source code editor plugin
|
|
[`black <https://black.readthedocs.io/en/stable/editor_integration.html>`__,
|
|
`isort <https://github.com/pycqa/isort/wiki/isort-Plugins>`__] or
|
|
`pre-commit <https://pre-commit.com/>`__-powered git hooks
|
|
[`black <https://black.readthedocs.io/en/stable/version_control_integration.html>`__,
|
|
`isort <https://pycqa.github.io/isort/docs/configuration/pre-commit/>`__].
|
|
|
|
|
|
DCO
|
|
===
|
|
|
|
Contributors must also indicate acceptance of the `Developer Certificate of
|
|
Origin <https://developercertificate.org/>`_ by appending a ``Signed-off-by:
|
|
Your Name <example@domain.com>`` to each git commit message (see `git commit
|
|
--signoff <https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---signoff>`_).
|