Subject: [Gen-art] Gen-art LC review: draft-ietf-l2vpn-vpls-ldp-mac-opt-11

From: Robert Sparks <[email-masked]>
Date: Mon, 07 Apr 2014 14:41:03 -0500

I am the assigned Gen-ART reviewer for this draft. For background on
Gen-ART, please see the FAQ at

<http://wiki.tools.ietf.org/area/gen/trac/wiki/GenArtfaq>.

Please resolve these comments along with any other Last Call comments
you may receive.

Document: draft-ietf-l2vpn-vpls-ldp-mac-opt-11
Reviewer: Robert Sparks
Review Date: 7Apr2014
IETF LC End Date: 8Apr2014
IESG Telechat date: not yet scheduled

Summary: This draft is almost ready for publication as a Proposed 
Standard, but has minor issues (primarily editorial) that should be 
addressed.

I found this document very difficult to read. It asks the reader to hop 
between sections in unusual ways (for instance, it sends the reader to 
the problem statement section for details on normative behavior). I 
strongly encourage an editorial pass focusing on document structure.

There are many instances of SHOULD in the document where the text should 
just be using prose instead. It's not always clear when an 
implementation would choose to ignore the SHOULD, and what the 
consequences of that choice would be.

The document is inconsistent about the level of support needed in the 
network before trying to use this extension.
Section 5.1.2 says the assumption is everything understands it before 
it's turned on. Section 6 points back to figure 2 and says
to use the extension over the pw where you administratively know the 
peer supports the extension, and fall back to 4762 for
everything else. Which of those did you intend?

Specific comments in document order:

Section 3.2 paragraph 1: This paragraph would benefit from being broken 
into several. It's hard to find its point. The SHOULD in this paragraph 
is probably not a 2119 SHOULD (this section isn't defining the 
protocol). It would be useful in this overview to explicitly say _why_ 
"This cannot be achieved with ... 4762]" at this point in the document.

Section 3.2 paragraph 2: This SHOULD _is_ defining protocol - shouldn't 
it be in section 5?

Section 4.1.1 paragraph 3: It took me some time to find Z on the figure. 
It might help to introduce it similar to how you introduce X.

Section 4.1.2: paragraph 1: I think you meant to reference 4.1.1

Section 5: The first sentence talks about requirements in section 4. 
Section 4 describes a problem using some examples but doesn't explicitly 
call out requirements. Doing so would help the document.

Last sentence in 5.1.1 (and several other places in the document): 
Please add an article before "MAC Flush message".  (I apologize for such 
a small nit, but each of these instances made making sure I was reading 
what the sentence intended significantly more difficult).

Section 5.1.2 first paragraph: This section is defining behavior - why 
are you sending the reader back into the problem statement for detail on 
the behavior?

5.1.2 paragraph 2: You meant section 6, not 5.

5.1.2 paragraph 3: I can't follow this paragraph's structure. I think 
you're trying to say "An MTU-s or PE2-rs SHOULD send MAC withdraw 
messages as defined in [RFC4762] in cases where the network is being 
upgraded and devices are not capable of understanding the optimized MAC 
flush." (But if so, the next sentence is redundant.) Why is this SHOULD?

5.1.3 paragraph 1: Why is this a SHOULD and not a MUST? (Similar 
question for the SHOULD in paragraph 2). It's not clear if you're trying 
to avoid "Some things won't implement this spec" or "Don't do this if 
you haven't administratively ensured every element understands this 
extension first" or something else?

5.1.3 paragraph 3: You say "unless specified otherwise". Do you ever 
specify otherwise? Why is this disclaimer here?

5.1.3 last paragraph: You meant section 6 not 5.

---

From: "Adrian Farrel" <[email-masked]>
Date: Thu, 10 Apr 2014 17:12:51 +0100

Thanks Robert,

Will be interested to hear author/shepherd responses to this.

Adrian

