We (authors/contributors) have discussed this issue in the last couple of weekly meetings and come up with the following. We'd like to hear back from the WG before updating the draft.
For sub-modules: 1) No revision-label is OK 2) Same revision-label scheme as including module is OK, but different revision-label space for submodules 3) Sub-modules can use different scheme as including module. By default (no revision-label scheme extension statement), submodules use same scheme as including module. Different submodules could use different schemes. 3) is not unanimous. Why would submodules use a different scheme as including module? But since allowing this seems to have a small cost, it doesn't seem to do any harm. Here's the proposed text: i) Replace MUST by SHOULD for include of submodules by revision-date. https://tools.ietf.org/html/draft-ietf-netmod-yang-module-versioning-00#section-3, replaced MUST by SHOULD below and added some text: A module's name and revision date identifies a specific immutable definition of that module within its revision history. Hence, if a module includes submodules then the module's "include" statements SHOULD use "revision-date" substatements to specify the exact revision date of each included submodule. ADDED TEXT: When a module does not include its submodules by revision-date, the revision of submodules used cannot be derived from the including module. If the revision of submodules is needed, mechanisms such as YANG packages and YANG library can be used. https://tools.ietf.org/html/draft-ietf-netmod-yang-module-versioning-00#section-7.1, replaced MUST by SHOULD and modified existing text as suggested in email discussion. OLD TEXT: A module that includes submodules MUST use the "revision-date" substatement to include specific submodule revisions. Changing a module's include statements to include different submodule revisions requires a new revision of the module. NEW TEXT: A module that includes submodules SHOULD use the "revision-date" substatement to include specific submodule revisions. The revision of the including module MUST be updated when any included submodule has changed. The revision-label substatement used in the new module revision MUST indicate the nature of the change, i.e. NBC, BC or editorial, to the module's schema tree. ii) Change text which talks about revision-labels for submodules, https://tools.ietf.org/html/draft-ietf-netmod-yang-module-versioning-00#section-3.3: OLD TEXT: The revision date and revision label within a submodule's revision history have no effect on the including module's revision. Submodules MUST NOT use revision label schemes that could be confused with the including module's revision label scheme. NEW TEXT: Submodules MAY use a revision label scheme. When they use a revision label scheme, submodules MAY use a revision label scheme that is different from the one used in the including module. The revision label space of submodules is separate from the revision label space of the including module. A change in one submodule MUST result in a new revision label of that submodule and the including module, but the actual values of the revision labels in the module and submodule could be completely different. A change in one submodule does not result in a new revision label in another submodule. A change in a module revision label does not necessarily mean a change to the revision label in all included submodules. Regards, Reshad (on behalf of the group). On 2020-05-13, 5:25 PM, "Sterne, Jason (Nokia - CA/Ottawa)" <jason.ste...@nokia.com> wrote: The example we've been using to discuss this is an editorial type change in 2 submodules (moving a leaf between them with no changes to their definition or the schema). But if we consider an example where schema actually changes (in a part that is defined in a submodule), then it does seem reasonable that the module version should also change. So (A) is probably the right answer here. But it does have a potentially confusing consequence: two YANG files could be identical except for an extra revision statement. It may appear that someone incorrectly bumped a version when there was no change, until you notice that "oh, this module includes submodules - one of those must have changed". Jason > -----Original Message----- > From: Reshad Rahman (rrahman) <rrah...@cisco.com> > Sent: Wednesday, May 13, 2020 4:52 PM > To: Sterne, Jason (Nokia - CA/Ottawa) <jason.ste...@nokia.com>; Martin > Björklund <mbj+i...@4668.se> > Cc: netmod@ietf.org > Subject: Re: [netmod] Revision labels for submodules > > Hi Jason, > > Is your question of option A v/s B just for the case where the schema > represented by the module does not change? > > If the schema changes, even if the module didn't change, the revision-label > has to be updated to indicate the change. > If the schema didn't change, I'd go with editorial revision-label update as (I > think) Martin suggested. > > Regards, > Reshad. > > On 2020-05-13, 1:30 PM, "Sterne, Jason (Nokia - CA/Ottawa)" > <jason.ste...@nokia.com> wrote: > > So that's the part I'm not sure of. > > If a leaf moves between submodules, and the module file doesn't change > in any way (as we've said is possible and should be allowed), do we mandate > that the module version changes? This is up to us to define IMO > > (A) the module version has a scope that includes the module and all > submodules > (B) the module version has a scope that is just the module file contents > > I'm on the fence between those two. (A) could make sense but it does > mean that someone comparing two versions of the just the module file itself > may see no difference whatsoever between them except the addition of a > new version statement. > > Jason > > > -----Original Message----- > > From: Reshad Rahman (rrahman) <rrah...@cisco.com> > > Sent: Wednesday, May 13, 2020 12:46 PM > > To: Sterne, Jason (Nokia - CA/Ottawa) <jason.ste...@nokia.com>; > Martin > > Björklund <mbj+i...@4668.se> > > Cc: netmod@ietf.org > > Subject: Re: [netmod] Revision labels for submodules > > > > Hi Jason, > > > > > > On 2020-05-13, 11:50 AM, "Sterne, Jason (Nokia - CA/Ottawa)" > > <jason.ste...@nokia.com> wrote: > > > > Hi guys, > > > > As someone who is heavily involved in the development of an > extensive > > YANG model comprised of submodules, I'm not a fan of mandating that > > include by revision is mandatory for submodules. It may indeed be a > good > > idea (so perhaps SHOULD is fine) but I can see it causing problems on the > > implementation side. > > > > The primary development of a data model may be distributed out to > > submodules and the main module may only be a top level container for > the > > submodules (and rarely touched). This would suddenly create an > ordering > > dependency in the release process that requires the main module file to > > systematically be updated after all development of the submodules is > halted. > > Then the results of the submodules has to be used to then go update > the > > module. Solvable - yes, but folks who work on large scale projects will > know > > that suddenly requiring that type of development process change isn't as > > easy as it may sound on paper. > > <RR> I can see why you wouldn't want to modify all your include by- > revision > > statements. But you would still need to update the module revision- > label > > based on changes done in the included submodules. > > > > Regards, > > Reshad. > > > > It is possible to manage the "packaging" of submodules and modules > out > > of band or other mechanisms. > > > > OpenConfig, for example, uses submodules but does not currently > include > > by version. I'm not proposing this is ideal. But I think we should leave it > as > > acceptable. > > > > Rgds, > > Jason > > > > > -----Original Message----- > > > From: Reshad Rahman (rrahman) <rrah...@cisco.com> > > > Sent: Tuesday, May 12, 2020 9:46 AM > > > To: Sterne, Jason (Nokia - CA/Ottawa) <jason.ste...@nokia.com>; > > Martin > > > Björklund <mbj+i...@4668.se> > > > Cc: netmod@ietf.org > > > Subject: Re: [netmod] Revision labels for submodules > > > > > > Hi Jason, > > > > > > On 2020-05-09, 12:52 PM, "Sterne, Jason (Nokia - CA/Ottawa)" > > > <jason.ste...@nokia.com> wrote: > > > > > > Hi Martin, > > > > > > Your approach sounds good to me. I was forgetting about the > > "editorial" > > > level of change (e.g. the 3rd part of SemVer). So I agree that moving > a > > leaf > > > would be an editorial change in both submodules. > > > > > > But what if a module is not doing include by revision? It may > indeed > > make > > > sense to include by revision but it isn't mandated. For sake of > argument > > here > > > what if the module itself didn't change at all in this case? > > > It is now mandated in section 3 of draft-ietf-netmod-yang-module- > > > versioning-00. > > > > > > > > > It *feels* like the right thing to do here is to consider the module > > overall > > > to have an editorial change. > > > > > > The revision statement of sub-modules has a scope of the file (the > > sub- > > > module). It isn't clear to me whether the revision of a *module* has > a > > scope > > > that includes all sub-modules or if it is just a scope of the module > file. > > But we > > > could clarify that as part of this work. > > > Because of include by revision, the module would have to change to > > include > > > a different revision of a sub-module. > > > > > > Regards, > > > Reshad. > > > > > > Jason > > > > > > > -----Original Message----- > > > > From: Martin Björklund <mbj+i...@4668.se> > > > > Sent: Saturday, May 9, 2020 11:54 AM > > > > To: rrah...@cisco.com > > > > Cc: netmod@ietf.org; Sterne, Jason (Nokia - CA/Ottawa) > > > > <jason.ste...@nokia.com> > > > > Subject: Re: [netmod] Revision labels for submodules > > > > > > > > "Reshad Rahman (rrahman)" <rrah...@cisco.com> wrote: > > > > > Hi, > > > > > > > > > > On 2020-05-08, 5:12 PM, "Martin Björklund" > <mbj+i...@4668.se> > > > wrote: > > > > > > > > > > Hi, > > > > > > > > > > "Reshad Rahman (rrahman)" <rrah...@cisco.com> wrote: > > > > > > Hi, > > > > > > > > > > > > This came up during this week's meeting. We briefly > discussed > > > whether > > > > > > there's a need to version sub-modules or can we restrict > > versioning > > > to > > > > > > modules only. We would like to hear from the WG on this, > > > especially > > > > > > those with experience managing sub-modules. > > > > > > > > > > Yes I think this is needed. At tail-f, there are several > modules > > with > > > > > many submodules. These modules always use include by > > revision, > > > and > > > > > always the main module is always uddated when any > submodule > > is > > > > > updated. It doens't make much sense IMO to not use > include by > > > > > revision. > > > > > > > > > > > For completeness, below is an update from Jason in > github: > > > > > > My initial reaction is that we should not preclude the use > of > > > revision > > > > > > label with a submodule. Submodules have their own > version > > > today. The > > > > > > trick is to define (or explicitly say it is out of scope) > whether a > > > > > > module version must change if any underlying submodule > > versions > > > > > > change. That gets difficult if you consider simply moving a > leaf > > > from > > > > > > one sub-module to another (without changing anything > else > > about > > > it - > > > > > > its context, etc). > > > > > > > > > > Why would this be difficult? The revision date is updated on > any > > > > > editorial change (see 7.1.9 of RFC 7950). So if a leaf gets > moved > > > > > from submodule A to submodule B, then their revisions are > > udpated, > > > and > > > > > hence the module's include-by revision is udpated, and > hence > > the > > > > > module's revision ois updated. > > > > > > > > > > I think what Jason meant is that by moving a leaf between > > > submodules, > > > > > it's possible the module's schema didn't change. > > > > > So yes revision date is updated, but you can't blindly update > the > > > > > revision-label. > > > > > > > > Why not? > > > > > > > > > > > > /martin > > > > > > > > > > > > > > > > > > Regards, > > > > > Reshad. > > > > > > > > > > /martin > > > > > > > > > > > > > > > > > > > > > > > > > > > Regards, > > > > > > Reshad. > > > > > > > > > > > > On 2020-03-27, 5:44 PM, "netmod on behalf of Reshad > > Rahman > > > > (rrahman)" > > > > > > <netmod-boun...@ietf.org on behalf of > > > > > > rrahman=40cisco....@dmarc.ietf.org> wrote: > > > > > > > > > > > > Hi, > > > > > > > > > > > > https://github.com/netmod-wg/yang-ver-dt/issues/49 > > > > > > > > > > > > o 3.3 > > > > > > > > > > > > Submodules MUST NOT use revision label > schemes > > that > > > could > > > > > > be > > > > > > confused > > > > > > with the including module's revision label > scheme. > > > > > > > > > > > > Hmm, how do I ensure that this MUST NOT is > handled > > > > > > correctly? > > > > > > What > > > > > > exactly does "could be confused with" mean? > > > > > > > > > > > > Good point. What was meant by that the label space for > > > modules and > > > > > > sub-modules are orthogonal. e.g. the sub-module and > > module > > > both > > > > have > > > > > > the same label, it shouldn't be inferred that the 2 are > > related. > > > > > > We'll change/clarify the text. > > > > > > > > > > > > Regards, > > > > > > Reshad. > > > > > > > > > > > > On 2020-03-20, 5:08 PM, "netmod on behalf of Reshad > > Rahman > > > > (rrahman)" > > > > > > <netmod-boun...@ietf.org on behalf of > > > > > > rrahman=40cisco....@dmarc.ietf.org> wrote: > > > > > > > > > > > > Hi Martin, > > > > > > > > > > > > We've opened issues to track your review comments > (see > > > > > > below). Will > > > > > > kick off separate therads for each issue. > > > > > > > > > > > > https://github.com/netmod-wg/yang-ver- > > > > dt/issues?q=is%3Aissue+is%3Aopen+label%3Aupdated-mod-rev- > > > handling > > > > > > > > > > > > Regards, > > > > > > Reshad. > > > > > > > > > > > > On 2020-03-10, 3:31 PM, "netmod on behalf of Martin > > > Björklund" > > > > > > <netmod-boun...@ietf.org on behalf of > > mbj+i...@4668.se> > > > wrote: > > > > > > > > > > > > Hi, > > > > > > > > > > > > Here are my review comments of > > > > > > draft-verdt-netmod-yang-module-versioning-01. > > > > > > > > > > > > > > > > > > > > > > > > o 3.1.1 > > > > > > > > > > > > o In statements that have any data definition > > statements > > > > > > as > > > > > > substatements, those data definition > substatements > > > MAY > > > > > > be > > > > > > reordered, as long as they do not change the > > ordering > > > > > > or > > > > > > any "rpc" > > > > > > "input" substatements. > > > > > > > > > > > > I think this needs to capture that no descendant > > > statements > > > > > > to > > > > > > "input" can be reordered. Same for "output" > (note, > > > "input" > > > > > > and > > > > > > "output" in both "rpc" and "action"). > > > > > > > > > > > > > > > > > > o 3.3 > > > > > > > > > > > > All revision labels that match the pattern for the > > > > > > "version" > > > > > > typedef in the ietf-yang-semver YANG module > MUST > > be > > > > > > interpreted as > > > > > > YANG semantic version numbers. > > > > > > > > > > > > I don't think this is a good idea. Seems like a layer > > > > > > violation. > > > > > > What if my project use another dialect of semver, > that > > > > > > wouldn't > > > > > > be > > > > > > possible with this rule. I think this needs to be > > removed. > > > > > > > > > > > > > > > > > > o 3.3 > > > > > > > > > > > > Submodules MUST NOT use revision label > schemes > > that > > > could > > > > > > be > > > > > > confused > > > > > > with the including module's revision label > scheme. > > > > > > > > > > > > Hmm, how do I ensure that this MUST NOT is > handled > > > > > > correctly? > > > > > > What > > > > > > exactly does "could be confused with" mean? > > > > > > > > > > > > > > > > > > o 3.3 > > > > > > > > > > > > In the filename of a YANG module, where it > takes > > the > > > > > > form: > > > > > > module- > > > > > > or-submodule-name ['@' revision-label] ( '.yang' > / > > > > > > '.yin' ) > > > > > > > > > > > > Should this section update 5.2 of RFC 7950? I > know > > that > > > > > > 5.2 > > > > > > just > > > > > > says "SHOULD". But existing tools implement this > > SHOULD, > > > > > > and > > > > > > they > > > > > > need to be updated to handle this new > convention. > > > > > > > > > > > > But I wonder if this a good idea. It means that a > tool > > > > > > that > > > > > > looks > > > > > > for a module with a certain revision date cannot > simply > > > > > > check > > > > > > the > > > > > > filenames, but need to parse all available modules > > (wijust > > > > > > to > > > > > > find the > > > > > > > > > > > > > > > > > > > > > > > > o 3.4 > > > > > > > > > > > > leaf imperial-temperature { > > > > > > type int64; > > > > > > units "degrees Fahrenheit"; > > > > > > status deprecated { > > > > > > rev:status-description > > > > > > "Imperial measurements are being phased out > in > > > > > > favor > > > > > > of their metric equivalents. Use > > > > > > metric-temperature > > > > > > instead."; > > > > > > } > > > > > > description > > > > > > "Temperature in degrees Fahrenheit."; > > > > > > } > > > > > > > > > > > > I don't think rev:status-description is necessary / > worth > > > > > > it. > > > > > > This > > > > > > can easily be written with the normal description > > > statement > > > > > > instead: > > > > > > > > > > > > leaf imperial-temperature { > > > > > > type int64; > > > > > > units "degrees Fahrenheit"; > > > > > > status deprecated; > > > > > > description > > > > > > "Imperial measurements are being phased out > in > > > > > > favor > > > > > > of their metric equivalents. Use > > > > > > metric-temperature > > > > > > instead. > > > > > > > > > > > > Temperature in degrees Fahrenheit."; > > > > > > } > > > > > > > > > > > > > > > > > > o 3.5 > > > > > > > > > > > > The example modules should be legal YANG > modules. > > Use > > > e.g. > > > > > > "urn:example:module" as namespace. > > > > > > > > > > > > Also, the modules are missing the last "}", which > > confuses > > > > > > the > > > > > > "rfcstrip" tool. > > > > > > > > > > > > > > > > > > o 4.1.1 > > > > > > > > > > > > Alternatively, the first example could have used > the > > > > > > revision > > > > > > label > > > > > > "1.0.0" instead, which selects the same set of > > > > > > revisions/versions. > > > > > > > > > > > > import example-module { > > > > > > rev:revision-or-derived 1.0.0; > > > > > > } > > > > > > > > > > > > Shouldn't this be s/1.0.0/2.0.0/g ? > > > > > > > > > > > > > > > > > > o 5 > > > > > > > > > > > > I think the module name "ietf-yl-revisions" should > be > > > > > > changed to > > > > > > "ietf-yang-library-revisions". "yl" is not a well- > known > > > > > > acronym. > > > > > > > > > > > > > > > > > > o 5.2.2 > > > > > > > > > > > > Wouldn't it be better if the leaf > > > > > > "deprecated-nodes-implemented" > > > > > > and > > > > > > "obsolete-nodes-absent" were of type "boolean" > > rather > > > than > > > > > > type > > > > > > "empty"? > > > > > > > > > > > > > > > > > > o 7.1 > > > > > > > > > > > > The text says: > > > > > > > > > > > > All IETF YANG modules MUST include revision- > label > > > > > > statements > > > > > > for all > > > > > > newly published YANG modules, and all newly > > published > > > > > > revisions of > > > > > > existing YANG modules. The revision-label MUST > take > > the > > > > > > form > > > > > > of a > > > > > > YANG semantic version number > > > > > > [I-D.verdt-netmod-yang-semver]. > > > > > > > > > > > > I strongly disagree with this new rule. IETF > modules > > use a > > > > > > linear > > > > > > history, so there are no reasons to use "modified > > semver". > > > > > > > > > > > > It is ok to use rev:nbc-changes if needed, though. > > > > > > > > > > > > > > > > > > o 7.1.1 > > > > > > > > > > > > There is a missing " in: > > > > > > > > > > > > 4. For status "obsolete", it is RECOMMENDED to > keep > > the > > > > > > "status- > > > > > > description" information, from when the node > had > > > > > > status > > > > > > "deprecated, which is still relevant. > > > > > > HERE -----------^ > > > > > > > > > > > > > > > > > > o 8 > > > > > > > > > > > > s/CODE ENDS>/<CODE ENDS>/ > > > > > > > > > > > > > > > > > > o Both YANG modules > > > > > > > > > > > > All extensions should specify the grammar; i.e., in > > which > > > > > > statements > > > > > > they can be present and which substatements they > can > > > have. > > > > > > > > > > > > > > > > > > > > > > > > /martin > > > > > > > > > > > > > > _______________________________________________ > > > > > > netmod mailing list > > > > > > netmod@ietf.org > > > > > > https://www.ietf.org/mailman/listinfo/netmod > > > > > > > > > > > > > > > > > > > _______________________________________________ > > > > > > netmod mailing list > > > > > > netmod@ietf.org > > > > > > https://www.ietf.org/mailman/listinfo/netmod > > > > > > > > > > > > > > > > > > > _______________________________________________ > > > > > > netmod mailing list > > > > > > netmod@ietf.org > > > > > > https://www.ietf.org/mailman/listinfo/netmod > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > _______________________________________________ netmod mailing list netmod@ietf.org https://www.ietf.org/mailman/listinfo/netmod
