Subject: YANG Model Formatting

From: "Acee Lindem (acee)" <[email-masked]>
Date: Mon, 8 Apr 2019 21:27:34 +0000

All,

I had a YANG model RFC discussion with the Sandy Ginoza, RFC Editor, at IETF 104 and she indicated that they are using pyang to format YANG models prior to publication. It would help greatly if authors do the formatting in advance to facilitate reviews and lessen the RFC Editor task. Here are the commands in use:

pyang -f yang --keep-comments
pyang --ietf --max-line-length 69

Thanks,
Acee

---

From: Benoit Claise <[email-masked]>
Date: Mon, 8 Apr 2019 23:34:37 +0200

Thanks Acee for the proactive note.
Using the right tool with the right parameters avoid some frustration at 
the end of the IETF process.
Next step: use those directly in the idnits, at submission time.

Regards, Benoit
>
> All,
>
>
> I had a YANG model RFC discussion with the Sandy Ginoza, RFC Editor, 
> at IETF 104 and she indicated that they are using pyang to format YANG 
> models prior to publication. It would help greatly if authors do the 
> formatting in advance to facilitate reviews and lessen the RFC Editor 
> task. Here are the commands in use:
>

---

From: Warren Kumari <[email-masked]>
Date: Mon, 8 Apr 2019 17:46:06 -0400

On Mon, Apr 8, 2019 at 5:27 PM Acee Lindem (acee) <[email-masked]> wrote:

> All,
>
>
> I had a YANG model RFC discussion with the Sandy Ginoza, RFC Editor, at
> IETF 104 and she indicated that they are using pyang to format YANG models
> prior to publication. It would help greatly if authors do the formatting in
> advance to facilitate reviews and lessen the RFC Editor task. Here are the
> commands in use:
>
>
>

Cool -- it seems like this information should be captured somewhere better
than just an email.

I don't really know where the best place for this is / where people
generally go look for this sort of thing - perhaps:
https://trac.ietf.org/trac/ops/wiki/yang-review-tools
or
https://trac.ietf.org/trac/ops/wiki/YangModelCoordGroup

I'll leave it to y'all / Ignas to figure out where.

W

-- 
I don't think the execution is relevant when it was obviously a bad idea in
the first place.
This is like putting rabid weasels in your pants, and later expressing
regret at having chosen those particular rabid weasels and that pair of
pants.
   ---maf

---

From: Yingzhen Qu <[email-masked]>
Date: Mon, 8 Apr 2019 22:03:23 +0000

I support adding this tool as part of draft submission verification, just like existing pyang and yanglint. This will help all YANG contributors on the formatting issue a lot.

Thanks,
Yingzhen

From: WGChairs [mailto:[email-masked]] On Behalf Of Benoit Claise
Sent: Monday, April 08, 2019 2:35 PM
To: Acee Lindem (acee) <[email-masked]>; Working Group Chairs <[email-masked]>
Cc: Martin Bjorklund <[email-masked]>; [email-masked]; [email-masked]
Subject: Re: YANG Model Formatting

Thanks Acee for the proactive note.
Using the right tool with the right parameters avoid some frustration at the end of the IETF process.
Next step: use those directly in the idnits, at submission time.

Regards, Benoit
All,

Thanks,
Acee

---

From: Kent Watsen <[email-masked]>
Date: Tue, 9 Apr 2019 00:40:32 +0000

Ignas, Martin, and I met with Sandy as well.

There is a plan to rather quickly add a process step into the shepherd writeup, followed by later integration into datatracker.  The goal is to remove this burden from the copyeditors entirely.

BTW, `pyang -f yang --keep-comments --max-line-length 69` is even more helpful.

Kent

> On Apr 8, 2019, at 5:34 PM, Benoit Claise <[email-masked]> wrote:
> 
>> B 
>> B 
>> B 
>> B 
>> B

---

From: "Acee Lindem (acee)" <[email-masked]>
Date: Tue, 9 Apr 2019 19:12:50 +0000

Hi Martin, 

With respect to the formatting done by " pyang -f yang --keep-comments --yang-line-length 69", I noticed that it joins all the XPaths that we had meticulously formatted to fit in 69 columns into a single line of arbitrary length. The same with constraints.  Using the output will undoubtedly result in lots of xml2rfc warnings. 

For example:

leaf routing-protocol-name {
      type leafref {
        path "/rt:routing/rt:control-plane-protocols/"
           + "rt:control-plane-protocol/rt:name";
      }
      must "derived-from( "
        + "/rt:routing/rt:control-plane-protocols/"
        + "rt:control-plane-protocol[rt:name=current()]/"
        + "rt:type, 'ospf:ospf-protocol')";
      description
       "OSPF routing protocol instance name.";
    }

Becomes: 

leaf routing-protocol-name {
      type leafref {
        path "/rt:routing/rt:control-plane-protocols/rt:control-plane-protocol/rt:name";
      }
      must "derived-from( /rt:routing/rt:control-plane-protocols/rt:control-plane-protocol[rt:name=current()]/rt:type, 'ospf:ospf-protocol')";
      description
        "OSPF routing protocol instance name.";
    }

Is this desirable?

Thanks,
Acee