> -----Original Message-----
> From: L2vpn [mailto:[email-masked]] On Behalf Of Robert Sparks
> Sent: 07 April 2014 20:41
> To: General Area Review Team;
[email-masked];
> [email-masked]
> Subject: Gen-art LC review: draft-ietf-l2vpn-vpls-ldp-mac-opt-11
>

---

From: "Fedyk, Don" <[email-masked]>
Date: Thu, 10 Apr 2014 16:25:10 +0000

Hi Robert

Thanks for your comments.

Inline [Don]

I've incorporated your feedback in the latest draft which I will distribute and check with authors and ADs and Chairs shortly. 

Don.

-----Original Message-----
From: L2vpn [mailto:[email-masked]] On Behalf Of Robert Sparks
Sent: Monday, April 07, 2014 3:41 PM
To: General Area Review Team; [email-masked]; [email-masked]
Subject: Gen-art LC review: draft-ietf-l2vpn-vpls-ldp-mac-opt-11

I am the assigned Gen-ART reviewer for this draft. For background on Gen-ART, please see the FAQ at

Please resolve these comments along with any other Last Call comments you may receive.

Summary: This draft is almost ready for publication as a Proposed Standard, but has minor issues (primarily editorial) that should be addressed.

I found this document very difficult to read. It asks the reader to hop between sections in unusual ways (for instance, it sends the reader to the problem statement section for details on normative behavior). I strongly encourage an editorial pass focusing on document structure.
[Don] Will work with AD to see what can be done here.  
There are many instances of SHOULD in the document where the text should just be using prose instead. It's not always clear when an implementation would choose to ignore the SHOULD, and what the consequences of that choice would be.
[Don] I'll check this. 

The document is inconsistent about the level of support needed in the network before trying to use this extension.
Section 5.1.2 says the assumption is everything understands it before it's turned on. Section 6 points back to figure 2 and says to use the extension over the pw where you administratively know the peer supports the extension, and fall back to 4762 for everything else. Which of those did you intend?
[Don] I will clarify.   
Specific comments in document order:

Section 3.2 paragraph 1: This paragraph would benefit from being broken into several. It's hard to find its point. The SHOULD in this paragraph is probably not a 2119 SHOULD (this section isn't defining the protocol). It would be useful in this overview to explicitly say _why_ "This cannot be achieved with ... 4762]" at this point in the document.
[Don] Will address this .

Section 3.2 paragraph 2: This SHOULD _is_ defining protocol - shouldn't it be in section 5?
[Don] Agree. 

[Don] OK

[Don] Done.

Section 5: The first sentence talks about requirements in section 4. 
Section 4 describes a problem using some examples but doesn't explicitly call out requirements. Doing so would help the document.
[[Don]] Renamed Problem Space as recommended by Ben. 

Last sentence in 5.1.1 (and several other places in the document): 
Please add an article before "MAC Flush message".  (I apologize for such a small nit, but each of these instances made making sure I was reading what the sentence intended significantly more difficult).
[Don] OK. 

Section 5.1.2 first paragraph: This section is defining behavior - why are you sending the reader back into the problem statement for detail on the behavior?
[Don] s/4.2/5.2/

[Don] Done.

5.1.2 paragraph 3: I can't follow this paragraph's structure. I think you're trying to say "An MTU-s or PE2-rs SHOULD send MAC withdraw messages as defined in [RFC4762] in cases where the network is being upgraded and devices are not capable of understanding the optimized MAC flush." (But if so, the next sentence is redundant.) Why is this SHOULD?
[Don] Updated. 

5.1.3 paragraph 1: Why is this a SHOULD and not a MUST? (Similar question for the SHOULD in paragraph 2). It's not clear if you're trying to avoid "Some things won't implement this spec" or "Don't do this if you haven't administratively ensured every element understands this extension first" or something else?
[Don] Changed to MUST for optimized MAC Flush. 

5.1.3 paragraph 3: You say "unless specified otherwise". Do you ever specify otherwise? Why is this disclaimer here?
[Don] Removed.

[Don] Done.