Document: draft-ietf-netmod-rfc8407bis Title: Guidelines for Authors and Reviewers of Documents Containing YANG Data Models Reviewer: Joseph Touch Review result: Ready with Nits This document has been reviewed as part of the transport area review team's ongoing effort to review key IETF documents. These comments were written primarily for the transport area directors, but are copied to the document's authors and WG to allow them to address any issues raised and also to the IETF discussion list for information. When done at the time of IETF Last Call, the authors should consider this review as part of the last-call comments they receive. Please always CC tsv-art@xxxxxxxx if you reply to or forward this review. There is very little in this document of specific relation to transport protocols, with the exception of the discussion of security in terms of SSH, TLS, and QUIC. That list should be augmented to include DTLS. SSH is more of a security tunnel than a secure transport layer. In that context, NETCONF is defined over SSH and TLS (RFC6241), but not QUIC. RESTCONF is exclusively defined over HTTP, TCP, and TLS (RFC8200), but not QUIC -- at least not yet. draft-ietf-netconf-over-quic-02 proposes it, but it has not yet been published. Keeping QUIC here seems like it would require a reference to that draft. Some other observations, not transport related: - This doc should help address the (IMO) oversight in RFC 7950 not obsoleting RFC 6020. RFC 7960 clearly indicates (Sec 1.1) that it addresses ambiguities and defects in 6020. There should not be a reason to continue to encourage both 1.0 and 1.1 YANG specifications equally in this document to perpetuate that confusion. - This document should more clearly state that it is addressing how to create RFCs describing YANG models; much of the advice is not relevant if the resulting document is not an RFC (or rfc-to-be as an I-D). - To the previous point, I recommend this being clarified as” Guidelines for Authors and Reviewers of RFCs Containing YANG Data Models”. All references to I-Ds or the generic “document” throughput should be replaced with “RFC”. - All instructions specific to writing RFCs or IDs already contained elsewhere, such as including boilerplate, following line length limits, etc., should be removed; those already appear elsewhere. That includes the beginning of Sec 3 and all of 3.1 and 3.3. 3.7 should focus on the way in which Security considerations are written for YANG modules, not as much on the fact that a security consideration section is needed (it is for all RFCs, again, as established elsewhere). None of these sections should restate the fact that the section is required by RFC rules. - Some of the more obscure rules here should have explanations – e.g., limiting identifiers in published modules to 64 chars or less per, e.g., RFC7950 Sec 6.2 establishing 64 as MUST be supported and longer as optionally supported. On a final note, I’ll ask this but – to be clear – I’m not positive I’ll get the terminology correct. I didn’t notice a discussion on the importance of using leafrefs rather than copies of the same leaf type, e.g., where instances of the former must refer to valid values of the latter. That includes the importance of using relative paths in leafrefs, to ensure a module instance can be instantiated in another module at an arbitrary level of nesting. -- last-call mailing list -- last-call@xxxxxxxx To unsubscribe send an email to last-call-leave@xxxxxxxx
