Re: [netmod] IETF 108: Summary of insignificant whitespace changes and versioning

[Martin Björklund <[e-mail]>]

Hi,

"Joe Clarke (jclarke)" <[e-mail]> wrote:
> 
> 
> > On Aug 11, 2020, at 10:45, Martin Björklund <[e-mail]> wrote:
> > 
> > Hi,
> > 
> > "Joe Clarke \(jclarke\)" <jclarke=[e-mail]> wrote:
> >> At the IETF 108 virtual meeting, Lada asked about what would happen if
> >> he converted a YANG module to YIN syntax (or vice versa, or to some
> >> other format).  This was during the discussion of the issue of what
> >> should happen if a module changes and the only changes are
> >> insignificant whitespaces (e.g., strip trailing spaces, change line
> >> length of descriptions, etc.).
> >> 
> >> The authors/contributors discussed on this on our weekly calls, and we
> >> propose:
> >> 
> >> If a module changes and those changes are only insignificant
> >> whitespace changes and the syntax of the module remains the same
> >> (i.e., YANG to YANG, YIN, YIN, etc.), a new revision of the module
> >> MUST be created.  If you are using YANG semver as your revision
> >> scheme, you MUST apply a PATCH version bump to that new module
> >> revision to indicate an editorial change.
> >> 
> >> The reasoning behind this decision is that it makes it very clear and
> >> unambiguous to consumers that this module has been consciously
> >> changed, and those changes are only editorial.  This way one won’t be
> >> concerned if they note that a module of a given syntax with the same
> >> version but different checksums and diffs wasn’t otherwise
> >> manipulated.
> > 
> > I think this is the wrong way to go.  I clean up formatting issues all
> > the time, including IETF modules.  I am pretty sure that if you
> > retrieve modules like "ietf-interfaces" or "ietf-yang-types" from
> > different vendors' products, you will get modules with differences in
> > whitespace - and this is not a problem AFAIK.
> > 
> > I think it is ok that a simple "diff" show whitespace changes in this
> > case.  I don't think it leads to any real problems.
> 
> We discussed this on the call.  The thinking was that a long diff
> output would essentially be unwieldy for some modules and important
> changes might be lost.  If the versions were the same, it would be
> ambiguous to the consume as to whether or not the module was only
> changed in trivial (i.e., less-than-editorial) or if more substantive
> changes happened.  If you trust the producer, maybe you assume they
> regenerated the module without trailing whitespace (or the like).  We
> felt there should be a more explicit signal.

But if you don't trust the producer, perhaps they didn't update the
revision according to the rules anyway?  I think we should have sound
rules and if people don't follow the rules then it's up to them.

> >> That said, if a module changes format from one syntax to another but
> >> maintains semantic equivalency, then the revision and YANG semver MUST
> >> be the same.  In that case, one will use the extension to realize that
> >> this module file cannot be directly compared to one of another syntax
> >> without looking at compiled or semantic representation.
> > 
> > This seems a bit inconsistent.  Suppose I round-trip from YANG to YIN
> > to YANG, and the result is different whitespace in the two YANG
> > modules.  The revision is the same, as explained above.  How is this
> > different from changing the whitespace in YANG directly?
> 
> We didn’t discuss this directly, but we did discuss auto-generators
> that could do this type of round-tripping.  The general consensus was
> that you would use the same post-processing tool (e.g., pyang -f yang)
> on the result to ensure consistency.

I don't think we can or should have a solution that works only if
people are using a (specific version of a) specific tool.

> And a consumer would look to a
> canonical source (like IANA, the IETF document, or the vendor) to
> ensure a consistent module.

It is quite common that clients download the modules from the servers,
rather than from a "canonical source".

> In terms of alternate sources, I would think that if one wanted to
> trust an IETF module downloaded from some other site, they could.  If
> that site did some additional formatting, that would be up to the
> consumer to resolve compared to what might be required by a package.
> But if the publisher (IETF in this case) were to republish a module
> with these stripped whitespace line endings, then that would be a
> different revision.

I think they (IETF/IANA) should be able to change insignificant
whitespace w/o changing the revision.


/martin