Subject: [Detnet] Genart last call review of draft-ietf-detnet-use-cases-18

From: Pete Resnick <[email-masked]>
Date: Thu, 04 Oct 2018 11:02:23 -0700

Reviewer: Pete Resnick
Review result: Ready with Nits

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

<https://trac.ietf.org/trac/gen/wiki/GenArtfaq>.

Document: draft-ietf-detnet-use-cases-18
Reviewer: Pete Resnick
Review Date: 2018-10-04
IETF LC End Date: 2018-10-03
IESG Telechat date: Not scheduled for a telechat

Summary: Ready with Nits

This was a really cool document to read simply because of the breadth of the
industries involved. It clearly is going to need a good grammatical editing
pass by the RFC Editor, but none of the errors are the kind that make the text
hard to understand. All of my comments below are editorial in nature.

Major issues: None

Minor issues: None

Nits/editorial comments: For all of the below, the world does not end if you
don't fix them, but please consider:

----

Abstract: The first paragraph of intro seems like a better abstract. I don't
think the abstract needs as much detail as you've got in there.

----

The Intro says:

   For DetNet, use cases explicitly do not define requirements; The
   DetNet WG will consider the use cases, decide which elements are in
   scope for DetNet, and the results will be incorporated into future
   drafts.

Then why was 2.1.4 removed? It seems like it might be useful for historical
context.

----

In general, I don't like using "we" in consensus documents because it makes it
ambiguous whether the "we" is the "the author(s), "the detnet WG"", "the IETF",
or "this document". Additionally, using phrases like "we believe" or "we think"
are superfluous in most cases. Search for " we" and think about how to get rid
of such uses. A few examples:

2.2 I think you can simply just delete "we believe that". This document is
making a statement; no reason to hedge.

4.3 "In the future we expect". Changing to the passive voice solves the
problem: "It is expected that in the future"

5.3.2.1 "We would like to see DetNet define such a protocol". Detnet is the
author of this document, so "we" here seems really weird.

There are many other examples. Doing a search for " we " and seeing if you can
clean them up would be useful.

----

Throughout 3.1.1, 6.1.2, 7.3, 7.4: I presume "###us" is meant to be "###µs". I
believe I-Ds are now allowed to have such characters.

----

In 3.3.2.3, there is no discussion about how this relates to NTP. I'm not sure
if that is necessary, but it seems odd for an IETF document.

----

I like that you have security considerations sprinkled throughout the document
instead of trying to combine them into one big section. However, some of the
sections are missing security considerations. For example, I think even I could
come up with some security considerations for the mining industry case. SECDIR
might have more to say, but I think it's worth adding these.

----

The FQDN idnit is because of Juergen Schmitt's email address, and it is fine.

---

From: "Grossman, Ethan A." <[email-masked]>
Date: Fri, 5 Oct 2018 18:50:23 +0000

Hi Pete,
Thank you very much for your review input. As editor of this draft, here are my comments, questions and some proposed resolutions. Please let me know what you think.

1. Abstract: OK, I will look at streamlining it, one way or another.

2. Sec 2.1.4 (deterministic time to start streaming): I agree that keeping some things for historical context is useful, and I did not remove the section entirely for exactly that reason; I was attempting to keep the general topic but just refer to the earlier draft for additional info, which the reader could look up if they were interested. The downside of this approach is that such text can't be formally referenced. In this case I still think this is appropriate - do you know of other reasons why you don't think this approach is sufficient in this case? Having said all that, I wouldn't mind putting back the supporting text, in addition to the "out of scope" message, if you feel that would be worthwhile. 

3. Use of "we": Good point, I agree and will review that voicing throughout the draft. The reason it came about was that the original framing of the draft was "what does your industry want from DetNet", and each use case was written by a team from that industry. So the "we" isn't exactly "DetNet" it is more like "the proponents of this specific use case". But still I agree that "we" should be expunged. 

4. microseconds: OK, I will replace use of "usec" or "us" with "µsec". 

5. Relation to NTP: From the DetNet perspective timekeeping is considered part of network implementation and is not specified by DetNet. The fact that the Utilities use case mentions PTP at all, leave alone not mentioning NTP, is incidental to that use case. So I would not be inclined to change anything here, but if anyone else wants to chime in, please do. 

