Subject: [RTG-DIR] RtgDir Early review: draft-ietf-i2rs-yang-l3-topology

From: Michael Richardson <[email-masked]>
Date: Wed, 19 Jul 2017 10:45:03 +0200

Hello

I have been selected to do a routing directorate “early” review of this draft. 
https://tools.ietf.org/html/draft-ietf-i2rs-yang-l3-topology-10

The routing directorate will, on request from the working group chair,
perform an “early” review of a draft before it is submitted for publication
to the IESG. The early review can be performed at any time during the draft’s
lifetime as a working group document. The purpose of the early review depends
on the stage that the document has reached.

I believe that this is case 3, the document is neither recently adopted
nor is it in WGLC.   The request is for a sanity check.

For more information about the Routing Directorate, please see
​http://trac.tools.ietf.org/area/rtg/trac/wiki/RtgDir 

Document: draft-ietf-i2rs-yang-l3-topology
Reviewer: Michael Richardson
Review Date: 2017-07-18
Intended Status: Standards Track

Summary: 

I have some minor concerns about this document that I think should be
resolved before it is submitted to the IESG.

Comments:

I found the document clear and well written.
You told me at the beginning that:
   For this purpose,
   example models are introduced that cover IS-IS [RFC1195] and OSPF
   [RFC2328].

Yet I still felt sad when I got to spot where it said:
   Accordingly, the module is not delimited with
   CODE BEGINS and CODE ENDS

I think that the point of the OSPF and ISIS examples was to show, via a kind
of running-code of YANG, that the specification was complete enough that
it could be used.   Maybe this could be clarified better, the examples occupy
a large portion of the document.   I'm not sure so much of the document
should be devoted to non-normative examples.

I don't think I agree with ommitting the CODE BEGINS, because someone reading
this might well want to run the examples through their yang validator.
   
It was nice to have the mini-tutorial on YANG, but I don't think it needed
to be repeated.

I found parts of the YANG to be silly, such as:

        leaf-list flag {
           type node-flag-type;
           description
             "Node flags";
         }

Does YANG require that actually have to have a description?
It is meaningless as above.  What are node flags?   I suggest that the
description should be far more useful.  Consider someone seeing the data
decoded into a database, but has this description.

