We are using 4 linters: black, isort, pylint and mypy.
It's good if we use one file as a source for truth for all linter
configurations.
I tried multiple ways to use the src_path option,
so we can just call isort without pointing out the target folders, but I was not
successful.
I tried running isort with "isort --settings-path=pyproject.toml"
I got the error:
"Error: arguments passed in without any paths or content."
Additionally, I saw one project with source configuration https://github.com/Pylons/pyramid/blob/master/pyproject.toml,
but they had to give explicit folders too 8061fce297/tox.ini (L26)
and 8061fce297/tox.ini (L66)
It was a similar situation with "check" and "diff".
In the documentation it's said that for both check and diff are not
supported in configuration files.
See:
- https://pycqa.github.io/isort/docs/configuration/options.html#check
- https://pycqa.github.io/isort/docs/configuration/options.html#show-diff
Additionally, in two issues it was confirmed that in integration tests
we should use --check and --diff the way we did until now.
As a result, I moved part of the configuration options for isort inside
pyproject.toml without the actual directories that need to be linted
and "check" and "diff" options.
Signed-off-by: Martin Vrachev <mvrachev@vmware.com>
We are using 4 linters: black, isort, pylint and mypy.
It's good if we use one file as a source for truth for all linter
configurations.
As a first step move black options in pyproject.toml.
I tried multiple ways to use the include option,
so we can just call black --config=pyproject.toml, but I was not
successful. Then I found this comment https://github.com/psf/black/issues/861#issuecomment-680411125
explaining that the path argument is mandatory.
As a result, I will move all configuration options for black inside
pyproject.toml without the actual directories that need to be linted.
Signed-off-by: Martin Vrachev <mvrachev@vmware.com>
This file is out of date to the point of being obsolete. An updated
ROADMAP document would be warmly welcome but an out of date roadmap
is worse than nothing.
Fixes#1525
Signed-off-by: Jussi Kukkonen <jkukkonen@vmware.com>
For users of legacy client (tuf/client/) this is purely a security fix
release with no API or functionality changes. For ngclient and Metadata
API, some API changes are included.
All users are advised to upgrade.
Signed-off-by: Jussi Kukkonen <jkukkonen@vmware.com>
Also add a summary to the page -- unfortunately getting a standard
TOC would require creating a rst page for each class.
Signed-off-by: Jussi Kukkonen <jkukkonen@vmware.com>
This makes the individual pages easier to read.
Use some autodoc configuration so we can have less config
in the automodule/autoclass declarations.
Signed-off-by: Jussi Kukkonen <jkukkonen@vmware.com>
Situation before
* constructor args are not documented
* object attributes are documented
* sphinx cannot show object attribute type annotations
* attribute docs take a lot of vertical space
Now:
* constructor args are documented
* sphinx can show annotated types of constructor args
* class docstring now explains the attributes are the same as
constructor args (and attributes are not explicitly documented)
Signed-off-by: Jussi Kukkonen <jkukkonen@vmware.com>
The v0.18.0 release was made with the changes from #1566, resulting in
a release with sources which don't match the git tag. Rectify this with
a brown bag point release.
Signed-off-by: Joshua Lock <jlock@vmware.com>
Capture discussion around the purpose of the reference implementation.
That we prioritise being an exemplary implementation over being a
pedagogical implementation.
Signed-off-by: Joshua Lock <jlock@vmware.com>
Write a bit more about the two modules, hide the actual TOC to not
repeat (and not have sphinx complain about missing items in TOC)
Signed-off-by: Jussi Kukkonen <jkukkonen@vmware.com>
This allows using existing documentation in the published documentation
without
* moving the existing docs (which would break external links)
* tricks like symlinks that create issues with relative links
Put the api reference files into a subdirectory to avoid polluting the
main docs/ directory.
Include "Installation" and "Instructions for Contributors" in the
published documentation.
Signed-off-by: Jussi Kukkonen <jkukkonen@vmware.com>
* Remove link to outdated roadmap
* Link to maintainers file in the same way as two lines earlier
* Fix formatting issues with code blocks
These fixes allow the installation rst to be used from sphinx sources
and from docs root.
Signed-off-by: Jussi Kukkonen <jkukkonen@vmware.com>
* Improve content
* Make ngclient Updater __init__() visible in docs
* Remove "legacy implementation" (except for the note on API stability)
Signed-off-by: Jussi Kukkonen <jkukkonen@vmware.com>
Add .rst source files for building documentation with
'sphinx'. The two mandatory files are conf.py containing
the build configuration and the master doc file index.rst.
Sphinx uses 'autodoc' to automatically include docstrings.
'autodoc' imports the modules and needs TUF installed in
the environment.
The following command will generate the documentation from the
source files in an html format:
`sphinx-build -b html docs/sphinx/source docs/sphinx/build/html`
Signed-off-by: Teodora Sechkova <tsechkova@vmware.com>
* Update CLI.md
Update the suggested command template for "trust keys", to make it consistent with other examples.
Signed-off-by: hosseinsia <hossein.siadati@datadoghq.com>
* Update docs/CLI.md
Remove the + to avoid confusion.
Co-authored-by: Martin Vrachev <martin.vrachev@gmail.com>
Signed-off-by: hosseinsia <hossein.siadati@datadoghq.com>
Co-authored-by: Martin Vrachev <martin.vrachev@gmail.com>
Updated/removed documented commands and comments which were referencing Python2. Also updated links to documentation referencing Python2 docs (unchanged where needed)
Signed-off-by: Samuel Gregorovic <samuelgregorovic@gmail.com>
Signed-off-by: samuelgregorovic <samuelgregorovic@gmail.com>
After a discussion with Jussi, we realized that there are a couple of
places where we don't want to allow unrecognized fields because the
they are sensitive dictionaries and the specification requires an items
of certain types inside them.
The places where we don't want to allow unrecognized fields are
"keys", "roles", "meta", "hashes" or "targets".
Signed-off-by: Martin Vrachev <mvrachev@vmware.com>
Even though, this ADR documents something already implied in the TUF
spec in [document formats](https://theupdateframework.github.io/specification/latest/#document-formats)
it seems better to document this decision clearly so that it could be
referenced and give an explanation why someone can load a metadata file
with additional unrecognized fields.
Signed-off-by: Martin Vrachev <mvrachev@vmware.com>
Add decision record about the design of de/serialization between
TUF metadata class model and wire line metadata formats.
Chosen option: Serialization and class model are decoupled, but the
class model provides conversion helper methods.
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
Add cli snippet to run black and isort on the command line and
pointers to editor and pre-commit configuration to
docs/CONTRIBUTORS.rst.
Also add .pre-commit-config.yaml to .gitignore for independent
pre-commit configuration.
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
This reverts commit "Add basic pre-commit configuration for
tuf/api/*" (44aea45fd3) in order to
reduce maintenance burdern:
- pre-commit really is a package manager, thus the packages (git
hooks) pulled in via pre-commit would need to be kept up-to-date
and securely so (sic!).
- pre-commit requires contributors to opt-in via "pre-commit
install" regardless, so we might as well ask contributors to add
and tend to the corresponding configuration file on their own.
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
Add optional pre-commit configuration to install and run
auto-formatters when committing new code to tuf/api/*.
Auto-formatters include:
- trailing-whitespace
- end-of-file-fixer
- black
- isort
This commit also adds pre-commit to the dev dependencies
and updates the contributor instructions accordingly.
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
Configure lint build in tox.ini to check if code in tuf/api/* is
formatted according to black and isort style rules:
https://black.readthedocs.io/en/stable/the_black_code_style.htmlhttps://pycqa.github.io/isort/
In addition to our new style guide (#1128) and corresponding linter
configuration, requiring auto-formatting should help to further
reduce reviewing effort. The auto-formatter black was chosen for
the following reasons:
- It seems to be the most popular formatter in the Python ecosystem
- It is well documented including integration instructions with
most of the tools we use (git, GitHub Actions, pylint, a range of
editors, pyproject.toml #1161)
- It checks that the reformatted code produces a valid AST that is
equivalent to the original
- It has almost no ways of customization, which means no
customization effort required, and more (cross-project) style
uniformity, lowering contribution barriers
- It converts single to double quotes, where reasonable, which is
exactly what we recommend
- The style choices it makes seem generally reasonable and don't
conflict with our style guide, except for favoring hanging over
aligned indentation, which is the opposite of what we recommend.
But we are willing to update the adapt our style guide.
Auto-format pre-commit configuration will be added in a subsequent
commit.
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
If you follow the instructions we provide for our contributors in
docs/CONTRIBUTORS.rst your sys.path (used to search for imports)
will put securesystemlib project directory first and tuf directory
second.
This creates a problem with imports from tuf modules because we can
import the wrong file or on relative imports (as currently we
use in the tests when we import utils), the imports cannot be resolved.
If we change the installation order, then tuf directory will be the
first in the import resolution path and those problems will be fixed.
PS: I want to express my gratitude towards Jussi who helped me find
this problem.
Signed-off-by: Martin Vrachev <mvrachev@vmware.com>
Replace mentions of travis/appveyor with GitHub Actions in
governance (contribution) and readme (badges) documents.
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
Use Google style guide with refinements, because the Google style
guide is a comprehensive, well-established style guide that is
mostly based on PEP-8 and was accepted by everyone on the TUF team.
There is no need to replicate these recommendations. However, we do
provide a very slim document with additional refinements, in order
to emphasize on items the we consider especially important, want to
be handled differently, or in one specific way, where the Google
guide would allow multiple.
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
Co-authored-by: Joshua Lock <jlock@vmware.com>
Add MADR that justifies why we want to add custom classes for
complex tuf metadata attributes.
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
Describe pros of developing TUF 1.0.0 in a subdirectory
of the current implementation against the rest of the options.
Signed-off-by: Teodora Sechkova <tsechkova@vmware.com>