6. Security: Individual use cases may make some reference to the security implications of their particular use case, but this list of use cases is by no means exhaustive; there will inevitably be new ones. I note that you appreciate including security considerations in separate sections :- ) but thus far we have opted to gather the DetNet security considerations into a separate draft that applies to DetNet networks in aggregate; if you haven't already, please see https://datatracker.ietf.org/doc/draft-ietf-detnet-security/. Regarding specific security considerations for each use case (e.g. Mining) my take (as editor of the DetNet Security draft) is that security design is part of the overall network design, and that the DetNet Security draft attempts to address only the aspects of network security that are specific to time sensitive IP based networks, which might be "new" to IP based network designers, and thus might not be addressed elsewhere. I don't feel that requiring the use case authors to each contribute a thorough security discussion for their application seems appropriate, but that's just my take.

7. Grammar: Each use case was contributed by a different group of authors, with widely varying writing styles. As editor I attempted to clarify the intended meaning, which it seems per your comment that I did succeed in doing, however I didn't attempt to fix every grammatical issue. Sometimes this was due to my concern about inadvertently changing the meaning of the statements, sometimes I just decided to leave in place the original author's wording and style if it didn't materially compromise comprehension. I am not sure what the RFC Editor would do with this material, and I'm not sure to what extent I should make another pass at "fixing grammar" rather than leaving it to the RFC Editor, if they are going to take that on. I'm open to input on this. 

Thanks again for your valuable review input, and please let me know if the above resolutions make sense to you. 
Best,
Ethan (as editor of the DetNet Use Cases draft).

-----Original Message-----
From: Pete Resnick <[email-masked]> 
Sent: Thursday, October 04, 2018 11:02 AM
To: [email-masked]
Cc: [email-masked]; [email-masked]; [email-masked]
Subject: Genart last call review of draft-ietf-detnet-use-cases-18

Reviewer: Pete Resnick

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.

Summary: Ready with Nits

This was a really cool document to read simply because of the breadth of the industries involved. It clearly is going to need a good grammatical editing pass by the RFC Editor, but none of the errors are the kind that make the text hard to understand. All of my comments below are editorial in nature.

Major issues: None

Minor issues: None

Nits/editorial comments: For all of the below, the world does not end if you don't fix them, but please consider:

----

Abstract: The first paragraph of intro seems like a better abstract. I don't think the abstract needs as much detail as you've got in there.

----

The Intro says:

Then why was 2.1.4 removed? It seems like it might be useful for historical context.

----

In general, I don't like using "we" in consensus documents because it makes it ambiguous whether the "we" is the "the author(s), "the detnet WG"", "the IETF", or "this document". Additionally, using phrases like "we believe" or "we think"
are superfluous in most cases. Search for " we" and think about how to get rid of such uses. A few examples:

2.2 I think you can simply just delete "we believe that". This document is making a statement; no reason to hedge.

5.3.2.1 "We would like to see DetNet define such a protocol". Detnet is the author of this document, so "we" here seems really weird.

There are many other examples. Doing a search for " we " and seeing if you can clean them up would be useful.

----

Throughout 3.1.1, 6.1.2, 7.3, 7.4: I presume "###us" is meant to be "###µs". I believe I-Ds are now allowed to have such characters.

----

In 3.3.2.3, there is no discussion about how this relates to NTP. I'm not sure if that is necessary, but it seems odd for an IETF document.

----

I like that you have security considerations sprinkled throughout the document instead of trying to combine them into one big section. However, some of the sections are missing security considerations. For example, I think even I could come up with some security considerations for the mining industry case. SECDIR might have more to say, but I think it's worth adding these.

----

---

From: "Pete Resnick" <[email-masked]>
Date: Sun, 07 Oct 2018 11:54:41 -0500

On 5 Oct 2018, at 13:50, Grossman, Ethan A. wrote:

> Hi Pete,
> Thank you very much for your review input. As editor of this draft, 
> here are my comments, questions and some proposed resolutions. Please 
> let me know what you think.
>

Cool, thanks.

> 2. Sec 2.1.4 (deterministic time to start streaming): I agree that 
> keeping some things for historical context is useful, and I did not 
> remove the section entirely for exactly that reason; I was attempting 
> to keep the general topic but just refer to the earlier draft for 
> additional info, which the reader could look up if they were 
> interested. The downside of this approach is that such text can't be 
> formally referenced. In this case I still think this is appropriate - 
> do you know of other reasons why you don't think this approach is 
> sufficient in this case? Having said all that, I wouldn't mind putting 
> back the supporting text, in addition to the "out of scope" message, 
> if you feel that would be worthwhile.

The RFC Editor is not going to be onboard with a reference to what is 
officially a non-existent document. That said, I am not insistent that 
you put it back in; I don't know if it's worth mentioning. But I don't 
think this sort-of-in-sort-of-out state is a good idea.

