Version 1.0 release strategy

[joshuagl]

We have a loosely communicated intent to ship python-tuf 1.0 with only the new/refactored code (metadata API + ngclient + ???). We should define what that release looks like, including accounting for:

• Communicating deprecation expectations with regards the legacy code
  • ADR 2 indicates legacy code will be supported on a best-effort basis, but this has not been communicated to users of python-tuf

  • "Support for older releases: Bugs reported with tuf versions prior to 1.0.0 will likely not be addressed directly by tuf’s maintainers. Pull Requests to fix bugs in the last release prior to 1.0.0 will be considered, and merged (subject to normal review processes). Note that there may be delays due to the lack of developer resources for reviewing such pull requests."

• What the feature complete state looks like for a python-tuf 1.0 release? Must python-tuf 1.0 provide feature parity with the legacy code?

[lukpueh]

This is a list of items that I think should and are feasible to be in 1.0.0 by the tentatively scheduled release date end of 2021 / early 2022, plus a rough list of TODO items to get to 1.0.0. Feel free to comment, add, remove and help break down the items in both lists.

Feature set of 1.0.0

• feature complete client
• client API docs on RTD (#1595, #1601)
• client tutorial/example (#1518)
• metadata API
• metadata API docs on RTD (#1600, #1595, #1602)
• no repository tool
  NOTE: It is not feasible to have a stable repository tool by the planned 1.0.0 release date. I suggest we publicly express our intent to provide one post-1.0.0, and until then provide example code that uses the metadata API for all repo activities.
• repository tutorial/example based on metadata API
  NOTE: The main usage scenarios are described in the advanced tutorial and in this usage scenario draft document. Plus the repo editor demonstrates how to use the metadata API for this purpose (its generic UI aspect may be ignored).
• no legacy code
• 1.0.0 release announcement plus migration document with the following contents:
  • planned 1.0.0 release date
  • link to ADR 2 and the fact that pre-1.0.0 code will remain available and be supported on a best-effort basis
  • list of what will be in 1.0.0 and what won't (basically this list)
  • links to client example code and repository tutorial (see corresponding items above)
  • an explanation how a generic from-legacy-to-new migration guide is not feasible, due to varying TUF usage
  • our word that we are contacting our users individually to help them migrate
  • an offer to all our users that we haven't contacted, to reach out to us so that we can help them migrate

TODO:

• review/create/associate/resolve issues for items above, maybe re-use 1.0.0 GitHub project to manage?
• publish 1.0.0 announcement/migration guide soon
• post link to 1.0.0 announcement/migration guide on slack, mailing list, theupdateframework.io and on top of python-tuf#README
• contact known adopters individually and offer help

[joshuagl]

There were a couple of items on my "before 1.0" bucket list:

• move to automated (SLSA compliant) release builds prior to 1.0 (Automated release builds #1550)
• figure out how to keep in synch with the spec and better indicate current spec compliance (Develop a process for keeping metadata.SPECIFICATION_VERSION up-to-date #1598)

[lukpueh]

adding more issues to the bucket list, based on my suggestions from above...

• docs: tutorial/example for ngclient Updater #1518
• Docs: Add repository tutorial based on metadata API #1673
• Add 1.0.0 announcement / migration help #1676
• Metadata API: Consider removing 'update()' methods #1627
• Metadata API: Improve docstrings language #1600
• docs: standardize how we refer to methods in docstrings #1595

[MVrachev]

More issues on the bucket list from me:

• ngclient: review argument names #1638
• metadata API: avoid raising securesystemslib exceptions #1646
• ngclient: should clean temp file if write fails #1575
• metadata API: TargetFile.custom is not visible in documentation #1602
• What to do with tuf/exceptions before 1.0.0? #1729
• Metadata API: rethink the expiry related API #1727
• review/document client exceptions #1312
• Review all TODO items in the new implementation prior to 1.0.0 #1764

[jku]

Probably:

• ngclient: consistently encode URLs #1634

[joshuagl]

As TODO items:

• have a look into the specification to figure out which version of it the specification the new code actually supports

Relates to #1598

[jku]

Lukas just created a 1.0.0 blockers label. Let's agree on some rules though... my suggestion:

• anyone (with label permissions) can add/remove issues to label, or suggest additions here
• when issues are added/removed, they should be announced in a comment here so others are notified

we should aim to only include things that are required to get 1.0 released -- fixing other things is still ok but they don't need the label.

[jku]

• Added blocker specification has new version #1763

[MVrachev]

More issues on the bucket list from me:

• ngclient: review argument names #1638
• metadata API: avoid raising securesystemslib exceptions #1646
• ngclient: should clean temp file if write fails #1575
• metadata API: TargetFile.custom is not visible in documentation #1602
• What to do with tuf/exceptions before 1.0.0? #1729
• Metadata API: rethink the expiry related API #1727
• review/document client exceptions #1312
• Review all TODO items in the new implementation prior to 1.0.0 #1764

I am going to label the yet unresolved issues from my list as blockers.

[jku]

Added (ngclient) exceptions tweaks as blockers:

• ngclient: throws securesystemslib errors #1761
• ngclient: decide what to do with requests (Fetcher impl) errors #1714

[jku]

I'd really like these... but maybe not release blockers in the end? @joshuagl opinions?

• Automated release builds #1550, Verifiably reproducible build artefacts #1269
• ngclient: Test against other implementations #1756

Added as blocker:

• ngclient: consistently encode URLs #1634
• docs: relative links in README 404 on PyPI project page #1739
• Remove "legacy code" #1745 <- this one is big and should be started and split into parts ASAP: getting docs etc in order might take a while

[jku]

This one I think we should work on at least far enough that we know how it's going to be solved: if Metadata API does not break as result, it could wait until after 1.0?

• Metadata API: Provide a way to validate object when serializing to dictionary #1696

[jku]

Opinions on this -- maybe should be in 1.0?

• Client explicitly asks server to not compress data #1251

EDIT: Added as blocker

[joshuagl]

I'd really like these... but maybe not release blockers in the end? @joshuagl opinions?

• Automated release builds #1550, Verifiably reproducible build artefacts #1269
• ngclient: Test against other implementations #1756

Agreed. These are important and nice to have for 1.0 but not blockers.