Re: [netmod] YANG Versioning: filename recommendations for YANG Semver

[Andy Bierman <[e-mail]>]

On Tue, Apr 9, 2024 at 7:01 AM Rob Wilton (rwilton) <[e-mail]>
wrote:

> Hi Andy,
>
>
>
> For me, it seems likely that vendors using YANG Semver will want to use a
> filename that can contain the Semver label, and I still see some advantages
> for everyone to do it in a similar way.  E.g., it is very likely that
> internally we will just use this format, but will probably strip or convert
> it before publishing them.
>
> But I agree that we shouldn’t formally change the filename format in YANG
> 1.1, and that would be best left for YANG 2.0 (obviously if agreed at that
> time).
>
> My question is whether we can find some middle ground where we at least
> informally document the format in an appendix now (i.e., as non-normative
> text), so that if folks are starting to use a format, then they could
> choose this one, but not to change the extension representation/API when
> naming YANG modules.
>
> Such an appendix might start with something like:
>
> <start proposal>
> “During this work it was discussed that having a filename format that
> allows for the Semver, rather than the revision-date to be expressed in the
> filename, would be beneficial.  It was concluded that making such a change
> would risk breaking existing tooling and hence would be better deferred to
> a further revision of the YANG language.  The proposed format is
> ‘informatively’ documented below, which might be adopted in a future
> revision of YANG.
>
> … <include the definition that we had before but with no RFC 2119 keywords>
>
> <end proposal>
>
>
> Would such an approach potentially be acceptable to you?  Or are you
> strongly against saying anything at all?  Note the motivation for
> considering put this in is because a comment was raised during IETF 119
> about avoiding an undocumented de facto standard – I would like to get
> consensus on this draft so that we can get it published an move on.
>
>

I do not see the value of creating a new file naming scheme based on the
revision label.
The "import by revision" mechanisms are based on revision date, not label.

YANG extensions are different.
1) a YANG extension MUST NOT alter YANG 1.1 semantics
2) a YANG 1.1 tool MUST be capable of skipping past any extension

However the YANG 1.1 specification makes no such provision for a detail
like the file naming.
So it seems premature and inappropriate to define a file naming scheme for
YANG 2.0
since it does not exist and will probably never exist.




> Regards,
> Rob
>

Andy


>
>
>
>
> *From: *netmod <[e-mail]> on behalf of Andy Bierman <
> [e-mail]>
> *Date: *Wednesday, 3 April 2024 at 19:07
> *To: *Joe Clarke (jclarke) <[e-mail]>
> *Cc: *Jason Sterne (Nokia) <jason.sterne=[e-mail]>,
> [e-mail] <[e-mail]>
> *Subject: *Re: [netmod] YANG Versioning: filename recommendations for
> YANG Semver
>
> Hi,
>
>
>
>
>
> On Wed, Apr 3, 2024 at 10:34 AM Joe Clarke (jclarke) <[e-mail]>
> wrote:
>
>
>
>
>
> *From: *Andy Bierman <[e-mail]>
> *Date: *Tuesday, April 2, 2024 at 17:40
> *To: *Joe Clarke (jclarke) <[e-mail]>
> *Cc: *Jason Sterne (Nokia) <jason.sterne=[e-mail]>,
> [e-mail] <[e-mail]>
> *Subject: *Re: [netmod] YANG Versioning: filename recommendations for
> YANG Semver
>
>
>
>
>
> On Tue, Apr 2, 2024 at 2:11 PM Joe Clarke (jclarke) <[e-mail]>
> wrote:
>
> Thanks, Andy.  See inline below.
>
>
>
> I do not agree with these recommendations to change the file names of YANG
> modules.
>
> The OFFICIAL YANG version is RFC 7950 - YANG 1.1.
>
> Any module using YANG version 1.1 needs to follow the rules in RFC 7950.
>
> Additional file naming that can be ignored by YANG 1.1 tools is OK.
>
>
>
> [JMC] We had this conversation on our call today.  I agree with you that
> tools can be unaware of YANG Semver and attempt to load a file named
> foo#1.2.3.yang as a module named “foo#1.2.3”, which would disagree with the
> module name defined within the module.
>
>
>
>
>
> This can never happen since the '#' char is not allowed in a YANG module
> name.
>
> YANG 1.1 tools look for MODNAME[@DATE].EXT.
>
> If the YANG module name is not in this format the tool will not find the
> module.
>
>
>
> [JMC] Of course.  We (authors on the call) were debating what a tool would
> do with the *filename* if it didn’t understand this YANG Semver naming.
>
>
>
> The issue is obviously not the 2 lines of code to parse "#" instead of "@".
>
> IMO this file name change is operationally disruptive and not really
> needed.
>
> How come OpenConfig modules do not use this naming scheme?
>
> Is it because they are following the RFC 7950 file naming rules?
>
>
>
> [JMC] This naming scheme hadn’t been introduced.  OpenConfig doesn’t use
> the @ convention, either.  They just have naked module names from what I
> can see (https://github.com/openconfig/public/tree/master/release/models).
> I know that at least one vendor is already using YANG Semver and the ‘#’
> notation for file naming.  I believe it is in part because of this the
> chairs wanted us to revisit the naming.
>
>
>
>
>
> So the revision-date is the only field that can be relied upon since the
> same SemVer (e.g. "1.0.0") could be released several times,
>
> each one containing different content.
>
>
>
> [JMC] Just as with revision-date, the YANG Semver identifier must be
> unique.  You cannot have multiple “1.0.0” identifiers for the same module
> with different content.  That 1.0.0 would be tied to a revision of a unique
> date.
>
>
>
>
>
>
>
> I do not see any net value by changing the filename spec so it is
> different than YANG 1.1.
>
> Duplication of files is a bug, not a feature.
>
>
>
> Tools usually rely on a proprietary search path configuration to find
> modules.
>
> Some clients rely on <get-schema> and always use the modules from the
> server.
>
> This is stable and has been the practice since 2016.
>
>
>
> IMO this is an NBC change to YANG 1.1, so it should not be done at all.
>
> Adding YANG extensions is fine, and I support that part of this work.
>
>
>
>
>
> Joe
>
>
>
>
>
> Andy
>
>
>
>
>
> Joe
>
>
>
>
>
> Andy
>
>
>
>