Document: draft-ietf-netmod-yang-module-filename
Title: YANG module file name convention
Reviewer: Barry Leiba
Review result: Has Issues
This is simple and useful; thanks for writing it up. I have some comments
about Section 2:
If a revision has an associated YANG semantic version (ysv:version)
then it MAY use the YANG semantic version instead of the revision
date in the file name of a YANG file, where it takes the form:
module-or-submodule-name [['@' revision-date]['#' ysv:version]]
( '.yang' / '.yin' )
E.g., [email protected] or
acme-router-module#2.0.3.yang.
The ABNF allows for both the revision date and the semantic version, together
(and only in that order), though the text implies that they’re mutually
exclusive.
If it’s intended that only one *or* the other be used, as “instead of” implies
you need to adjust the ABNF, for example by replacing
[['@' revision-date]['#' ysv:version]]
with
[(‘@‘ revision-date) / (‘#’ ysv:version)]
If it’s intended that both may be used together, you should probably change
“instead of” and also add an example with both.
And if it’s intended that both may be used together and that they can be in
either order, the ABNF has to change to accommodate the ordering issue.
In short, the YANG semantic version file name scheme is recommended
in order to simplify for module consumers, i.e. to convey
compatibility status at a glance without needing to read the module.
An English nit here: you can’t just “simplify for someone”, as “simplify" needs
a direct object: you have to “simplify something for someone”. Often we use a
placeholder in informal writing, as “in order to simplify things for module
consumers,” but it might be better in a formal specification to rewrite this to
avoid the problem:
NEW
In short, the YANG semantic version file name scheme is recommended,
as its use will convey compatibility status at a glance without the
need to read the module.
END
The last two paragraphs in Section 2 seem at the same time repetitious and
contradictory of what came before. The last paragraph, in particular, confuses
me: earlier you say that you MAY use the semantic version and here you say that
you MUST use it, but then it appears that you can create two files (with the
same content?). I’m not clear on this bit.
_______________________________________________
netmod mailing list -- [email protected]
To unsubscribe send an email to [email protected]
