Subject: [Gen-art] Gen-ART Telechat review of draft-ietf-isis-prefix-attributes-03

From: Paul Kyzivat <[email-masked]>
Date: Fri, 1 Jan 2016 09:53:55 -0500

I am the assigned Gen-ART reviewer for this draft. The General Area
Review Team (Gen-ART) reviews all IETF documents being processed by the
IESG for the IETF Chair. Please wait for direction from your document
shepherd or AD before posting a new version of the draft. For more
information, please see the FAQ at <​ 
http://wiki.tools.ietf.org/area/gen/trac/wiki/GenArtfaq>.

Document: draft-ietf-isis-prefix-attributes-03
Reviewer: Paul Kyzivat
Review Date: 2015-12-28
IETF LC End Date: 2016-01-01
IESG Telechat date: 2016-01-07

Summary:

There has been no new version since my LC review (below), so that review 
(ready with issues) still stands.

-------- Forwarded Message --------
Subject: [Gen-art] Gen-ART Last Call review of 
draft-ietf-isis-prefix-attributes-03
Date: Mon, 28 Dec 2015 14:18:05 -0500
From: Paul Kyzivat <[email-masked]>
To: [email-masked]
CC: General Area Review Team <[email-masked]>

I am the assigned Gen-ART reviewer for this draft. The General Area
Review Team (Gen-ART) reviews all IETF documents being processed by the
IESG for the IETF Chair. Please treat these comments just like any other
last call comments. For more information, please see the FAQ at
<http://wiki.tools.ietf.org/area/gen/trac/wiki/GenArtfaq>.

Document: draft-ietf-isis-prefix-attributes-03
Reviewer: Paul Kyzivat
Review Date: 2015-12-28
IETF LC End Date: 2016-01-01
IESG Telechat date: 2016-01-07

Summary:

This draft is on the right track but has open issues, described in the
review.

Major: 0
Minor: 4
Nits:  1

(1) Minor:

   The abstract and introduction both seem to assume that the
   reader has a lot of context about the intended scope of this
   document. For instance:

   - the abstract starts with "This document introduces new sub-TLVs",
     without any mention of to what they are subordinate;

   - the intro starts with "There are existing use cases in which
     knowing additional attributes of a prefix is useful." The
     uninitiated reader is left to figure out what sort of prefix
     (in this case network prefix) is being discussed.

   It would be helpful to state more of the context. Adding one or more
   references to the Introduction would also help. Keep in mind that
   once this is published as an RFC many people may see only the RFC
   number and the abstract, without even knowing that this is about
   routing. (And when looking at the title a different meaning of "ISIS"
   might first come to mind.)

   (Once I had the proper mind set, and had reviewed some of the related
   drafts and the relevant IANA registries, the draft finally made sense
   to me.)

(2) Minor / meta-editorial:

   I found it disconcerting that TLVs are referenced by their numeric
   type value rather than a name. And in this case the new sub-TLVs ar
   defined in a table that applies jointly to several different TLVs. I
   think it would be clearer if a name was given to this collection of
   TLVs, and used to discuss things that apply to all of them. (But,
   while I bring this up, I don't really expect that it makes sense to
   address it in the context of this draft. It it perhaps something
   better saved for a BIS to the entire IS-IS family.)

(3) Minor:

   The IANA considerations section says:

    This document adds the following new sub-TLVs to the registry of sub-
    TLVs for TLVs 135, 235, 236, 237.

   It doesn't explicitly indicate which registry this is. I suggest:

    This document adds the following new sub-TLVs to the "Sub-TLVs for
    TLVs 135, 235, 236, 237" table within the "IS-IS TLV Codepoints"
    registry.

   (Or some other wording recommended by IANA.) To their credit, IANA
   seems to have figured this out, since they already have placeholders
   in the table.

(4) Minor:

   Also in IANA considerations, in the definition of the new bit flags
   table,

   - the document ought to explicitly state the name it would like
     assigned to the new registry;

   - the name given in the IANA considerations section only includes the
     long name from section 2.1 (e.g., External Prefix Flag), not the
     short mnemonic name (e.g., X-Flag). Someone reading the IANA table
     might want to see the short name.

(5) Nit:

   And finally a typo in this section: "registery" should be "registry".

