specification has new version

[github-actions]

It seems specification (https://github.com/theupdateframework/specification/blob/master/tuf-spec.md) has new version.
Please review the version.

[joshuagl]

Changes were some cleanup in theupdateframework/specification#195 (diff) and removing ambiguous text related to updating root metadata after an update fails in theupdateframework/specification#196 (diff).

[jku]

Note that this is the first time the CI check ran: Metadata API currently states support for v1.0.19 (vs spec v1.0.28 ) so there's likely more to verify.

This does imply the issue message should list the version numbers :)

[kairoaraujo]

I thought to have the version numbers, but if we don't thread the issue and a new version of the spec is released, it becomes outdated. The idea was to have a generic issue.

I'm thinking about some options:

• Add version number in the title, so one issue every time we have a new spec
• Add a comment with the version if the comment does not exist (maybe a bit tricky)

More suggestions?

[jku]

eh, maybe we let it be and see how it works for a while 🤷

[jku]

Looking at the commits these need review:

• c43045a (tag: v1.0.28) Remove ambiguity in update root after a failed attempt
• d7bc72e (tag: v1.0.27) A round of clean-up/clarifications
• 107be15 (tag: v1.0.26) Clean up "Writing consistent snapshots" section
• 2585a4e (tag: v1.0.25) Explain why we check hashes before signatures
• 8dafd00 (tag: v1.0.24) Clarify optional attributes
• 57f636e (tag: v1.0.23) Add guidance about unknown fields
• adeaea4 Remove outdated terminology from description of ROLE
• 7544c41 Remove redundant MUST statement in "Update the root role"
• c7809e8 Require keyid uniqueness in metadata signatures list
• 6fffd36 Clarify PATHPATTERN wildcards are glob-like
• 4d69ee9 Require role name uniqueness in delegations

EDIT: all reviewed: the one issue is in the next comment

[jku]

8dafd00 (tag: v1.0.24) Clarify optional attributes

This contains

The "path_hash_prefixes" and "paths" attributes are OPTIONAL, if used, exactly one of them should be set.

Metadata API requires exactly one of them.

Specification does not explain what should happen if neither field is set (I've previously thought it meant that everything is delegated but I think was persuaded against this in python-tuf before the spec change... not sure how this mess happened)

[jku]

theupdateframework/specification#200

[MVrachev]

We discussed with @kairoaraujo that I will take this issue while he is focused on working on Warehouse related stuff.

[MVrachev]

Looking at the commits these need review:

• c43045a (tag: v1.0.28) Remove ambiguity in update root after a failed attempt
• d7bc72e (tag: v1.0.27) A round of clean-up/clarifications
• 107be15 (tag: v1.0.26) Clean up "Writing consistent snapshots" section
• 2585a4e (tag: v1.0.25) Explain why we check hashes before signatures
• 8dafd00 (tag: v1.0.24) Clarify optional attributes
• 57f636e (tag: v1.0.23) Add guidance about unknown fields
• adeaea4 Remove outdated terminology from description of ROLE
• 7544c41 Remove redundant MUST statement in "Update the root role"
• c7809e8 Require keyid uniqueness in metadata signatures list
• 6fffd36 Clarify PATHPATTERN wildcards are glob-like
• 4d69ee9 Require role name uniqueness in delegations

EDIT: all reviewed: the one issue is in the next comment

I looked into all changes between our current version 1.0.19 and the current version of the specification 1.0.28 and I agree with Jussi that the only one not fully resolved is:
8dafd00 (tag: v1.0.24) Clarify optional attributes.

It doesn't make sense to have a target file without paths or path_hash_prefixes, so our `python-tuf requirement to have at least one of them set makes sense.

Both with @jku we agreed that we can easily loosen this requirement if when solving theupdateframework/specification#200 it's decided that both of them can be omitted, but for now we decided it's better to stick to our current requirement to have one of them set.