From 00b773b8d0d3a6eaad6e9a57755af3f21a47b8b8 Mon Sep 17 00:00:00 2001 From: Kairo de Araujo Date: Wed, 19 Jan 2022 10:44:20 +0100 Subject: [PATCH 1/3] docs: contributors enhancements This commit simplifies the contributor's doc. It adds the reference to the Secure Systems Lab Development Guidelines, gives more evidence to the tox usage, shares information about the tests, linting, and coverage, and creates a session about submitting the contributions highlighted by the DCO. Fixes #1709 Signed-off-by: Kairo de Araujo --- docs/CONTRIBUTORS.rst | 195 ++++++++++++------------------------------ 1 file changed, 53 insertions(+), 142 deletions(-) diff --git a/docs/CONTRIBUTORS.rst b/docs/CONTRIBUTORS.rst index 1ba6bf10b1..fb98b875fe 100644 --- a/docs/CONTRIBUTORS.rst +++ b/docs/CONTRIBUTORS.rst @@ -1,92 +1,22 @@ 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 `` to the Git commit message. -For example: - -:: - - Commit message - - Signed-off-by: Vladimir Diaz - -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 - +Contribute to python-tuf by submitting pull requests against the "develop" +branch of this repository. Detailed instructions are available in our +`development guidelines +`_. +All submitted code should follow our `style guidelines +`_ +and must be unit tested [reference to test section below] . 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 `_. + 1. First, `install non-Python dependencies `_. 2. Then clone this repository: @@ -105,96 +35,77 @@ To work on the TUF project, it's best to perform a development install. $ python3 -m pip install -r requirements-dev.txt -Auto-formatting -=============== +Testing +======= -CI/CD will check that new TUF code is formatted with `black -`__ and `isort `__. -Auto-formatting can be done on the command line: -:: +With `tox `_, the test suite can be executed in a +separate *venv*. While a supported Python version must already be available, +``tox`` will install ``tuf`` and dependencies, run the tests, auto-formatting, +and coverage. - $ black - $ isort +:: -or via source code editor plugin -[`black `__, -`isort `__] or -`pre-commit `__-powered git hooks -[`black `__, -`isort `__]. + $ tox +Below, you will see more details about each steps managed by ``tox``, in case +you need debug/run outside ``tox``. -Testing -======= +Unit tests +---------- -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). +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 + $ 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_ng.py # run a specific test file - $ python3 test_updater_ng.py TestUpdater.test_refresh_and_download # run a specific test - $ python3 test_updater_ng.py -vvvv TestUpdater.test_refresh_and_download # run test with DEBUG log level + $ cd tests/ + $ python3 test_updater_ng.py -v -All of the log levels and the corresponding options that could be used for testing are: - -.. list-table:: - :widths: 20 25 - :header-rows: 1 - - * - 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 +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 -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*). -:: +Auto-formatting +--------------- - $ cd path/to/tuf - $ python3 -m pip install -r requirements-dev.txt - $ cd path/to/securesystemslib - $ python3 -m pip install -r requirements-dev.txt +CI/CD will check that new TUF code is formatted with `black +`__ and `isort `__. +Auto-formatting can be done on the command line: +:: + $ black + $ isort -With `tox `_, the test suite can be executed in a -separate *venv*. While a supported Python version must already be available, -``tox`` will install ``tuf`` and dependencies. -:: +or via source code editor plugin +[`black `__, +`isort `__] or +`pre-commit `__-powered git hooks +[`black `__, +`isort `__]. - $ tox +Submitting Contributions +======================== -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. -:: +Contributions can be made by submitting GitHub pull requests. - $ tox -e with-sslib-master +Contributors must also indicate acceptance of the `Developer Certificate of +Origin `_ by appending a ``Signed-off-by: +Your Name `` to each git commit message (see `git commit +--signoff `_). From cd61b149d5a893419e7858939fe71adcc3f6bf2c Mon Sep 17 00:00:00 2001 From: Kairo de Araujo Date: Thu, 20 Jan 2022 14:43:26 +0100 Subject: [PATCH 2/3] fixed links, RST formatting and text Fixed some links, RST formatting and made some texts more clear understanding. Signed-off-by: Kairo de Araujo --- docs/CONTRIBUTORS.rst | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/docs/CONTRIBUTORS.rst b/docs/CONTRIBUTORS.rst index fb98b875fe..981809cf45 100644 --- a/docs/CONTRIBUTORS.rst +++ b/docs/CONTRIBUTORS.rst @@ -7,7 +7,7 @@ branch of this repository. Detailed instructions are available in our `_. All submitted code should follow our `style guidelines `_ -and must be unit tested [reference to test section below] . +and must be `unit tested <#unit-tests>`_. Development Installation ======================== @@ -38,16 +38,16 @@ developers are encouraged to use `venv `_, the test suite can be executed in a -separate *venv*. While a supported Python version must already be available, -``tox`` will install ``tuf`` and dependencies, run the tests, auto-formatting, -and coverage. +With `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 steps managed by ``tox``, in case +Below, you will see more details about each step managed by ``tox``, in case you need debug/run outside ``tox``. Unit tests @@ -62,8 +62,9 @@ dependencies must already be installed. $ python3 aggregate_tests.py -Individual tests can also be executed. Optional '-v' flags can be added to -increase log level up to DEBUG ('-vvvv'). +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 @@ -100,10 +101,8 @@ or via source code editor plugin `isort `__]. -Submitting Contributions -======================== - -Contributions can be made by submitting GitHub pull requests. +DCO +=== Contributors must also indicate acceptance of the `Developer Certificate of Origin `_ by appending a ``Signed-off-by: From c87ff3e874a5d0a28abdbb4961d78fa9825f629a Mon Sep 17 00:00:00 2001 From: Kairo de Araujo Date: Tue, 25 Jan 2022 11:23:52 +0100 Subject: [PATCH 3/3] Fixed broken link on RTD Fix the RTD link using the absolute link. Signed-off-by: Kairo de Araujo --- docs/CONTRIBUTORS.rst | 3 ++- docs/conf.py | 5 ++++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/CONTRIBUTORS.rst b/docs/CONTRIBUTORS.rst index 981809cf45..de82cb46c0 100644 --- a/docs/CONTRIBUTORS.rst +++ b/docs/CONTRIBUTORS.rst @@ -17,7 +17,8 @@ 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 `_. -1. First, `install non-Python dependencies `_. +1. First, `install non-Python dependencies +`_. 2. Then clone this repository: diff --git a/docs/conf.py b/docs/conf.py index 4577404ba3..9caa8feae3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -30,7 +30,10 @@ # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['sphinx.ext.napoleon', 'sphinx.ext.autosummary'] +extensions = [ + 'sphinx.ext.napoleon', 'sphinx.ext.autosummary', + 'sphinx.ext.autosectionlabel' +] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates']