-
Notifications
You must be signed in to change notification settings - Fork 278
Write ADR for repository library design #1679
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Comments
copy-pasting initial ADR writeup for reference Repository library designContext and Problem StatementThe Metadata API provides a modern Python API for accessing individual pieces of metadata. It does not provide any wider context help to someone looking to implement a TUF repository. The legacy python-tuf implementation offers tools for this but suffers from some issues (as do many other implementations):
Decision Drivers
Considered Options
Decision OutcomeOption 3: Minimal repository abstraction While option 1 might be used temporarily, the goal should be to implement a minimal repository abstraction as soon as possible: this should give the project a path forward where the maintenance burden is reasonable and results should be usable very soon. The python-tuf repository functionality can be later extended as ideas are experimented with in upstream projects and in python-tuf example code. The concept is still unproven but validating the design should be straight forward: decision could be re-evaluated in a few months if not in weeks. Pros and Cons of the OptionsNo repository packagesMetadata API makes editing the repository content vastly simpler. There are already repository implementations built with it (RepositorySimulator in python-tuf tests is an in-memory implementation, while repository-editor-for-tuf is an external CLI tool) so clearly a repository library is not an absolute requirement. Not providing repository packages in python-tuf does mean that external projects could experiment and create implementations without adding to the maintenance burden of python-tuf. This would be the easiest way to iterate many different designs and hopefully find good ones in the end. That said, there are some tricky parts of repository maintenance (e.g. initialization, snapshot update, hashed bin management) that would benefit from having a canonical implementation. Likewise, a well designed library could make some repeated actions (e.g. version bumps, expiry updates, signing) much easier to manage. repository_tool -like APIIt won't be possible to support the repository_tool API as it is but a similar one would certainly be an option. This would likely be the easiest upgrade path for any repository_tool users out there. The implementation would not be a huge amount of work as Metadata API makes many things easier. However, repository_tool (and parts of repo.py) are not a great API. It is likely that a similar API suffers from some of the same issues: it might end up being a substantial amount of code that is only a good fit for one application. Minimal repository abstractionpython-tuf could define a tiny repository API that
python-tuf could also provide one or more implementations of this abstraction as examples -- this could include a repo.py- or repository_tool-like implementation. This could be a compromise that allows:
The approach does have some downsides:
LinksDesign document for minimal repository abstraction |
Great write-up, @jku! I'd love if we had a comprehensive list of both the specific functionality a minimal repository abstraction includes, and leaves to application implementations respectively, and also why. Maybe this is more relevant for the design document than for the ADR. What do you think? |
Oh agreed, I think the ADR is pretty pointless without some kind of design document: this is why the content is just a comment for now... The point about including reasoning for those decisions is good, I'll have to think where and how to do that |
I'm trying to provide the following in the coming days:
This is part of #1136. My current writing is in https://docs.google.com/document/d/1ZsXWMP_JgsI6RLhyiDn1Fr6rSCMFVoYSBwBakMzspjs but it's really not a proper design document yet
The text was updated successfully, but these errors were encountered: