Serious, comprehensive docs on everything

heartsucker commented 7 years ago

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.

JustinCappos commented 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 .

heartsucker commented 7 years ago

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.

heartsucker commented 7 years ago

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:

[x] ASN.1 for all crypto keys
[x] JSON schema and/or examples for JSON encoded metadata
[x] Best practices for using this safely / implementation details

lucab commented 7 years ago

Capturing the other part of my comment above, my wishlist for docs are:

[x] explicitly calling out that this TUF-derived library does NOT interoperate with any other TUF-derived library (this is mentioned in several issues by now, but not in general user docs)
[x] 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
[ ] ~~list of custom renamed fields (e.g. _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.txt~~
[x] other encoding details which cannot be captured by JSON schema (e.g. hexlower and base64 signatures are both "string")

Thanks again for writing this library and for all your feedback leading here!

heartsucker commented 7 years ago

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.

heartsucker commented 7 years ago

Also to include

[x] Deployment considerations: online unclaimed versus offline archive keys for unmaintained projects
[x] Deployment considerations: how to register new developer keys (similar online/offline as above)

heartsucker commented 7 years ago

@lucab Could you review the docs on the develop branch to see if they are sufficient? If so, I will close this issue.

heartsucker commented 7 years ago

Since no one has said anything, I'm closing this.

lucab commented 7 years ago

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.

theupdateframework / rust-tuf

Serious, comprehensive docs on everything #109