> 3. Use of "we": Good point, I agree and will review that voicing 
> throughout the draft. The reason it came about was that the original 
> framing of the draft was "what does your industry want from DetNet", 
> and each use case was written by a team from that industry. So the 
> "we" isn't exactly "DetNet" it is more like "the proponents of this 
> specific use case". But still I agree that "we" should be expunged.

I figured as much. Not a huge deal, but nice if you can do it.

> 4. microseconds: OK, I will replace use of "usec" or "us" with 

Ack.

> 5. Relation to NTP: From the DetNet perspective timekeeping is 
> considered part of network implementation and is not specified by 
> DetNet. The fact that the Utilities use case mentions PTP at all, 
> leave alone not mentioning NTP, is incidental to that use case. So I 
> would not be inclined to change anything here, but if anyone else 
> wants to chime in, please do.

Ack.

> 6. Security: Individual use cases may make some reference to the 
> security implications of their particular use case, but this list of 
> use cases is by no means exhaustive; there will inevitably be new 
> ones. I note that you appreciate including security considerations in 
> separate sections :- ) but thus far we have opted to gather the DetNet 
> security considerations into a separate draft that applies to DetNet 
> networks in aggregate; if you haven't already, please see 
> https://datatracker.ietf.org/doc/draft-ietf-detnet-security/. 
> Regarding specific security considerations for each use case (e.g. 
> Mining) my take (as editor of the DetNet Security draft) is that 
> security design is part of the overall network design, and that the 
> DetNet Security draft attempts to address only the aspects of network 
> security that are specific to time sensitive IP based networks, which 
> might be "new" to IP based network designers, and thus might not be 
> addressed elsewhere. I don't feel that requiring the use case authors 
> to each contribute a thorough security discussion for their 
> application seems appropriate, but that's just my take.

Ah, I hadn't realized there was a separate security document. A 
reference would be good. A simple suggestion then: Make a "Security 
Considerations" section in this document that simply says something 
like: "Specific discussions of security considerations for particular 
use cases are noted throughout this document. A more complete discussion 
of security considerations can be found in 
[draft-ietf-detnet-security]."

> 7. Grammar: Each use case was contributed by a different group of 
> authors, with widely varying writing styles. As editor I attempted to 
> clarify the intended meaning, which it seems per your comment that I 
> did succeed in doing, however I didn't attempt to fix every 
> grammatical issue. Sometimes this was due to my concern about 
> inadvertently changing the meaning of the statements, sometimes I just 
> decided to leave in place the original author's wording and style if 
> it didn't materially compromise comprehension. I am not sure what the 
> RFC Editor would do with this material, and I'm not sure to what 
> extent I should make another pass at "fixing grammar" rather than 
> leaving it to the RFC Editor, if they are going to take that on. I'm 
> open to input on this.

Totally understood. Leaving the grammar corrections to the RFC Editor is 
fine, and they'll be able to make it all consistent across the sections. 
And they're very good about avoiding breaking meanings when they do 
their edits.

> Ethan (as editor of the DetNet Use Cases draft).

Thanks for the complete response.

pr

> 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.
>
> This was a really cool document to read simply because of the breadth 
> of the industries involved. It clearly is going to need a good 
> grammatical editing pass by the RFC Editor, but none of the errors are 
> the kind that make the text hard to understand. All of my comments 
> below are editorial in nature.
>
> Major issues: None
>
> Minor issues: None
>
> Nits/editorial comments: For all of the below, the world does not end 
> if you don't fix them, but please consider:
>
> ----
>
> Abstract: The first paragraph of intro seems like a better abstract. I 
> don't think the abstract needs as much detail as you've got in there.
>
> ----
>
> The Intro says:
>
> In general, I don't like using "we" in consensus documents because it 
> makes it ambiguous whether the "we" is the "the author(s), "the detnet 
> WG"", "the IETF", or "this document". Additionally, using phrases like 
> "we believe" or "we think"
> 2.2 I think you can simply just delete "we believe that". This 
> document is making a statement; no reason to hedge.
>
> 5.3.2.1 "We would like to see DetNet define such a protocol". Detnet 
> is the author of this document, so "we" here seems really weird.
>
> Throughout 3.1.1, 6.1.2, 7.3, 7.4: I presume "###us" is meant to be 
> "###µs". I believe I-Ds are now allowed to have such characters.
>
> ----
>
> In 3.3.2.3, there is no discussion about how this relates to NTP. I'm 
> not sure if that is necessary, but it seems odd for an IETF document.
>
> ----
>
> I like that you have security considerations sprinkled throughout the 
> document instead of trying to combine them into one big section. 
> However, some of the sections are missing security considerations. For 
> example, I think even I could come up with some security 
> considerations for the mining industry case. SECDIR might have more to 
> say, but I think it's worth adding these.
>
> ----
>

