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

From: "Joe Clarke (jclarke)" <[email-masked]>
Date: Tue, 11 Aug 2020 13:41:22 +0000

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.

Thoughts?

Joe

---

From: Martin Björklund <[email-masked]>
Date: Tue, 11 Aug 2020 16:45:56 +0200 (CEST)

Hi,

"Joe Clarke \(jclarke\)" <jclarke=[email-masked]> 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.).
> 
> 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.

> 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?

/martin

> Thoughts?
> 
> Joe
> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod

---

From: Ladislav Lhotka <[email-masked]>
Date: Tue, 11 Aug 2020 16:52:45 +0200

> 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…

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.

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.

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

-- 
Ladislav Lhotka
Head, CZ.NIC Labs
PGP Key ID: 0xB8F92B08A9F76C67

---

From: Martin Björklund <[email-masked]>
Date: Tue, 11 Aug 2020 17:06:13 +0200 (CEST)

Hi,

> 1. Whitespace outside statement arguments - I believe this should never

Agreed.

> 3. Whitespace in other arguments has to be significant and lead to a

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.

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

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 11 Aug 2020 18:13:07 +0200

> whitespace change in the argument, but in fact it is not:

+1

I agree since whitespace outside YANG strings is insignificant.

Lets raise this to the next level. What about the following?

   D1. description "A server.";
   D2. description "A server.";  // not very descriptive

   E1. description "A server.";  // not	very descriptive
   E2. // not very descriptive
       description "A server.";

/js

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1 | 28759 Bremen | Germany
Fax:   +49 421 200 3103         <https://www.jacobs-university.de/>

---

From: "Joe Clarke (jclarke)" <[email-masked]>
Date: Tue, 11 Aug 2020 17:11:28 +0000

> On Aug 11, 2020, at 10:45, Martin Björklund <[email-masked]> wrote:
> 
> Hi,
> 

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.

> 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.  And a consumer would look to a canonical source (like IANA, the IETF document, or the vendor) to ensure a consistent module.

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.

Joe

---

From: "Joe Clarke (jclarke)" <[email-masked]>
Date: Tue, 11 Aug 2020 17:16:03 +0000

> On Aug 11, 2020, at 10:52, Ladislav Lhotka <[email-masked]> wrote:
> 
> 
> 

I shared comments from our discussion today in my response to Martin.

> I think there are in fact three cases:

Yeah.  We also discussed if this notion of “insignificant” white space was documented.  We weren’t sure that all of these cases were properly spelled out anywhere.

> are absolutely equivalent.

The consensus on the call would be to bump revision and YANG semver (if used) for all of these when republishing.  For 2 and your corner case, I would definitely see these as editorial.  For #3, that could be more of a MAJOR version bump (think changing a pattern).  For #1, we thought the explicitness of bumping the PATCH version when republishing made the most sense since the consumer clearly knows the module was intended to change, and the revision can document the reason for the change.

Joe

---

From: Martin Björklund <[email-masked]>
Date: Wed, 12 Aug 2020 09:10:46 +0200 (CEST)

Hi,

"Joe Clarke (jclarke)" <[email-masked]> wrote:
> 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.

> 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

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 12 Aug 2020 09:42:39 +0200

> 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.

Lada

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 12 Aug 2020 10:04:42 +0200

> 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 t…

I think it would be better to define "canonical YANG". One relatively straightforward way might be to convert to YIN first and then apply XML canonicalization:

https://www.w3.org/TR/2001/REC-xml-c14n-20010315

As an additional benefit, this would also enable digital signatures of YANG modules.

Lada

---

From: Martin Björklund <[email-masked]>
Date: Wed, 12 Aug 2020 10:34:10 +0200 (CEST)

>    E2. // not very descriptive

I think that comments should be treated as insignificant whitespace.

Comments in YANG are not tied to a specific statement, so it is
difficult to e.g. translate them to YIN properly.  For example to
which statement does the comment below belong?

  container foo {
     container bar; /* beware */ container baz;
  }

/martin

---

From: "Rob Wilton (rwilton)" <[email-masked]>
Date: Wed, 12 Aug 2020 08:56:49 +0000

