specification
specification copied to clipboard
theupdateframework
Need formal specification of TUF
The current specification is too informal: it leaves many details unspecified (e.g. the exact algorithmic flow of a conformant updater, exactly what hashed delegations or consistent snapshots are, etc.).
Ideally, the TUF specification would be much more formal. (We should look into a suitable language.)
We should also unify our many different names for the same thing (e.g. 'consistent snapshots' == 'hashed snapshot trees', 'lazy bin walk' == 'hashed delegations', 'release' == 'snapshot'), and produce a standard glossary.
Ideally, the TUF specification would be much more formal. (We should look into a suitable language.)
I'm not at all in favor of this. Clarity is good, but not from this standpoint. People have to be able to read it. There are guidelines about how to write readable documents of this type and we should follow them.
We should also unify our many different names for the same thing (e.g. 'consistent snapshots' == 'hashed snapshot trees', 'lazy bin walk' == 'hashed delegations', 'release' == 'snapshot'), and produce a standard glossary.
I completely agree. This is a pet-peeve of mine in technical writing. (It's also something I struggled with early on as a writer.)
On Tue, Apr 29, 2014 at 5:04 PM, JustinCappos [email protected]:
Ideally, the TUF specification would be much more formal. (We should look into a suitable language.)
I'm not at all in favor of this. Clarity is good, but not from this standpoint. People have to be able to read it. There are guidelines about how to write readable documents of this type and we should follow them.
Sure, maybe completely formalizing it is a pipe dream, but I think we agree that the current specification can be improved
We should also unify our many different names for the same thing (e.g. 'consistent snapshots' == 'hashed snapshot trees', 'lazy bin walk' == 'hashed delegations', 'release' == 'snapshot'), and produce a standard glossary.
I completely agree. This is a pet-peeve of mine in technical writing. (It's also something I struggled with early on as a writer.)
A good name solves half the problem!
A good name solves half the problem!
Yep, using it everywhere is the most important half.
Justin
On Tue, Apr 29, 2014 at 5:52 PM, JustinCappos [email protected]:
A good name solves half the problem!
Yep, using it everywhere is the most important half.
Yeah :))
For our own sanity (if not that of our readers), we need a page that explains the differences between TUF and PyPI/PyPA glossaries.
I'd also flag uses of the term 'rotate' as a specific concern, especially with TAP 8 looming. We need to be very precise about what is meant.