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

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

"Rob Wilton (rwilton)" <[e-mail]> wrote:
> 
> 
> > -----Original Message-----
> > From: netmod <[e-mail]> On Behalf Of Ladislav Lhotka
> > Sent: 12 August 2020 08:43
> > To: Martin Björklund <[e-mail]>
> > Cc: jclarke=[e-mail]; [e-mail]
> > Subject: Re: [netmod] IETF 108: Summary of insignificant whitespace
> > changes and versioning
> > 
> > Martin Björklund <[e-mail]> writes:
> > 
> > > Hi,
> > >
> > >
> > > Ladislav Lhotka <[e-mail]> wrote:
> > >>
> > >>
> > >> On 11. 08. 20 15:41, Joe Clarke (jclarke) 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.
> > >> >
> > >> > 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.
> > >>
> > >> The last paragraph means that after a round trip YANG -> YIN -> YANG
> > the
> > >> initial and final YANG modules MUST have the same revision. However,
> > >> depending on the conversion tools used, they may easily differ in
> > >> whitespace, so their byte-oriented checksums won't be equal.
> > >>
> > >> I think there are in fact three cases:
> > >>
> > >> 1. Whitespace outside statement arguments - I believe this should
> > >> never
> > >> be significant.
> > >
> > > Agreed.
> > >
> > >> 2. Whitespace in the argument of "contact", "description",
> > >> "error-message" and "organization" - this is tricky because tools may
> > >> format such arguments differently. I am leaning towards making
> > >> whitespace insignificant in this case as well.
> > >>
> > >> 3. Whitespace in other arguments has to be significant and lead to a
> > >> revision bump.
> > >
> > > I think that any change in an argument string is an editorial change.
> > >
> > > For example, compare these two changes:
> > >
> > >    A1.  description "a server.";
> > >    A2.  description "A server.";
> > >
> > >    B1.  description "A  server.";
> > >    B2.  description "A server.";
> > >
> > > These are editorial changes, and thus the revision should be changed.
> > 
> > But consider
> > 
> >    description
> >        "A server and
> >         its data.";
> > 
> > versus
> > 
> >    description
> >        "A server and
> >        its data.";
> > 
> > Here the difference is only in presentation - a YANG parser gives the
> > same
> > string in both cases. Another awkward case is whitespace before a line
> > break.
> [RW] 
> 
> [As an individual contributor]
> 
> What about:
> 
>     description
>         "A server and
>          its data.";
>  
> versus
>  
>     description
>         "A server and its data.";

I wrote:

> > > I think that any change in an argument string is an editorial change.

Your example changes the argument string; hence this is a significant
(editorial) change, and requires a new revision.

> Or any cases where description statements might be reflowed by tooling
> to fit different line width limits?

See above.



/martin


> 
> Regards,
> Rob
> 
> 
> > 
> > Lada
> > 
> > >
> > > Note however that the following change might look like an editorial
> > > whitespace change in the argument, but in fact it is not:
> > >
> > >   C1.
> > >       description
> > >           "A server and
> > >            its data.";
> > >
> > >   C2.
> > >       description
> > >         "A server and
> > >          its data.";
> > >
> > >
> > > /martin
> > >
> > >
> > >>
> > >> And one more corner case for both 2 a 3: what if "\t" is replaced with
> > >> the tab character in a double-quoted string? For YANG, these two
> > strings
> > >> are absolutely equivalent.
> > >>
> > >> Lada
> > >>
> > >> >
> > >> > Thoughts?
> > >> >
> > >> > Joe
> > >> > _______________________________________________
> > >> > netmod mailing list
> > >> > [e-mail]
> > >> > https://www.ietf.org/mailman/listinfo/netmod
> > >> >
> > >>
> > >> --
> > >> Ladislav Lhotka
> > >> Head, CZ.NIC Labs
> > >> PGP Key ID: 0xB8F92B08A9F76C67
> > >>
> > >> _______________________________________________
> > >> netmod mailing list
> > >> [e-mail]
> > >> https://www.ietf.org/mailman/listinfo/netmod
> > 
> > --
> > Ladislav Lhotka
> > Head, CZ.NIC Labs
> > PGP Key ID: 0xB8F92B08A9F76C67
> > 
> > _______________________________________________
> > netmod mailing list
> > [e-mail]
> > https://www.ietf.org/mailman/listinfo/netmod