Here is the list of all breaking API changes:
1) The "role" and "key" arguments in "Root.add_key()" are in reverse
order - "key" becomes first and "role" second.
2) "Root.remove_key()" has been renamed to "Root.revoke_key()".
3) The "role" and "keyid" arguments in "Root.revoke_key()" are in
reverse order - "keyid" becomes first and "role" second.
4) The "role" and "key" arguments in "Targets.add_key()" are in reverse
order - "key" becomes first and "role" second.
5) "Targets.remove_key()" has been renamed to "Targets.revoke_key()".
6) The "role" and "keyid" arguments in "Targets.revoke_key()" are in
reverse order - "keyid" becomes first and "role" second.
7) In both methods "Targets.add_key()" and "Targets.revoke_key()" the
"role" argument becomes an optional with a default value of None.
Those changes are made in an effort to make those methods logical
for both cases when standard roles and succinct_roles are used.
The "Root" API change was done in order to preserve naming and argument
order consistency with "Targets" API.
Signed-off-by: Martin Vrachev <mvrachev@vmware.com>
This blog post explains details around the use of respository
simulator, `--dump` option and test cases with expired metadata
Fixes#1885
Signed-off-by: Ivana Atanasova <iyovcheva@vmware.com>
The class docstring for FetcherInterface needed to clearly state that
only _fetch() had to be implemented in it's implementation. This is
because the public API of the interface is implemented already.
Signed-off-by: Abhisman Sarkar <abhisman.sarkar@gmail.com>
Mention how to use verify_release with the recently added --sign
option to create signatures for a verified release.
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
Since #1971 ci and cd workflows run independently of each other,
each of them also calling the test workflow.
This patch updates RELEASE.md to match the new setup.
It also fixes a (twice) broken link.
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
Change RELEASE.md to include instructions to trigger and review
auto release workflow (CI/CD).
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
verify-release
* Builds a release from current commit
* Notifies if git describe does not match built version
* Notifies if built version is not the latest GitHub or PyPI version
* Asserts that the GitHub and PyPI release artifacts match the built
release artifacts
This should be useful after release as any developer (or a CI job) can
easily verify that the release matches the sources in git.
Note that the last checks currently fail as the 1.0 build was not
reproducible. They should succeed after next release.
Signed-off-by: Jussi Kukkonen <jkukkonen@vmware.com>
* version number is single sourced now
* Mention that using pip against test.pypi.org is unsafe
* Fix some filenames in the examples
Signed-off-by: Jussi Kukkonen <jkukkonen@vmware.com>
Minima theme by default adds all files in blog root (docs/) as links in
the header. This looks ridiculous in our case: let's just have a link to
blog front page.
Signed-off-by: Jussi Kukkonen <jkukkonen@vmware.com>
Add config for GitHub Pages so that we can use it as a project blog.
* _config.yml is jekyll configuration
* index.md contains description and title for the blog main page.
* Any files matching "_posts/YYYY-MM-DD-TITLE.md" are considered posts
The Github Pages configuration only allows "/" or "/docs/" as the Jekyll
root directory: The clutter in docs/ is annoying but otherwise this is a
very easy setup.
Signed-off-by: Jussi Kukkonen <jkukkonen@vmware.com>
Change docs in preparation of close v1.0.0 release.
- Remove important notice about upcoming 1.0.0 release from README
- Reword 1.0.0-ANNOUNCEMENT.md to not sound outdated after release
Co-authored-by: Joshua Lock <jlock@vmware.com>
Signed-off-by: Jussi Kukkonen <jkukkonen@vmware.com>
Update README.md#Acknowledgements
- Reword to acknowledge maintainer contributions as well
- Remove names that are mentioned in maintainers document
- Remove duplicate Konstantin Andrianov
Santiago Torres-Arias, Sebastien Awwad, Trishank Kuppusamy,
Vladimir Diaz)
- Add new significant contributors
(Ivana Atanasova, Kairo de Araujo, Martin Vrachev)
Remove unmaintained AUTHORS.txt, which lists many individuals and
organisations that are/were not affiliated with 'python-tuf', but
other projects in the TUF ecosystem (Thandy, Notary, etc.) and
thus is not suited for this repository.
-> theupdateframework.io#38
Caveats:
- Significant contributors means top ~20 committers sorted by
commit count (`git shortlog -s`).
- The Acknowledgements section might miss significant contributors,
if they contributed by other means than git commits in this repo.
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
As discussed in detail in #1793, maintainer-level (GitHub)
permissions should be granted to those who need them, i.e. who
actively maintain the project at the moment.
The MAINTAINERS.txt file should reflect that state.
It will be reviewed regularly (#1803), and can be changed (e.g.
reverted to a prior state) at any time as need arises.
To express our appreciation for past efforts, we might use the
Acknowledgement section of the README, and also update it
regularly.
In the case of this update: Big kudos to @awwad, @SantiagoTorres
and @sechkova for all their valuable contributions to python-tuf!
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
This is an ugly hack to also resolve the link when the document is
rendered in GitHub, where it is likely to be browsed, because it is
the community standard location for a GitHub repo's contributing
docs.
Coordinate with #1849 to better separate RTD docs with GitHub docs
in the future.
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
Move release signature verification instructions to bottom of
install docs. The doc is short, so the section is still prominent
enough for promoting verification, but does not break the reading
flow as much anymore.
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
Make contributing document header sentence case for consistency
with other docs and shorten menu name in side navbar to stand out
less.
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
Replace custom installation section in contribution docs with
pointer to updated installation documentation.
Also configure sphinx autosectionlabel for cross-document refs.
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
Update severely outdated installation documentation.
- Simplify "Simple Installation" section
- Update "Release Verification" section to actually verify a tuf
release and with a key of an active maintainer
- Update and simplify section about non-python dependencies
(just point to installation instructions for underlying crypto
backends, they are up-to-date and have become a lot easier)
- Add "Development installation" section
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
Remove obsolete docs/images directory which contains unused
variants of the logo. The canonical location of TUF logos is
theupdateframework/artwork, which has high-resolution formats (png
and svg) for all variants of the logo.
Also see https://github.com/theupdateframework/artwork/pull/3.
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
Remove documentation for legacy client, repository/developer tool
and command line tools, which will be removed in subsequent
commits.
See #1797 and #1798 for replacing ATTACKS.md and QUICKSTART.md.
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
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 <kdearaujo@vmware.com>
This commit adds to the RTD the links references to source code
examples.
The examples are added to TUF ngclient Updater, Metadata and API
reference.
includes a seed for examples/README.md
Signed-off-by: Kairo de Araujo <kdearaujo@vmware.com>
Remove old doc/tuf-spec* documents, which are merely pointers to
the theupdateframework/specification repo (created in late 2017).
They were likely kept in place to avoid 404s of old links, but the
up-to-date TUF specification location should be discoverable enough
to get rid of the pointers.
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
This commit is a simple trailing whitespaces cleanup from the files
inside the docs folder.
The files on docs sub-directories are not part of this commit.
The docs/SECURITY.md will be removed on PR #1769
Signed-off-by: Kairo de Araujo <kdearaujo@vmware.com>
These documents describe TUF server (mostly key management) and
client (mostly targets delegation) operations referring to a long
outdated TUF specification and suggesting the use of long gone
python-tuf tooling.
A deprecation disclaimer was added to the document headers already
in 2014 (see b84225f3e7).
I think it is safe to remove them.
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
Update sphinx/rtd conf to display inherited members. This is
enabled specifically for the newly added `expires` property,
which has a useful code snippet in the docstring.
We don't display
- them on the tuf.api automodule overview page (avoid duplicates)
- members inherited from the built-in Exception class
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
This will be the final release of python-tuf that includes the
legacy implementation code. Please see the [*1.0.0
announcement*](1.0.0-ANNOUNCEMENT.md) page for more details about
the next release and the deprecation of the legacy implementation,
including migration instructions.
Co-authored-by: Jussi Kukkonen <jkukkonen@vmware.com>
Signed-off-by: Jussi Kukkonen <jkukkonen@vmware.com>
Rename test files testing the old code by adding an "old" suffix.
This is done, so we can easily exclude them from linting.
Signed-off-by: Martin Vrachev <mvrachev@vmware.com>
In addition to multiple smaller review fixes:
* Explain how the proposed library is minimal: more specific
functionality may be added as we get more experience
* Explain what a concrete Repository implementation must implement
(details are obviously subject to change but this is what the
current prototype requires)
Signed-off-by: Jussi Kukkonen <jkukkonen@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.
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>