_______________________________________________
Gen-art mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/gen-art

---

From: "Les Ginsberg (ginsberg)" <[email-masked]>
Date: Sun, 3 Jan 2016 14:27:06 +0000

Paul -

> -----Original Message-----
> From: Paul Kyzivat [mailto:[email-masked]]
> Sent: Wednesday, December 30, 2015 12:31 PM
> To: Les Ginsberg (ginsberg); [email-masked]
> Cc: General Area Review Team
> Subject: Re: Gen-ART Last Call review of draft-ietf-isis-prefix-attributes-03
> 
> Hi Les,
> 
> Note that at the end of the day my comments are just suggestions. You can
> act on them or not. They only become binding if the IESG decides to raise
> them.

[Les:] I want you to know that I take your comments seriously - binding or not. You obviously invested time in reviewing - which I appreciate.

> 
> More inline.
> 
> On 12/30/15 12:46 PM, Les Ginsberg (ginsberg) wrote:
> > Paul -
> >
> > Thanx for the review.
> > Responses inline.
> >
> >> -----Original Message-----
> >> From: Paul Kyzivat [mailto:[email-masked]]
> >> Sent: Monday, December 28, 2015 11:18 AM
> >> Cc: General Area Review Team
> >> Subject: Gen-ART Last Call review of
> >> Review Team (Gen-ART) reviews all IETF documents being processed by
> >> the IESG for the IETF Chair. Please treat these comments just like
> >> any other last call comments. For more information, please see the
> >> FAQ at <http://wiki.tools.ietf.org/area/gen/trac/wiki/GenArtfaq>.
> >>
> > [Les:] Frankly, I have difficulties with your comments. I appreciate that they
> are coming from the POV of someone not familiar w IS-IS.
> >
> > There are a large number of RFCs which define extensions to the IS-IS
> protocol. None of these documents stand on their own. If the reader does
> not know what "IS-IS" is then I think it is safe to say the document is not
> something that would be useful to that reader.
> 
> Understood. But the abstract will be seen by many (like me) who don't fall
> into that category. They are left entirely in the dark about what this is about.
> Might it be something they *ought* to be interested in?
> After reading the abstract, the only clue I had about the scope of this
> document was the name of the wg from the draft name. And once this
> becomes an RFC that won't be available as a hint. I had to look up isis in the
> list of WGs to discover that this was in the routing area. Then I had to do
> more searching to figure out what IS-IS was about.
> 

[Les:] The title (even once it becomes an RFC) includes "IS-IS".  If you don't know that IS-IS is a routing protocol, do you think that further clarification is needed to help you understand that this isn't something which you are interested in reading?

