Subject: Re: [Teas] not a Yangdoctor review of draft-ietf-teas-yang-te-types-03

From: tom petch <[email-masked]>
Date: Tue, 5 Feb 2019 14:47:28 +0000

Tarek

Getting there .

You will need to have a reference to the new I-D references in the body
of the I-D else you will get unused references.  One way to do this is
to have a Section 4.1 This module references [RFC3272]. [....  I have
not gone through and seen how many this applies to but imagine it is
most of them.

Also you have G.8031 but G808.  Not wrong, but...

      import ietf-routing-types { prefix "rt-types";
now has the right RFC but the wrong title; should be
Common YANG Data Types for the Routing Area

Tom Petch

----- Original Message -----
From: "Tarek Saad (tsaad)" <[email-masked]>
Sent: Thursday, January 31, 2019 2:10 PM

> Hi Tom,
>
> Thank again for your review comments below. We've uploaded version
04/-05 which attempts to address these comments.
> See inline [TS] for resolution.
>
> -----Original Message-----
> From: tom petch <[email-masked]>
> Date: Wednesday, January 23, 2019 at 12:13 PM
> To: Jan Lindblad <[email-masked]>, Tarek Saad <[email-masked]>
> Cc: "[email-masked]" <[email-masked]>,
"[email-masked]"
<[email-masked]>, "[email-masked]"
<[email-masked]>, "[email-masked]" <[email-masked]>
> Subject: [Teas] not a Yangdoctor review of
draft-ietf-teas-yang-te-types-03
>
>     Tarek
>
>     The YANG modules have lots of references - good - but they are not
in
>     the I-D references - not good.
>
>     My list is
>
>     3272
>     4202
>     4328
>     4657
>     5817
>     6004
>     6205
>     6511
>     7139
>     7308
>     7551
>     7571
>     7579
>     7951
>     G.808
>     G.8031
>     G.8131
>     G.873.1
>
> [TS]: thanks. I've added the missing references and they should show
in the I-D references now.
>
>     s.3.1 I would find more usable if the types were in an order I
could
>     recognise, such as alphabetical
>
> [TS]: OK, I tried an attempt to sort the typedefs alphabetically.
>
>       import ietf-routing-types { prefix "rt-types";
>     reference "RFC6991: Common YANG Data Types";
>     perhaps RFC8294 is intended
>
> [TS]: corrected to RFC8294
>
>     "   defined in ietf-network.yang, to help user to understand ""
>     might benefit from a reference - is this
>     draft-ietf-i2rs-yang-network-topo?
>
> [TS]: added reference RFC8345.
>
>     /"Then index of the label/ "The index of the label /
>
> [TS]: fixed typo.
>
>               container tiebreakers {
>                 description
>                   "The list of tiebreaker criterion to apply
>                    on an equally favored set of paths to pick best";
>                 list tiebreaker {
>                   description
>                   "The list of tiebreaker criterion to apply
>                      on an equally favored set of paths to pick best";
>     One description is perhaps enough
>
> [TS]: removed/updated redundant description.
>
>     uses path-objective-function_config;
>     using _ is not wrong but is discouraged, mixing _ with - in a
label more
>     so
>
> [TS]: OK, we have moved away from using "_" in the naming.
>
>     /This document registers a YANG module/
>     This document registers two YANG modules/
>
> [TS]: fixed typo.
>
>        name: ietf-te-types namespace:
urn:ietf:params:xml:ns:yang:ietf-te-
>        types prefix: ietf-te-types reference: RFC3209
>        name: ietf-te-packet-types namespace:
>        urn:ietf:params:xml:ns:yang:ietf-te-packet-types prefix:
ietf-te-
>        packet-types reference: RFC3209
>
>     Perhaps /3209/XXXX/
>
> [TS]: fixed.
>
> Regards,
> Tarek
>
>     Tom Petch
>
>     ----- Original Message -----
>     From: "Jan Lindblad" <[email-masked]>
>     To: "Tarek Saad (tsaad)" <[email-masked]>
>     Cc: <[email-masked]>;
>     <[email-masked]>; <[email-masked]>;
>     <[email-masked]>
>     Sent: Monday, January 21, 2019 10:10 AM
>     Subject: Re: [Teas] Yangdoctors early review of
>     draft-ietf-teas-yang-te-types-03 (was -01)
>
>
>     >
>
>
>
>

---

From: "Tarek Saad (tsaad)" <[email-masked]>
Date: Tue, 5 Feb 2019 20:11:59 +0000

Thanks, Tom. Please see inline below.

-----Original Message-----
From: tom petch <[email-masked]>
Date: Tuesday, February 5, 2019 at 9:47 AM
To: Tarek Saad <[email-masked]>, Jan Lindblad <[email-masked]>
Cc: "[email-masked]" <[email-masked]>, "[email-masked]" <[email-masked]>, "[email-masked]" <[email-masked]>, "[email-masked]" <[email-masked]>
Subject: Re: [Teas] not a Yangdoctor review of draft-ietf-teas-yang-te-types-03

    Tarek
    
    Getting there .
    
[TS]: unfortunate that the tool will flag those as warning as the I-D YANG module clearly references them.. I am wondering if there is a chance or a plan to enhance the IETF idnit tool to parse the YANG module for references and silence such warnings?

    Also you have G.8031 but G808.  Not wrong, but...
[TS]: G.8031 is already listed in references. G808 is still relevant. I've moved both to informative references as per other recommendations.

[TS]: thank you. I'll take care of this one in the next update.

Regards,
Tarek

    Tom Petch
    
    ----- Original Message -----
    From: "Tarek Saad (tsaad)" <[email-masked]>
    Sent: Thursday, January 31, 2019 2:10 PM
    
    in
    could
    label more
    ietf-te-

---

From: tom petch <[email-masked]>
Date: Thu, 7 Feb 2019 11:42:20 +0000

----- Original Message -----
From: "Tarek Saad (tsaad)" <[email-masked]>
Sent: Tuesday, February 05, 2019 8:11 PM

> [TS]: unfortunate that the tool will flag those as warning as the I-D
YANG module clearly references them.. I am wondering if there is a
chance or a plan to enhance the IETF idnit tool to parse the YANG module
for references and silence such warnings?

Well no, that would be wrong.

A YANG module needs references, for import statements and to tell the
user where to go for more information on the objects, their use and so
on.

A YANG module must be plain text so cannot contain the usual HTML/XML
style anchors that an I-D/RFC has.

Documents referenced from within an RFC must appear in the References of
that RFC.

Hence
 - anything referenced in the YANG module must be in the References of
the RFC
- anything referenced in the YANG module must have a HTML/XML style
reference somewhere in the RFC outside the YANG module.

Where such references do not crop up in the existing text of the memo
outside the YANG module, then the practice is to add a
Section X.1
before the YANG module saying words to the effect that this YANG module
imports from [. and references [....

So the tool wants enhancing to generate more warnings, not less, when
the contents of a a YANG reference clause do not appear in the Reference
section of the I-D.

HTH

I was unclear about my comment on G808; having the reference is find but
I would prefer G.808; I note that Deborah's e-mail used G.808 even when
referring to the 'G808' in the I-D so I think G.808 is to be preferred.

Tom Petch

> [TS]: G.8031 is already listed in references. G808 is still relevant.
I've moved both to informative references as per other recommendations.

---

From: "Tarek Saad (tsaad)" <[email-masked]>
Date: Thu, 7 Feb 2019 15:03:29 +0000

Hi Tom,

>>     reference somewhere in the RFC outside the YANG module.

[TS]: I don’t mind if it is a common practice to follow it.. However, I’d note as can be seen in the uploaded ver -05, I am able to have all references mentioned in YANG module show up in the references section of the I-D without explicitly needing cross-reference them in the I-D text outside of the YANG module. FWIW, kramdown-rfc2629 allows to list those at the top so they automatically get added to the references section.

Also, since I see (some) IETF tools are already parsing the I-D YANG module contents (e.g. for replacing RFC tags with HTML’zed URL links – see below), I would have thought it would be possible to determine such warnings were inaccurate..

“  == Unused Reference: 'RFCXXXX' is defined on line 3780, but no explicit

     reference was found in the text”

E.g.:

Liu, et al.                  Standards Track                    [Page 8]
________________________________
<https://tools.ietf.org/html/rfc8294#page-9>
RFC 8294<https://tools.ietf.org/html/rfc8294>                 Routing Area YANG Types           December 2017

      revision 2017-12-04 {
        description "Initial revision.";
        reference
          "RFC 8294<https://tools.ietf.org/html/rfc8294>: Common YANG Data Types for the Routing Area.
           Section 3<https://tools.ietf.org/html/rfc8294#section-3>.";
     }

     /*** Identities related to MPLS/GMPLS ***/

    identity mpls-label-special-purpose-value {
       description
         "Base identity for deriving identities describing
          special-purpose Multiprotocol Label Switching (MPLS) label
          values.";
       reference
         "RFC 7274<https://tools.ietf.org/html/rfc7274>: Allocating and Retiring Special-Purpose MPLS
          Labels.";
     }

     identity ipv4-explicit-null-label {
       base mpls-label-special-purpose-value;
       description
         "This identity represents the IPv4 Explicit NULL Label.";
       reference
         "RFC 3032<https://tools.ietf.org/html/rfc3032>: MPLS Label Stack Encoding.  Section 2.1<https://tools.ietf.org/html/rfc8294#section-2.1>.";
     }

Regards,

Tarek

-----Original Message-----

From: Teas <[email-masked]> on behalf of tom petch <[email-masked]>

Date: Thursday, February 7, 2019 at 6:42 AM

    ----- Original Message -----

    >     You will need to have a reference to the new I-D references in the

    body

    >     of the I-D else you will get unused references.  One way to do

    this is

    >     to have a Section 4.1 This module references [RFC3272]. [....  I

    have

    >     not gone through and seen how many this applies to but imagine it

    is

    on.

    that RFC.

    Hence

    the RFC

    Section X.1

    section of the I-D.

    HTH

    Tom Petch

    >     > Thank again for your review comments below. We've uploaded

    version

    >     >     The YANG modules have lots of references - good - but they

    are not

    >     > [TS]: thanks. I've added the missing references and they should

    show

    >     >     s.3.1 I would find more usable if the types were in an order

    I

    >     > [TS]: OK, I tried an attempt to sort the typedefs

    alphabetically.

    >     >     "   defined in ietf-network.yang, to help user to understand

    ""

    >     >                    on an equally favored set of paths to pick

    best";

    >     >                      on an equally favored set of paths to pick

    best";

    >     >     using _ is not wrong but is discouraged, mixing _ with - in

    a

    >     >     <[email-masked]>;

    <[email-masked]>;

    _______________________________________________

    Teas mailing list

    [email-masked]

    https://www.ietf.org/mailman/listinfo/teas

---

From: Italo Busi <[email-masked]>
Date: Thu, 7 Feb 2019 15:24:27 +0000

Hi  Tom,

Regarding your comment:

"I was unclear about my comment on G808; having the reference is find but I would prefer G.808; I note that Deborah's e-mail used G.808 even when referring to the 'G808' in the I-D so I think G.808 is to be preferred."

The draft references G.808 whenever it is possible

However, there are a couple of items which are common across multiple technologies but missing in G.808:
- signal-fail-of-protection which has higher priority than the FS command
- failure-of-protocol

In this case, the set of technology-specific Recommendations (G.8031, G.8131 and G.873.1) has been referenced instead of G.808

@Tarek: I have just noted the following nit in G.873.1 reference which can be easily fixed when you publish the next draft update:

OLD
   [G.873.1]  "G.8131 : Linear protection switching for MPLS transport
              profile", July 2014,

NEW
   [G.873.1]  "G.873.1 : Optical transport network (OTN):
             Linear protection", October 2017,

Italo

-----Original Message-----
From: tom petch [mailto:[email-masked]] 
Sent: giovedì 7 febbraio 2019 12:42
To: Tarek Saad (tsaad) <[email-masked]>; Jan Lindblad <[email-masked]>
Cc: [email-masked]; [email-masked]; [email-masked]; [email-masked]
Subject: Re: [Teas] not a Yangdoctor review of draft-ietf-teas-yang-te-types-03

----- Original Message -----
From: "Tarek Saad (tsaad)" <[email-masked]>
Sent: Tuesday, February 05, 2019 8:11 PM

body
this is
have
is
> [TS]: unfortunate that the tool will flag those as warning as the I-D
YANG module clearly references them.. I am wondering if there is a chance or a plan to enhance the IETF idnit tool to parse the YANG module for references and silence such warnings?

A YANG module needs references, for import statements and to tell the user where to go for more information on the objects, their use and so on.

A YANG module must be plain text so cannot contain the usual HTML/XML style anchors that an I-D/RFC has.

Documents referenced from within an RFC must appear in the References of that RFC.

Hence
 - anything referenced in the YANG module must be in the References of the RFC
- anything referenced in the YANG module must have a HTML/XML style reference somewhere in the RFC outside the YANG module.

Where such references do not crop up in the existing text of the memo outside the YANG module, then the practice is to add a Section X.1 before the YANG module saying words to the effect that this YANG module imports from [. and references [....

So the tool wants enhancing to generate more warnings, not less, when the contents of a a YANG reference clause do not appear in the Reference section of the I-D.

HTH

I was unclear about my comment on G808; having the reference is find but I would prefer G.808; I note that Deborah's e-mail used G.808 even when referring to the 'G808' in the I-D so I think G.808 is to be preferred.

Tom Petch

version
are not
show
I
alphabetically.
""
best";
best";
a
<[email-masked]>;

---

From: "Ryoo, Jeong-dong " <[email-masked]>
Date: Fri, 8 Feb 2019 01:38:23 +0000

Italo and all,

G.808 has a sentence about the priority in clause 3.2.8.10 as follows:

"For the case where an APS protocol is in use, an SF on the protection transport entity (over which the APS signal is routed) has priority over the forced switch."

Therefore, G.808 can be used for "signal-fail-of-protection."

For "failure-of-protocol," G.8031, G.8131 and G.873.1 should be referenced.

Best regards,

Jeong-dong

________________________________
보낸 사람 : "Italo Busi" <[email-masked]>
보낸 날짜 : 2019-02-08 00:25:04 ( +09:00 )
받는 사람 : tom petch <[email-masked]>, Tarek Saad (tsaad) <[email-masked]>, Jan Lindblad <[email-masked]>
참조 : [email-masked] <[email-masked]>, [email-masked] <[email-masked]>, [email-masked] <[email-masked]>, [email-masked] <[email-masked]>
제목 : Re: [Teas] not a Yangdoctor review of draft-ietf-teas-yang-te-types-03

Hi Tom,

Regarding your comment:

- failure-of-protocol

OLD

profile", July 2014,

NEW

Italo

-----Original Message-----

To: Tarek Saad (tsaad) ; Jan Lindblad

----- Original Message -----

From: "Tarek Saad (tsaad)"

> From: tom petch

body

this is

have

is

Hence

HTH

Tom Petch

> From: "Tarek Saad (tsaad)"

version

> > From: tom petch

> > To: Jan Lindblad , Tarek Saad

> > Cc: "[email-masked]" ,

> , "[email-masked]"

> , "[email-masked]"

are not

show

I

alphabetically.

""

best";

best";

a

> > From: "Jan Lindblad"

> > To: "Tarek Saad (tsaad)"

> > Cc: ;

> > ;

;

Teas mailing list

[email-masked]