Another example of useless descriptions:
        case asbr {
           leaf asbr {
             type empty;
             description
               "The node is ASBR";
           }

okay, fair enough, it is an example, so don't work too hard here.

As examples, I thought that maybe I'd see this module instantiated into
JSON or XML and to see an example of a data set that describes a real-life
router's interfaces.  I did not see such a thing.
Perhaps there are feelings about whether or not a YANG model should include
concrete code or not, I'm not sure.

I didn't understand why:
  Appendix A.  Companion YANG model for non-NMDA compliant implementations
was included.  Probably I don't know enough about NMDA.

Nits:

I found no trivial nits.

-- 
Michael Richardson <[email-masked]>, Sandelman Software Works
 -= IPv6 IoT consulting =-

---

From: "Susan Hares" <[email-masked]>
Date: Wed, 19 Jul 2017 04:50:41 -0400

Michael: 

Thank you for the review.  The authors will be discussing this with you and on the list. 

One challenge is that your point of view on IS-IS and OSPF models was countered by the Yang doctor's review.  The YANG Doctor's early review removed the CODE-BEGINS/CODE-ENDS.   However, you and the YANG Doctors both have good points.   As chair, I'm going to have to the I2RS AD and the OPS Advice on what to do. 

Sue 

-----Original Message-----
From: rtg-dir [mailto:[email-masked]] On Behalf Of Michael Richardson
Sent: Wednesday, July 19, 2017 4:45 AM
To: [email-masked]; [email-masked]
Cc: [email-masked]; [email-masked]
Subject: [RTG-DIR] RtgDir Early review: draft-ietf-i2rs-yang-l3-topology

Hello

The routing directorate will, on request from the working group chair, perform an “early” review of a draft before it is submitted for publication to the IESG. The early review can be performed at any time during the draft’s lifetime as a working group document. The purpose of the early review depends on the stage that the document has reached.

For more information about the Routing Directorate, please see ​http://trac.tools.ietf.org/area/rtg/trac/wiki/RtgDir 

Summary: 

I have some minor concerns about this document that I think should be resolved before it is submitted to the IESG.

Comments:

I think that the point of the OSPF and ISIS examples was to show, via a kind of running-code of YANG, that the specification was complete enough that
it could be used.   Maybe this could be clarified better, the examples occupy
a large portion of the document.   I'm not sure so much of the document
should be devoted to non-normative examples.

I don't think I agree with ommitting the CODE BEGINS, because someone reading this might well want to run the examples through their yang validator.
   
It was nice to have the mini-tutorial on YANG, but I don't think it needed to be repeated.

        leaf-list flag {
           type node-flag-type;
           description
             "Node flags";
         }

Does YANG require that actually have to have a description?
It is meaningless as above.  What are node flags?   I suggest that the
description should be far more useful.  Consider someone seeing the data decoded into a database, but has this description.

As examples, I thought that maybe I'd see this module instantiated into JSON or XML and to see an example of a data set that describes a real-life router's interfaces.  I did not see such a thing.
Perhaps there are feelings about whether or not a YANG model should include concrete code or not, I'm not sure.

I didn't understand why:
  Appendix A.  Companion YANG model for non-NMDA compliant implementations was included.  Probably I don't know enough about NMDA.

Nits:

I found no trivial nits.

--
Michael Richardson <[email-masked]>, Sandelman Software Works  -= IPv6 IoT consulting =-

---

From: Michael Richardson <[email-masked]>
Date: Wed, 19 Jul 2017 14:12:37 +0200

Susan Hares <[email-masked]> wrote:
    > One challenge is that your point of view on IS-IS and OSPF models was
    > countered by the Yang doctor's review.  The YANG Doctor's early review
    > removed the CODE-BEGINS/CODE-ENDS.  However, you and the YANG Doctors
    > both have good points.  As chair, I'm going to have to the I2RS AD and
    > the OPS Advice on what to do.

Perhaps EXAMPLE-CODE-BEGINS.  That way it can still be extracted from the xml
via script, but the automatic draft yang validator won't see it.

---

From: "Susan Hares" <[email-masked]>
Date: Wed, 19 Jul 2017 08:13:23 -0400

That' a good idea. 

Sue 

-----Original Message-----
From: Michael Richardson [mailto:[email-masked]] 
Sent: Wednesday, July 19, 2017 8:13 AM
To: Susan Hares
Cc: [email-masked]; [email-masked];
[email-masked]; [email-masked]
Subject: Re: [RTG-DIR] RtgDir Early review: draft-ietf-i2rs-yang-l3-topology

    > the OPS Advice on what to do.

Perhaps EXAMPLE-CODE-BEGINS.  That way it can still be extracted from the
xml via script, but the automatic draft yang validator won't see it.

--
Michael Richardson <[email-masked]>, Sandelman Software Works  -=
IPv6 IoT consulting =-

---

From: Michael Richardson <[email-masked]>
Date: Wed, 19 Jul 2017 18:52:14 +0200

BTW: I complained about [email-masked]
     bouncing to ietf-action.

---

From: "Susan Hares" <[email-masked]>
Date: Wed, 19 Jul 2017 15:53:48 -0400

I'll ask why this happened.  Thank you for the note. 

Sue Hares 

-----Original Message-----
From: Michael Richardson [mailto:[email-masked]] 
Sent: Wednesday, July 19, 2017 12:52 PM
To: Susan Hares
Cc: [email-masked]; [email-masked];
[email-masked]; [email-masked]
Subject: Subject: [www.ietf.org/rt #176329] AutoReply: bounce for
[email-masked]

BTW: I complained about
[email-masked]
     bouncing to ietf-action.