> So I'm not suggesting that the document to stand on its own. But just enough
> in the abstract to help the reader decide if he should look further would help.
> And just enough more in the intro to identify other documents that provide
> the context for this one would help the reader get the proper context.
> 
> > In regards to "other meanings" for the term "ISIS", I would only
> > comment that the protocol and the name originate from work done in the
> > 1980's. If in recent years other uses/contexts for the name have
> > become part of modern discussion this does not require this draft (or
> > any other IS-IS WG document) to address this. (This is as "politically
> > correct" a statement as I can make. :-) )
> 
> Yes, this was mostly a tongue-in-cheek comment.
> 
> > In regards to the abstract, brevity is a stated requirement for an abstract
> (see http://www.ietf.org/id-info/guidelines.html#anchor11). Yes, if you
> want to find out what prefix attributes can be advertised and in what TLVs
> these advertisements may appear you have to read the body of the
> document. I do not apologize for that. IMO the abstract does what it is
> intended to do - succinctly summarize the topics which are covered in the
> document and I think adding additional detail (such as the TLVs which have
> been affected) would not serve the purpose of the abstract.
> 
> I was only looking for another word or two.
> 
> > In regards to the term "prefix", you seem to be expecting the document to
> define that term - but in looking at multiple RFCs I do not see precedent for
> that. It is part of the base knowledge that has been assumed that readers
> understand . Perhaps this is a bad practice - but if so there are many
> documents - not restricted solely to IS-IS related documents - that could be
> critiqued on this basis. I would ask that this comment be viewed in a larger
> context - I don't think this particular draft should be asked to deviate from
> common practice without larger guidance from the IETF community.
> 
> Not a definition, just a disambiguation. Simply replacing "prefix" with
> "network prefix" would have met my need.
> 

[Les:] You are proposing that "prefix" be replaced by "network prefix" throughout the document?
This has not been done in any of the existing RFCs that I checked.

> > In regards to "references to the Introduction", I emphasize that the
> Introduction is neither normative nor exhaustive. It is meant to provide some
> examples of cases where the information contained in the new
> advertisements could be useful. I therefore find that references to it would
> be inappropriate.
> 
> I guess I wasn't clear. I was suggesting that reference(s) be added to the
> introduction. (References are not permitted in the abstract, but they are
> allowed in the intro.) A reference to the base specification for the internet
> version of IS-IS would have helped me.
> 

[Les:] I usually constrain references to those which are actually useful in the context of the topics being discussed in the draft. Base specifications are not directly referenced in this draft because we are extending TLVs which were defined in RFCs issued long after the base specifications were published. However, the following could be added to the introduction:

"IS-IS is a link state routing protocol defined in [ISO10589] and [RFC1195].  Extensions in support of advertising new forms of IP/IPv6 prefix reachability are defined in [RFC5305], [RFC5308], and [RFC5120]."

Is this what you had in mind?

   Les

> > [Les:] The registry being modified is officially named " Sub-TLVs for TLVs
> 135, 235, 236, and 237" (http://www.iana.org/assignments/isis-tlv-
> codepoints/isis-tlv-codepoints.xhtml#isis-tlv-codepoints-135-235-236-237 )-
> so using TLV numbers is both a common practice and definitive. In the case
> of TLVs used for prefix advertisement because there are multiple TLVs
> involved (including "old style" TLVs 128 and 130 which are NOT modified by
> the draft), the use of numbers is also considerably more succinct. An
> accurate replacement would require the following text:
> >
> > " Extended IP reachability and MT IP. Reachability and IPv6 IP Reachability
> and MT IPv6 IP Reachability"
> >
> > Perhaps you can appreciate why we prefer to use numbers. :-)
> 
> Yes, it was pretty clear that direct use of the numbers is a well
> established convention. And I don't suggest that you try to change it in
> this draft. Still, to an outside observer it seems like a very user
> unfriendly way to do things.
> 
> >> (3) Minor:
> >>
> > [Les:] As stated above, the document uses the official name of the existing
> registry. However, as IANA rewrites these sections anyway I am fine with
> whatever wording they choose to use.
> >
> >>
> > [Les:] The "placeholders" exist because of early allocation requests made
> as defined in RFC 7370.
> 
> I suppose there is no need to do anything since IANA has figured it out.
> 
> >> (4) Minor:
> >>
> > [Les:] Guilty as charged. IANA has asked the same question in their review -
> I will provide the suggested name in my response to them.
> >
> >
> >>
> > [Les:] The short names exist to aid in the pictorial representation of the
> field. In existing bit registries (e.g. http://www.iana.org/assignments/isis-tlv-
> codepoints/isis-tlv-codepoints.xhtml#isis-tlv-codepoints-19of22 ) only a long
> name is used. But I have no objection to including the short names.
> 
> It is your call. I just imagine those who care about this will most
> often refer to the short names, so having them in the registry makes
> sense to me.
> 
> >> (5) Nit:
> >>
> > [Les:] ACK
> >     Les
> 	Best wishes,
> 	Paul

---

From: Paul Kyzivat <[email-masked]>
Date: Sun, 3 Jan 2016 15:49:05 -0500

Hi Les,

Trimming to the relevant points:

> [Les:] I want you to know that I take your comments seriously - binding or not. You obviously invested time in reviewing - which I appreciate.

Thanks. Genart is educational for the reviewers (at least for me) 
because we are usually reviewing things we know nothing about! It often 
takes some sniffing around to gain enough context to do the review.

But I think that is the point of genart - to get a review from somebody 
who doesn't already know the subject.

> [Les:] The title (even once it becomes an RFC) includes "IS-IS".  If you don't know that IS-IS is a routing protocol, do you think that further clarification is needed to help you understand that t…

It is sufficient to get people to stop reading and ignore it. Maybe that 
is enough.

But for the person who goes a step further and pulls the full document 
and still doesn't know, it would be nice to add an informative reference 
to the intro, to a base document for IS-IS. As best I can tell, the 
likely one is RFC1195. For example, revise the first sentence of the intro:

    There are existing use cases for IS-IS [RFC1195] in which knowing
    additional attributes of a network prefix is useful.

> This has not been done in any of the existing RFCs that I checked.

Not everywhere, just one or a few places - say in the abstract and the 
intro.

> Is this what you had in mind?

Yes.

	Thanks,
	Paul

---

From: "Les Ginsberg (ginsberg)" <[email-masked]>
Date: Mon, 4 Jan 2016 03:53:50 +0000

Paul -

Attached is a diff file w the changes I have made to address your comments. Please let me know if this suffices.

(co-authors - please let me know if you have any concerns regarding the proposed changes)

Thanx.

   Les

> Sent: Sunday, January 03, 2016 12:49 PM
> >> Note that at the end of the day my comments are just suggestions. You
> >> can act on them or not. They only become binding if the IESG decides
> >> to raise them.
> >
> > [Les:] I want you to know that I take your comments seriously - binding or
> not. You obviously invested time in reviewing - which I appreciate.
> 
> Thanks. Genart is educational for the reviewers (at least for me) because we
> are usually reviewing things we know nothing about! It often takes some
> sniffing around to gain enough context to do the review.
> 
> But I think that is the point of genart - to get a review from somebody who
> doesn't already know the subject.
> 
> >> Understood. But the abstract will be seen by many (like me) who don't
> >> fall into that category. They are left entirely in the dark about what this is
> about.
> >> After reading the abstract, the only clue I had about the scope of
> >> this document was the name of the wg from the draft name. And once
> >> this becomes an RFC that won't be available as a hint. I had to look
> >> up isis in the list of WGs to discover that this was in the routing
> >> area. Then I had to do more searching to figure out what IS-IS was about.
> >>
> >
> > [Les:] The title (even once it becomes an RFC) includes "IS-IS".  If you don't
> know that IS-IS is a routing protocol, do you think that further clarification is
> needed to help you understand that this isn't something which you are
> interested in reading?
> 
> It is sufficient to get people to stop reading and ignore it. Maybe that is
> enough.
> 
> But for the person who goes a step further and pulls the full document and
> still doesn't know, it would be nice to add an informative reference to the
> intro, to a base document for IS-IS. As best I can tell, the likely one is
> RFC1195. For example, revise the first sentence of the intro:
> 
> >> define that term - but in looking at multiple RFCs I do not see
> >> precedent for that. It is part of the base knowledge that has been
> >> assumed that readers understand . Perhaps this is a bad practice -
> >> but if so there are many documents - not restricted solely to IS-IS
> >> related documents - that could be critiqued on this basis. I would
> >> ask that this comment be viewed in a larger context - I don't think
> >> this particular draft should be asked to deviate from common practice
> without larger guidance from the IETF community.
> >>
> >> Not a definition, just a disambiguation. Simply replacing "prefix"
> >> with "network prefix" would have met my need.
> >>
> >
> Not everywhere, just one or a few places - say in the abstract and the intro.
> 
> >> Introduction is neither normative nor exhaustive. It is meant to
> >> provide some examples of cases where the information contained in the
> >> new advertisements could be useful. I therefore find that references
> >> to it would be inappropriate.
> >>
> >> I guess I wasn't clear. I was suggesting that reference(s) be added
> >> to the introduction. (References are not permitted in the abstract,
> >> but they are allowed in the intro.) A reference to the base
> >> specification for the internet version of IS-IS would have helped me.
> >>
> >
> > [Les:] I usually constrain references to those which are actually useful in the
> context of the topics being discussed in the draft. Base specifications are not
> directly referenced in this draft because we are extending TLVs which were
> defined in RFCs issued long after the base specifications were published.
> However, the following could be added to the introduction:
> >
> > "IS-IS is a link state routing protocol defined in [ISO10589] and [RFC1195].
> Extensions in support of advertising new forms of IP/IPv6 prefix reachability
> are defined in [RFC5305], [RFC5308], and [RFC5120]."
> >

---

From: Xuxiaohu <[email-masked]>
Date: Mon, 4 Jan 2016 03:59:32 +0000

Hi Les,

The modification looks fine to me.

Best regards,
Xiaohu

> From: Les Ginsberg (ginsberg) [mailto:[email-masked]]
> Sent: Monday, January 04, 2016 11:54 AM
> To: Paul Kyzivat; [email-masked]
> Subject: RE: Gen-ART Last Call review of draft-ietf-isis-prefix-attributes-03
> 
> Paul -
> 
> > To: Les Ginsberg (ginsberg);
> > [email-masked]
> > >> Note that at the end of the day my comments are just suggestions.
> > >> You can act on them or not. They only become binding if the IESG
> > >> decides to raise them.
> > >
> > because we are usually reviewing things we know nothing about! It
> > often takes some sniffing around to gain enough context to do the review.
> >
> > But I think that is the point of genart - to get a review from
> > somebody who doesn't already know the subject.
> >
> > >> Understood. But the abstract will be seen by many (like me) who
> > >> don't fall into that category. They are left entirely in the dark
> > >> about what this is
> > about.
> > >> this becomes an RFC that won't be available as a hint. I had to
> > >> look up isis in the list of WGs to discover that this was in the
> > >> routing area. Then I had to do more searching to figure out what IS-IS was
> about.
> > >>
> > >
> > know that IS-IS is a routing protocol, do you think that further
> > clarification is needed to help you understand that this isn't
> > something which you are interested in reading?
> >
> > It is sufficient to get people to stop reading and ignore it. Maybe
> > that is enough.
> >
> > and still doesn't know, it would be nice to add an informative
> > reference to the intro, to a base document for IS-IS. As best I can
> > tell, the likely one is RFC1195. For example, revise the first sentence of the
> intro:
> >
> > >> provide some examples of cases where the information contained in
> > >> the new advertisements could be useful. I therefore find that
> > >> references to it would be inappropriate.
> > >>
> > context of the topics being discussed in the draft. Base
> > specifications are not directly referenced in this draft because we
> > are extending TLVs which were defined in RFCs issued long after the base
> specifications were published.
> > Extensions in support of advertising new forms of IP/IPv6 prefix
> > reachability are defined in [RFC5305], [RFC5308], and [RFC5120]."
> > >

---

From: Paul Kyzivat <[email-masked]>
Date: Mon, 4 Jan 2016 09:38:25 -0500

Les,

This works for me.

	Thanks,
	Paul

---

From: Uma Chunduri <[email-masked]>
Date: Mon, 4 Jan 2016 19:01:39 +0000

Les,

Changes look good to me. 

New year wishes to all.

--
Uma C.

-----Original Message-----
From: Les Ginsberg (ginsberg) [mailto:[email-masked]] 
Sent: Sunday, January 03, 2016 7:54 PM
To: Paul Kyzivat; [email-masked]
Cc: General Area Review Team
Subject: RE: Gen-ART Last Call review of draft-ietf-isis-prefix-attributes-03

Paul -

Thanx.

   Les

> >> routing area. Then I had to do more searching to figure out what IS-IS was about.
> >>
> >
> tell, the likely one is RFC1195. For example, revise the first sentence of the intro:
> 
> are extending TLVs which were defined in RFCs issued long after the base specifications were published.

---

From: Paul Kyzivat <[email-masked]>
Date: Tue, 5 Jan 2016 09:42:47 -0500

Document: draft-ietf-isis-prefix-attributes-04
Reviewer: Paul Kyzivat
Review Date: 2015-12-28
IETF LC End Date: 2016-01-01
IESG Telechat date: 2016-01-07

Summary:

The -04 version addressed my LC comments on the -03 version.

This draft is ready for publication as a Standards Track RFC.

Major: 0
Minor: 0
Nits: 0

---

From: Jari Arkko <[email-masked]>
Date: Thu, 7 Jan 2016 14:53:49 +0200

Paul et al: Thanks for the review & the updates!

jari

On 05 Jan 2016, at 16:42, Paul Kyzivat <[email-masked]> wrote:

> information, please see the FAQ at <​ http://wiki.tools.ietf.org/area/gen/trac/wiki/GenArtfaq>.
>