On 4/9/19, 5:01 AM, "Martin Bjorklund" <[email-masked]> wrote:

    > https://trac.ietf.org/trac/ops/wiki/yang-review-tools
    
    This page was a bit out of date... I updated it, and added a new
    section about YANG formatting, with the commands above (actually, the
    proper command for formatting is:
    
      pyang -f yang --keep-comments --yang-line-length 69
    
    )

    As Kent wrote, the plan is to eventually get a warning about
    formatting issues at draft submit time (like idnits and YANG
    validation).

    /martin

---

From: Mahesh Jethanandani <[email-masked]>
Date: Tue, 9 Apr 2019 12:30:34 -0700

Can I suggest that the ‘-f yang’ option not reformat how blank lines are inserted/removed in the model. I am sure we can give authors discretion on where they see fit to have them in the model, without impacting consistency of IETF models.

Thanks.

> On Apr 8, 2019, at 5:40 PM, Kent Watsen <[email-masked]> wrote:
>

---

From: Mahesh Jethanandani <[email-masked]>
Date: Tue, 9 Apr 2019 13:08:12 -0700

> On Apr 9, 2019, at 12:41 PM, Martin Bjorklund <[email-masked]> wrote:
> 
> Mahesh Jethanandani <[email-masked]> wrote:
>> Can I suggest that the ‘-f yang’ option not reformat how blank lines
>> are inserted/removed in the model.
> 
> This is non-trivial.  PRs are welcome ;-)  For example, check this model:
> 
> https://tools.ietf.org/html/draft-ietf-i2nsf-sdn-ipsec-flow-protection-04#appendix-A
> 
> (similar in Appendix B & C)
> 
> How should pyang *not* reformat blank lines in this model?

I see the model could do with formatting for indentation, max characters per line amongst other things, but I do not find the use of blank lines between statements particularly egregious. Where do you find the use of blank lines particularly offending?

> 
> 
>> I am sure we can give authors
>> discretion on where they see fit to have them in the model, without
>> impacting consistency of IETF models.
> 
> Well... do you really think it is important that authors can insert
> various levels of blank lines in the model?

The discretion I am talking about is giving authors choice of having a blank line or not having a blank line between statements. If the model has 10 blank lines between statements, I would agree we have a problem. But is that the case in the model above?

> 
> This said, the idea I had to handle this is to ignore blank lines when
> we check the format at draft submission time.  The RFC editor then
> doesn't (have to) change blank lines.

I agree.

>>> There is a plan to rather quickly add a process step into the shepherd
>>> writeup, followed by later integration into datatracker.  The goal is
>>> to remove this burden from the copyeditors entirely.
>>> 

Mahesh Jethanandani
[email-masked]

---

From: "Acee Lindem (acee)" <[email-masked]>
Date: Tue, 9 Apr 2019 20:11:53 +0000

Hi Martin, 

On 4/9/19, 3:29 PM, "Martin Bjorklund" <[email-masked]> wrote:

    "Acee Lindem (acee)" <[email-masked]> wrote:
    > Hi Martin, 
    > 
    > With respect to the formatting done by " pyang -f yang
    > --keep-comments --yang-line-length 69", I noticed that it joins all
    > the XPaths that we had meticulously formatted to fit in 69 columns
    > into a single line of arbitrary length. The same with constraints.
    > Using the output will undoubtedly result in lots of xml2rfc
    > warnings.
    
    It should keep the string concats you have.  Are you running 1.7.8 or
    later?   Also double check the parameter "--yang-line-length 69".

I was using pip to update my pyang and it thinks 1.7.5 is the latest. I guess I need to manually install the latest. This would explain my "--yang-line-length" wasn't recognized. I thought it was a typo for "--max-line-length".

Thanks,
Acee

    If this doesn't work, we can take this off this list.

    /martin

---

From: "Acee Lindem (acee)" <[email-masked]>
Date: Wed, 10 Apr 2019 01:09:08 +0000

It turns out I had, more than one, old version of pyang on my MacPro. Once uninstalled them and installed 1.7.8, my formatting issues were resolved. 
Thanks,
Acee

On 4/9/19, 4:12 PM, "WGChairs on behalf of Acee Lindem (acee)" <[email-masked] on behalf of [email-masked]> wrote:

    Hi Martin, 

        

    Thanks,
    Acee

        /martin

---

From: Linda Dunbar <[email-masked]>
Date: Tue, 16 Apr 2019 22:04:14 +0000

Even better put it under the https://www.ietf.org/how/tools/ right next to YANG Model Validation Tool, making it easier for people to use.

Linda

From: WGChairs [mailto:[email-masked]] On Behalf Of Warren Kumari
Sent: Monday, April 08, 2019 4:46 PM
To: Acee Lindem (acee) <[email-masked]>
Cc: Working Group Chairs <[email-masked]>; Martin Bjorklund <[email-masked]>; [email-masked]
Subject: Re: YANG Model Formatting

On Mon, Apr 8, 2019 at 5:27 PM Acee Lindem (acee) <[email-masked]<mailto:[email-masked]>> wrote:
All,

Cool -- it seems like this information should be captured somewhere better than just an email.

I don't really know where the best place for this is / where people generally go look for this sort of thing - perhaps:
https://trac.ietf.org/trac/ops/wiki/yang-review-tools
or
https://trac.ietf.org/trac/ops/wiki/YangModelCoordGroup

W

Thanks,
Acee

--
I don't think the execution is relevant when it was obviously a bad idea in the first place.
This is like putting rabid weasels in your pants, and later expressing regret at having chosen those particular rabid weasels and that pair of pants.
   ---maf