Closed heartsucker closed 7 years ago
We'd be happy to work with you on this.
On Tue, Jul 11, 2017 at 9:06 AM, heartsucker notifications@github.com wrote:
Right now there's just come cursory stuff, but since TUF is complex, all functions that deal with TUF things really need to explain what and why better. This lib tries to prevent someone from being able to do Bad Things, but I've probably lost perspective on what constitutes a simple mistake because I'm in this too deep. Thus. Way more docs.
— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/heartsucker/rust-tuf/issues/109, or mute the thread https://github.com/notifications/unsubscribe-auth/AA0XDxON0_5BiGqoTD2CVDNuOOZx256kks5sM3NigaJpZM4OUNG5 .
Great! If you and any of the team want to submit PRs, I'll gladly merge them. Most of the docs stuff is actually straight forward and most of the internal types map pretty directly to the TUF metadata/objects/etc. Plus it would be good to have more eyes on this to make sure I'm not doing Bad Things.
Just as a note develop
is relatively stable and all the feature branches get rebased and force pushed, so I'd stay away from those.
As noted in https://github.com/heartsucker/rust-tuf/issues/86#issuecomment-315367884, the definition of done for documentation should include not just example usage of the lib, but also the underlying metadata and operations should someone want to build a lib in another language that can talk to this implementation.
To include:
Capturing the other part of my comment above, my wishlist for docs are:
_type
-> type
, keyid
-> key_id
) as there is no upstream JSON schema to diff against, and there are multiple renamed fields compared to TUF spec.txtThanks again for writing this library and for all your feedback leading here!
explicitly calling out that this TUF-derived library does NOT interoperate with any other TUF-derived library
This is reasonable. I can make a note that historically the spec was so strict that everything could interop and that now that it has been moved into a spec that describes how a framework should look and not a spec for the exact framework itself that there will be differences between implementations. And a kind suggestion to fork if they need interop. :)
describing this as an "opinionated TUF library", "TUF-derived library", "TUF-based library" or whathever is suitable to reflect the above point and the fact that TUF doesn't have any interop baseline
Assuming the spec continues the way it is, this lib will be more than "Based on a True TUF Story." If it follows the spec, the it is TUF. Just at some point the spec was so rigid that everything that followed it could interop.
list of custom renamed fields
This should be obvious from the JSON schema or examples I provide as well as the fact that I warn about lack of interoperability. In the Uptane spec (a TUF variant / extension), there is no mandatory schema. There is only suggested ASN.1 modules that describe metadata that could be used. Keeping tabs on all the way this deviates from the reference implementation feels overkill in that there already are enough differences that there is no way that rust-tuf
and the Python tuf
package could work together.
Also to include
unclaimed
versus offline archive
keys for unmaintained projects@lucab Could you review the docs on the develop
branch to see if they are sufficient? If so, I will close this issue.
Since no one has said anything, I'm closing this.
Posthumous comment: I quickly skimmed the commit in develop
and I'm happy with the additional docstrings, in particular the ones in src/lib.rs
.
Right now there's just come cursory stuff, but since TUF is complex, all functions that deal with TUF things really need to explain what and why better. This lib tries to prevent someone from being able to do Bad Things, but I've probably lost perspective on what constitutes a simple mistake because I'm in this too deep. Thus. Way more docs.