> -----Original Message-----
> From: netmod <[email-masked]> On Behalf Of Ladislav Lhotka
> Sent: 12 August 2020 08:43
> To: Martin Björklund <[email-masked]>
> Cc: jclarke=[email-masked]; [email-masked]
> Subject: Re: [netmod] IETF 108: Summary of insignificant whitespace
> changes and versioning
> 
> >> > 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.).
> >> >
> 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.
> >> >
> 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.
> >> >
> 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.
> >>
> 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.";

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

Regards,
Rob

---

From: Martin Björklund <[email-masked]>
Date: Wed, 12 Aug 2020 11:02:48 +0200 (CEST)

"Rob Wilton (rwilton)" <[email-masked]> wrote:
> > should
> > (i.e.,
> > changed,
> > be

> > > 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.

> to fit different line width limits?

See above.

/martin

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 12 Aug 2020 11:08:03 +0200

> (editorial) change, and requires a new revision.

Perhaps formally, but given the role that the description statement
plays reflowing really means no change.

Lada

---

From: Randy Presuhn <[email-masked]>
Date: Wed, 12 Aug 2020 10:04:07 -0700

Hi -

On 8/12/2020 1:34 AM, Martin Björklund wrote:
...
>       container bar; /* beware */ container baz;

For some reason this whole discussion of errorless round-trip conversions
generated by flawless tools and inconsequential editorial changes made
by infallible editors reminds me of an episode at a company long ago
in which a programmer received a "commendation" for "most bugs
introduced by fixing a comment."  (I won't name names.)   From a
configuration management perspective, what's the point of introducing
a revision identification scheme if it is not used?

Randy

---

From: "Joe Clarke (jclarke)" <[email-masked]>
Date: Thu, 13 Aug 2020 08:52:11 +0000

> On Aug 12, 2020, at 04:04, Ladislav Lhotka <[email-masked]> wrote:
> 

This came up on our last call as well, but the consensus there was that defining canonical YANG would be a large undertaking and out of scope for this work.  That said, I think codifying such things would be useful.

Joe

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 13 Aug 2020 11:37:18 +0200

> This came up on our last call as well, but the consensus there was that defining canonical YANG would be a large undertaking and out of scope for this work.  That said, I think codifying such thing…

I did a few quick tests, and it seems that a pipeline like

$ pyang -f yin ietf-inet-types.yang | xmllint --c14n - | sha256sum
8d1ca8f30566ce8cbeffa095e20642f8f6e9f3a724286be4ead863b4467dc40b  -

might be a very good start. It is certainly much more robust than
relying on a simple checksum of the YANG module text.

Lada

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 13 Aug 2020 12:23:02 +0200

> relying on a simple checksum of the YANG module text.

This work started with the need for _semantic_ version numbers and now
we are down to hashes of modules? Do we still have a clear idea which
problem we are solving?

- Sane development environments use version control systems, we should
  in my view not attempt to go there. We should assume that people
  developing YANG modules use version control systems to track
  changes.

- There apparently is a need for a packaging system that can express
  which combinations of YANG module version are known to work
  together.

The YANG versioning work was driven (I think) by the desire to
support non-backwards compatible changes (section 4 of
draft-ietf-netmod-yang-versioning-reqs-03). Why do we end up
discussing how to calculate hashes or the impact of whitespace
changes? Whitespace and layout changes are backwards compatible,
even today's YANG versioning rules handle them well.

/js

---

From: Jan Lindblad <[email-masked]>
Date: Thu, 13 Aug 2020 12:52:58 +0200

+1
/jan

> On 13 Aug 2020, at 12:23, Juergen Schoenwaelder <[email-masked]> wrote:
>

---

From: "Joe Clarke (jclarke)" <[email-masked]>
Date: Wed, 26 Aug 2020 17:43:27 +0000

> On Aug 13, 2020, at 06:23, Juergen Schoenwaelder <[email-masked]> wrote:
> 

Sorry for the delay.  I was traveling and then trying to get caught back up.  Yes, things got off track a bit here.

>  developing YANG modules use version control systems to track

Agreed.  And through that development, we are not trying to impose any versioning up to the point that a module would be published (e.g., in a draft where it might be implemented).  Certainly, people could also pull and implement any arbitrary revision from a VCS, but we haven’t created any text to cover that (nor do I think we want to impose that each commit revs some version in the module itself).

> even today's YANG versioning rules handle them well.

The intent, at least for the whitespace changes was at a module release time to indicate what constitutes a version bump.  But the question could likely be rephrased.  Would one change the _revision_ of a module for any of the changes mentioned thus far?  And if a new revision is created, and semantic versioning is used a revision-label scheme, then that revision should have a new version label.  At least this was the opinion of the contributors in the regular weekly calls.

Joe

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 26 Aug 2020 21:55:27 +0200

> The intent, at least for the whitespace changes was at a module release time to indicate what constitutes a version bump.  But the question could likely be rephrased.  Would one change the _revisio…

The goal of the effort was to allow for non-backwards compatible
changes. Backwards compatible changes already work today (and white
space changes are obviously backwards compatible). If you want to
_publish_ a module with just whitespace changes, it is defined how to
do this.

I would find it way more important to mark which specific definitions
had backwards incompatible changes (plus perhaps hints how to deal
with them) instead of sticking a label on an entire module and then to
let others figure out what this label actually means for them (and
ultimately it is then the package maintainer's job to dig out which
revision sets can meaningfully work together).

If I make a non-backwards compatible change to the definition of
object-identifier in ietf-yang-types, then likely >98% of the modules
importing ietf-yang-types will not at all be affected by this. Still I
would have to declare a major version change triggering a lot of 'uhm,
ehm, what'. Expressing incompatibilities at the module level is pretty
arbitrary since the way definitions are organized into modules is
already somewhat arbitrary.

/js

---

From: "Joe Clarke (jclarke)" <[email-masked]>
Date: Thu, 27 Aug 2020 17:21:13 +0000

On Aug 26, 2020, at 15:55, Juergen Schoenwaelder <[email-masked]<mailto:[email-masked]>> wrote:

On Aug 13, 2020, at 06:23, Juergen Schoenwaelder <[email-masked]<mailto:[email-masked]>> wrote:

To be fair, the goal was to create a way to _express_ NBC changes.  We were very specific on wording it as “allowing NBC changes” versus documenting when NBC changes happen.

And we have the ability to do that in the module versioning document.  The [YANG Semver] label is there to make it easier for humans to quickly inspect two modules (or a package of modules) and know whether or not to spend more time digging into (via tooling) as to what changes have occurred and if the changes may break their applications.

I feel the hint is still helpful, especially for those that may be in the <2% group, whereas not causing an undue burden given that without it, that >98% group would have to take every module change and analyze them for relevant changes.

Joe

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 28 Aug 2020 09:30:34 +0200

> I feel the hint is still helpful, especially for those that may be in the <2% group, whereas not causing an undue burden given that without it, that >98% group would have to take every module chang…

If you mark the definitions that changed, tools can do the work to
figure out whether importing modules are affected or not. This is
relatively straight forward for a compiler that already knows what is
used and what is not used, this does not require much magic.

Instead, the approch taken here is to provide a somewhat vague warning
indicator (the version number) at the module level and then you rely
on tools (or humans) to identify semantic changes. And tools will
likely fail if semantics in descriptions have changed or they will
fail to decide whether two regular expressions are backwards
compatible or not or if a must statement is equivalent to a previous
when statement in a certain context. For the person making the change,
however, it is fairly easy to leave a mark since he/she can be
expected to understand the nature of the change.

It turns out that we already have some marks in the form of the status
statement. We can mark definitions as deprecated or obsolete. We do
not have a value to say 'changed' in an nbc way and we do not have a
mechanism to document the history of status changes for a given
definition, but that is easy to engineer into YANG.

/js

PS: I assume that we focus on 'published' YANG modules where the nbc
    change churn is reasonably under control. During active
    development phases, modules may undergo many little (nbc) changes
    but dealing with them should be left to version management
    systems.