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

[Jan Lindblad]

+1
/jan

> On 13 Aug 2020, at 12:23, Juergen Schoenwaelder 
>  wrote:
> 
> On Thu, Aug 13, 2020 at 11:37:18AM +0200, Ladislav Lhotka wrote:
>> 
>> 
>> $ 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.
> 
> 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
> 
> -- 
> Juergen Schoenwaelder   Jacobs University Bremen gGmbH
> Phone: +49 421 200 3587 Campus Ring 1 | 28759 Bremen | Germany
> Fax:   +49 421 200 3103 
> 
> ___
> 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

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

[Juergen Schoenwaelder]

On Thu, Aug 13, 2020 at 11:37:18AM +0200, Ladislav Lhotka wrote:
> 
> 
> $ 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.

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

-- 
Juergen Schoenwaelder   Jacobs University Bremen gGmbH
Phone: +49 421 200 3587 Campus Ring 1 | 28759 Bremen | Germany
Fax:   +49 421 200 3103 

___
netmod mailing list
netmod@ietf.org
https://www.ietf.org/mailman/listinfo/netmod

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

[Ladislav Lhotka]

On 13. 08. 20 10:52, Joe Clarke (jclarke) wrote:
> 
> 
>> On Aug 12, 2020, at 04:04, Ladislav Lhotka  wrote:
>>
>> "Joe Clarke \(jclarke\)"  writes:
>>
 On Aug 11, 2020, at 10:45, Martin Björklund  wrote:

 Hi,

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

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

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

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

> 

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

[Joe Clarke (jclarke)]

> On Aug 12, 2020, at 04:04, Ladislav Lhotka  wrote:
> 
> "Joe Clarke \(jclarke\)"  writes:
> 
>>> On Aug 11, 2020, at 10:45, Martin Björklund  wrote:
>>> 
>>> Hi,
>>> 
>>> "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.
>>> 
>>> 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.
>> 
>>> 
 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.  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.
> 
> 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.

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

___
netmod mailing list
netmod@ietf.org
https://www.ietf.org/mailman/listinfo/netmod