Re: [netmod] Adam Roach's No Objection on draft-ietf-netmod-rfc6087bis-18: (with COMMENT)

[Benoit Claise <[e-mail]>]

Hi Adam,
> Adam Roach has entered the following ballot position for
> draft-ietf-netmod-rfc6087bis-18: No Objection
>
> When responding, please keep the subject line intact and reply to all
> email addresses included in the To and CC lines. (Feel free to cut this
> introductory paragraph, however.)
>
>
> Please refer to https://www.ietf.org/iesg/statement/discuss-criteria.html
> for more information about IESG DISCUSS and COMMENT positions.
>
>
> The document, along with other ballot positions, can be found here:
> https://datatracker.ietf.org/doc/draft-ietf-netmod-rfc6087bis/
>
>
>
> ----------------------------------------------------------------------
> COMMENT:
> ----------------------------------------------------------------------
>
> Thanks for this document. It is well-written and I believe it will be helpful.
> Comments follow.
>
> ---------------------------------------------------------------------------
>
> General:
>
> I've reviewed a couple of YANG modules where the indentation and/or wrapping was
> awkward and inconsistent. I would love to see guidance in this document that
> authors be careful to run their modules through pyang (or a similar tool) to
> ensure consistent formatting. It may be worthwhile to give an example of the
> exact commandline invocation of pyang to achieve a formatting that is consistent
> with existing published modules.
We've been in discussion with the RFC editor lately (Sandy, cc'ed) on 
this important topic.
And also with IANA, which should be keep the source of truth for IETF 
YANG modules (but this is not that easy. More on this later).

 From a YANG language point of view, as long as the module validates, 
we're good.
But OTOH, we do require some common style from the published modules, 
for example we want all lines to be properly indented and we require 
space characters between some tokens etc. Consistency is easier for readers

With the RFC editors, we agreed on this high level process:
     - extract the YANG file
     - run pyang -f yang --yang-canonical --keep-comments FILE
     - ask the authors if they are okay with the output file (before 
replacing it in the RFC (to be) for review)
     - assuming they agree, update the RFC
     - then transmit the module to IANA for publication.

During the discussion, Martin Bjorklund (THE pyang main developer), 
expressed:

      Such a tool will of course blindly produce consistent output, but
      sometimes a human needs to polish the result anyway.

      ...

    Unfortunately, I don't think the tool is quite ready to be used in an
    automated fashion.  It does produce consistent output wrt indentation
    and quotes etc, but it doesn't do a good job when it comes to handling
    long lines.  As an example, if the original module has:

           pattern '[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-'
                 + '[0-9a-fA-F]{4}-[0-9a-fA-F]{12}';

    the tool will print:

           pattern '[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}';


    I have just released a new version of pyang, 1.7.4, which fixes one
    issue with "-f yang" that has been discussed on the mailing list.

I see two solutions from here.
1. we mention "pyang -f yang --yang-canonical --keep-comments FILE" in 
RFC6087bis, with a warning such as: "As the tool matures, a human might 
need to polish the results"
2. we don't mention "pyang -f yang --yang-canonical --keep-comments 
FILE" in RFC6087bis, but we ask the YANG doctors to run the tests.

Considering that not many people know those specific pyang parameters, I 
would favor solution 1.

Feedback?

Regards, Benoit