Version release strategy for TUF...

[JustinCappos]

We would like to make it possible to make changes to the TUF specification in a way that:

1. makes it easy to timestamp and archive versions of the TUF specification in semver style

2. enables there to be working drafts of new TUF versions. In particular, changes that are backwards incompatible (major), backwards compatible (minor), and typo fixes (patch) in parallel.

3. the manual effort to keep everything consistent is minimized.

To achieve these goals, I propose that there are three different "living" documents for the TUF spec (major-draft, minor-draft, and latest) that are edited in a very specific way. To provide a conceptual model that is easy to understand, the documents form a hierarchy, major (backwards-incompatible) -> minor (backwards compatible) -> patch (typo fixes). To minimize manual effort, changes in the document are only made to the drafts that need to be changed. To achieve this, all changes to lower documents propagate to higher documents. For example, if a typo is fixed in a patch, both the minor and major draft versions are updated to fix the typo. If a backwards incompatible change is made to the specification, only the major document changes.

Using such a hierarchy, it requires little effort to apply the correct semver number to a new release of TUF. Simply take the prior version and increment the version number that applies to the appropriate patch, while zeroing out all lower version numbers. For example, when at version 2.4.3 of the specification and accepting a minor draft, the new version number is 2.5.0. In all cases, the newly approved draft becomes the latest. If the major draft is accepted, then the previous major draft also becomes the new minor-draft and latest.

However, this does not handle the question of when to release a new version of the specification. A new version of the specification is released in two scenarios. First, whenever a patch change is accepted, the specification number is released. Second, when there is consensus in the community that a specific minor version or major version is ready, this is accepted and finalized.

[lukpueh]

I like the concept, but I see some operational difficulties if we indeed have multiple documents:

1. Strictly propagating changes from lower to higher documents seems onerous and error-prone, especially if lower patches can't be applied directly to a higher document, because of conflicting changes.
2. The setup seems like a higher barrier for contribution. A contributor needs to have 3 different documents in their mental model (in addition to the latest stable version), and needs to know beforehand if a planned change is major, minor or patch.
3. It is harder to trace back changes, if the relevant git history is spread across multiple documents.

If we choose a concept like @JustinCappos suggests, I'm in favor of using different git branches that all work on the same document instead of different documents. This only solves (3), but maybe we can use something like gitflow to mitigate (1) and (2).

[JustinCappos]

Should we PoC a version of this with gitflow? I'm all for making this as simple as possible.

I'm not sure how this would work in the hopefully rare case where there is a conflict in changes.

[lukpueh]

A gitflow-like approach could be to have 4 permanent branches (master, major, minor and patch ). Contributors work on feature branches and submit PRs against major, minor or patch depending on the type of their PR.
Whenever we merge from major, minor or patch into master we bump the corresponding version number, so that master always points to the latest stable version of the spec.

This still requires manual syncing:

• When a feature branch gets merged into major, minor or patch, the change needs to be adopted in higher number branches, and
• when one of major, minor or patch gets merged into master, lower number branches need to be reseted.

The manual syncing and the fact that either the contributor or at least the maintainer need to coordinate if a change from a feature branch should go into major, minor or patch worry me a little bit.

[lukpueh]

A stripped down alternative that is less flexible in regards to parallel work on major, minor, patch would be to only have master and draft. Like above master always points to the latest stable release and each merge into master must bump the version number.
Contributors either PR their features against draft (for major- and minor-release work), or directly against master (for patch-release work).

This makes syncing a lot easier, because we only need to sync master back to draft, in case of a patch release.
The downside is reduced flexibility in regards to parallel work on major and minor, but I don't know if that actually is a problem.

[lukpueh]

I'd love to see others weigh in (cc @mnm678, @trishankatdatadog, @joshuagl).

[trishankatdatadog]

What do people think about committing things directly to branches corresponding to the version numbers, like 1.1.0 and 2.0.0 and so on? I don't expect a lot of parallel updates to the spec, and as long as we review and merge PRs quickly enough, this should work.

[lukpueh]

Thanks for chiming in, @trishankatdatadog. What would be the advantage of your proposal over either of mine above?

[jhdalek55]

Mine is probably the minority view on these issues, but I am thinking about the less-git-savvy person (someone not unlike myself) who wants to contribute a correction or addition. Will it be clear which version to submit a change to? And will there be an explictly clear criteria for what corrections fit within these specifications, particularly between the patch and the minor draft? I'm not sure its a good idea to leave such a decision to the contributor.

[lukpueh]

I agree with you 100%, @jhdalek55, and I think the arguments you make apply to the git-savvy person just as well (see my similar concern (2) above in #73 (comment), which was in reply to a not git-based strategy).

I think my proposition from #73 (comment), i.e. master and draft branches, is the way to go. Its main downside is the reduced flexibility in parallel work on major and minor releases, which, as @trishankatdatadog claims, should not be a problem. Besides, parallel work would still be possible by coordinating the feature branch PRs.

[trishankatdatadog]

@lukpueh Yes, on second thought, it seems to me that your proposal is operationally the simplest.

[joshuagl]

FWIW I agree that striving for operational simplicity is the best approach. The process can evolve as gaps become apparent in use, it's usually harder to rein in an unwieldy process than it is to evolve a simple one.