---

From: "Grossman, Ethan A." <[email-masked]>
Date: Mon, 8 Oct 2018 09:24:24 +0000

Hi Pete,
Executive summary: I have determined that "µ" is not accepted in I-Ds so I did not implement your requested change to that effect. Details below. If you find evidence to the contrary please let me know.
Thanks,
Ethan.

Details: 

Regarding "I presume "###us" is meant to be "###µs". I believe I-Ds are now allowed to have such characters."

Stackoverflow says " 7-bit ASCII only includes 128 characters (00-7F or 0-127 in decimal). 7-bit ASCII is also referred to as US-ASCII. UTF-8 encoding uses the same encoding as 7-bit ASCII for its first 128 characters."

The first line of the boilerplate that I inherited for the DetNet Use Cases draft says

<?xml version="1.0" encoding="US-ASCII"?>

Presumably for this reason my XML editor (oXygen) rejects use of µ as not ASCII. I tried to do some searches to figure out if I-Ds are indeed allowed to use UTF-8, but so far I don't see anything that indicates this. 

For example, the xml2rfc page says "xml2rfc will allow you to take your XML source using the format defined in RFC 7749..." in which RFC 7749 says (essentially) " the current RFC format does not allow non-ASCII Unicode characters" (exceptions follow, however they do not include characters such as µ). 

Another example is from https://www.ietf.org/ietf-ftp/1id-guidelines.txt: 
   "I-Ds must be in ASCII.  No 8-bit characters are allowed."

But just for laughs I tried switching the above line to
<?xml version="1.0" encoding="UTF-8"?>

Once I did this the XML editor no longer complains, and (to me seemingly strangely) https://xml2rfc.tools.ietf.org/ did not complain either, nor did the idnits tool. 

However when I look at the generated .txt file output of xml2rfc I see that the "10 µs" I put in there has been rendered as "10 [micro]s". So that explains it; at this point I claim that µ is not allowed so I am leaving that text as is. If you have a better idea please let me know.

Best,
Ethan.

-----Original Message-----
From: Pete Resnick <[email-masked]> 
Sent: Sunday, October 07, 2018 9:55 AM
To: Grossman, Ethan A. <[email-masked]>
Cc: [email-masked]; [email-masked]; [email-masked]; [email-masked]
Subject: Re: Genart last call review of draft-ietf-detnet-use-cases-18

Cool, thanks.

> if you feel that would be worthwhile.

The RFC Editor is not going to be onboard with a reference to what is officially a non-existent document. That said, I am not insistent that you put it back in; I don't know if it's worth mentioning. But I don't think this sort-of-in-sort-of-out state is a good idea.

Ack.

Ack.

> application seems appropriate, but that's just my take.

Ah, I hadn't realized there was a separate security document. A reference would be good. A simple suggestion then: Make a "Security Considerations" section in this document that simply says something
like: "Specific discussions of security considerations for particular use cases are noted throughout this document. A more complete discussion of security considerations can be found in [draft-ietf-detnet-security]."

> leaving it to the RFC Editor, if they are going to take that on. I'm 

Totally understood. Leaving the grammar corrections to the RFC Editor is fine, and they'll be able to make it all consistent across the sections. 
And they're very good about avoiding breaking meanings when they do their edits.

pr

---

From: Adam Roach <[email-masked]>
Date: Mon, 8 Oct 2018 12:56:34 -0500

[speaking with my RSOC hat on]

> believe I-Ds are now allowed to have such characters.

To be clear, I-Ds are currently prevented from being submitted with 
non-ASCII characters -- at least, when submitted using the normal 
mechanisms. This will be changed in the fairly near future to allow such 
characters, in anticipation of the upcoming transition to the new RFC 
format.

However, there will be no additional RFCs published with non-ASCII 
characters until the new format tools are put into production. This was 
announced in September of last year, after an experiment was run to test 
the RFC Production Center's tool suite as it pertains to handling 
non-ASCII characters:

https://mailarchive.ietf.org/arch/msg/ietf/jic8bRvwu8cJB0EgFtoHVQq14TM

For more information, see the RFC Format Change FAQ at 
https://www.rfc-editor.org/rse/format-faq/

/a