From 8e04b8e5d73b1b40dfb1967e1d797f5d89695a25 Mon Sep 17 00:00:00 2001 From: Lars Eggert Date: Wed, 1 Jun 2022 12:36:28 +0300 Subject: [PATCH 01/22] fix: Update document shepherd writeup template based on community review --- ietf/templates/doc/shepherd_writeup.txt | 56 ++++++++++++++----------- 1 file changed, 31 insertions(+), 25 deletions(-) diff --git a/ietf/templates/doc/shepherd_writeup.txt b/ietf/templates/doc/shepherd_writeup.txt index 5d40fad32ee..750fb4dd7c1 100644 --- a/ietf/templates/doc/shepherd_writeup.txt +++ b/ietf/templates/doc/shepherd_writeup.txt @@ -1,6 +1,6 @@ {# Keep in sync with https://github.com/ietf-chairs/chairs.ietf.org/blob/main/documents/qa-style-writeup-template.md #}{% if doc.stream %}{% if doc.stream.slug == 'ietf' %}# Document Shepherd Writeup -*This version is dated 8 April 2022.* +*This version is dated 1 June 2022.* Thank you for your service as a document shepherd. Among the responsibilities is answering the questions in this writeup to give helpful context to Last Call and @@ -39,8 +39,9 @@ to answer all of them. ### Additional Reviews -5. Does this document need review from other IETF working groups or external - organizations? Have those reviews occurred? +5. Does this document closely relate to work in other IETF working groups or + external organizations and would it hence benefit from their review? Have + those reviews occurred? 6. Describe how the document meets any required formal expert review criteria, such as the MIB Doctor, YANG Doctor, media type, and URI type reviews. @@ -63,30 +64,30 @@ to answer all of them. to be handed off to the responsible Area Director? 10. Several IETF Areas have assembled [lists of common issues that their - reviewers encounter][6]. Do any such issues remain that would merit specific - attention from subsequent reviews? + reviewers encounter][6]. Are any such issues still present in the document? -11. What type of RFC publication is being requested on the IETF stream (Best - Current Practice, Proposed Standard, Internet Standard, Informational, - Experimental, or Historic)? Why is this the proper type of RFC? Do all - Datatracker state attributes correctly reflect this intent? +11. What type of RFC publication is being requested on the IETF stream ([Best + Current Practice][13], [Proposed Standard, Internet Standard][14], + [Informational, Experimental or Historic][15])? Why is this the proper type + of RFC? Do all Datatracker state attributes correctly reflect this intent? -12. Has the interested community confirmed that any and all appropriate IPR - disclosures required by [BCP 78][7] and [BCP 79][8] have been filed? If not, - explain why. If yes, summarize any discussion and conclusion regarding the - intellectual property rights (IPR) disclosures, including links to relevant - emails. +12. Have the authors, editors and contributors confirmed that any and all + appropriate IPR disclosures required by [BCP 78][7] and [BCP 79][8] have + been filed? If not, explain why. If yes, summarize any discussion and + conclusion regarding the intellectual property rights (IPR) disclosures, + including links to relevant emails. -13. Has each Author or Contributor confirmed their willingness to be listed as - such? If the number of Authors/Editors on the front page is greater than 5, - please provide a justification. +13. Has each author or editor shown their willingness to be listed as such? If + the total number of authors and editors on the front page is greater than + five, please provide a justification. -14. Identify any remaining I-D nits in this document. (See [the idnits tool][9] - and the checkbox items found in Guidelines to Authors of Internet-Drafts). - Simply running the idnits tool is not enough; please review the entire - guidelines document. +14. Document any remaining I-D nits in this document. Simply running the [idnits + tool][9] is not enough; please review the ["Content Guide" pages on + authors.ietf.org][16]. (Also note that the current idnits tool generates + some incorrect warnings; a rewrite is underway.) -15. Should any informative references be normative or vice-versa? +15. Should any informative references be normative or vice-versa? See the [IESG + Statement on Normative and Informative References][17]. 16. List any normative references that are not freely available to anyone. Did the community have sufficient access to review any such normative @@ -95,9 +96,9 @@ to answer all of them. 17. Are there any normative downward references (see [RFC 3967][10], [BCP 97][11])? If so, list them. -18. Are there normative references to documents that are not ready for - advancement or are otherwise in an unclear state? If they exist, what is the - plan for their completion? +18. Are there normative references to documents that are not ready to be + submitted to the IESG for publication or are otherwise in an unclear state? + If they exist, what is the plan for their completion? 19. Will publication of this document change the status of any existing RFCs? If so, does the Datatracker metadata correctly reflect this and are those RFCs @@ -129,5 +130,10 @@ to answer all of them. [10]: https://www.rfc-editor.org/rfc/rfc3967.html [11]: https://www.rfc-editor.org/info/bcp97 [12]: https://www.rfc-editor.org/rfc/rfc8126.html +[13]: https://www.rfc-editor.org/rfc/rfc2026.html#section-5 +[14]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.1 +[15]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.2 +[16]: https://authors.ietf.org/ +[17]: https://www.ietf.org/about/groups/iesg/statements/normative-informative-references/ {% else %}There is no default shepherd writeup template for the {{doc.stream}} stream. {% endif %}{% else %}There is no stream set for this document (thus, no default shepherd writeup template).{% endif %} From 9f84ad615cf36b0fdf1d448d63fc0e1e37a8e9c5 Mon Sep 17 00:00:00 2001 From: Lars Eggert Date: Wed, 1 Jun 2022 14:54:21 +0300 Subject: [PATCH 02/22] Point to the new "content guidelines" page @JayDaley added --- ietf/templates/doc/shepherd_writeup.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ietf/templates/doc/shepherd_writeup.txt b/ietf/templates/doc/shepherd_writeup.txt index 750fb4dd7c1..80850235aa7 100644 --- a/ietf/templates/doc/shepherd_writeup.txt +++ b/ietf/templates/doc/shepherd_writeup.txt @@ -82,7 +82,7 @@ to answer all of them. five, please provide a justification. 14. Document any remaining I-D nits in this document. Simply running the [idnits - tool][9] is not enough; please review the ["Content Guide" pages on + tool][9] is not enough; please review the ["Content Guidelines" on authors.ietf.org][16]. (Also note that the current idnits tool generates some incorrect warnings; a rewrite is underway.) @@ -133,7 +133,7 @@ to answer all of them. [13]: https://www.rfc-editor.org/rfc/rfc2026.html#section-5 [14]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.1 [15]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.2 -[16]: https://authors.ietf.org/ +[16]: https://authors.ietf.org/en/content-guidelines-overview [17]: https://www.ietf.org/about/groups/iesg/statements/normative-informative-references/ {% else %}There is no default shepherd writeup template for the {{doc.stream}} stream. {% endif %}{% else %}There is no stream set for this document (thus, no default shepherd writeup template).{% endif %} From dff8c90738383cecae1d33d98677de3044d80ea1 Mon Sep 17 00:00:00 2001 From: Lars Eggert Date: Wed, 1 Jun 2022 14:56:25 +0300 Subject: [PATCH 03/22] Suggestion from Jane Coffin --- ietf/templates/doc/shepherd_writeup.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ietf/templates/doc/shepherd_writeup.txt b/ietf/templates/doc/shepherd_writeup.txt index 80850235aa7..3b9a501979a 100644 --- a/ietf/templates/doc/shepherd_writeup.txt +++ b/ietf/templates/doc/shepherd_writeup.txt @@ -6,8 +6,8 @@ Thank you for your service as a document shepherd. Among the responsibilities is answering the questions in this writeup to give helpful context to Last Call and Internet Engineering Steering Group ([IESG][1]) reviewers, and your diligence in completing it, is appreciated. The full role of the shepherd is further -described in [RFC 4858][2], and informally. You will need the cooperation of -authors to complete these checks. +described in [RFC 4858][2]. You will need the cooperation of authors to complete +these checks. Note that some numbered items contain multiple related questions; please be sure to answer all of them. From c2d8e88202ec81937f41e47966ed6c5787954130 Mon Sep 17 00:00:00 2001 From: Lars Eggert Date: Wed, 1 Jun 2022 14:57:30 +0300 Subject: [PATCH 04/22] Also extend this to contributors --- ietf/templates/doc/shepherd_writeup.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ietf/templates/doc/shepherd_writeup.txt b/ietf/templates/doc/shepherd_writeup.txt index 3b9a501979a..c0b1b33654a 100644 --- a/ietf/templates/doc/shepherd_writeup.txt +++ b/ietf/templates/doc/shepherd_writeup.txt @@ -77,9 +77,9 @@ to answer all of them. conclusion regarding the intellectual property rights (IPR) disclosures, including links to relevant emails. -13. Has each author or editor shown their willingness to be listed as such? If - the total number of authors and editors on the front page is greater than - five, please provide a justification. +13. Has each author, editor and contributor shown their willingness to be listed + as such? If the total number of authors and editors on the front page is + greater than five, please provide a justification. 14. Document any remaining I-D nits in this document. Simply running the [idnits tool][9] is not enough; please review the ["Content Guidelines" on From 9b41da7d0bb0394e89260f11fab02b7f406f1fcc Mon Sep 17 00:00:00 2001 From: Lars Eggert Date: Wed, 1 Jun 2022 15:01:50 +0300 Subject: [PATCH 05/22] Fix grammar nits --- ietf/templates/doc/shepherd_writeup.txt | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/ietf/templates/doc/shepherd_writeup.txt b/ietf/templates/doc/shepherd_writeup.txt index c0b1b33654a..672554bb1c0 100644 --- a/ietf/templates/doc/shepherd_writeup.txt +++ b/ietf/templates/doc/shepherd_writeup.txt @@ -1,13 +1,13 @@ -{# Keep in sync with https://github.com/ietf-chairs/chairs.ietf.org/blob/main/documents/qa-style-writeup-template.md #}{% if doc.stream %}{% if doc.stream.slug == 'ietf' %}# Document Shepherd Writeup +{# Keep in sync with https://github.com/ietf-chairs/chairs.ietf.org/blob/main/documents/qa-style-writeup-template.md #}{% if doc.stream %}{% if doc.stream.slug == 'ietf' %}# Document Shepherd Write-Up *This version is dated 1 June 2022.* Thank you for your service as a document shepherd. Among the responsibilities is -answering the questions in this writeup to give helpful context to Last Call and -Internet Engineering Steering Group ([IESG][1]) reviewers, and your diligence in -completing it, is appreciated. The full role of the shepherd is further -described in [RFC 4858][2]. You will need the cooperation of authors to complete -these checks. +answering the questions in this write-up to give helpful context to Last Call +and Internet Engineering Steering Group ([IESG][1]) reviewers, and your +diligence in completing it is appreciated. The full role of the shepherd is +further described in [RFC 4858][2]. You will need the cooperation of the authors +and editors to complete these checks. Note that some numbered items contain multiple related questions; please be sure to answer all of them. @@ -40,7 +40,7 @@ to answer all of them. ### Additional Reviews 5. Does this document closely relate to work in other IETF working groups or - external organizations and would it hence benefit from their review? Have + external organizations, and would it hence benefit from their review? Have those reviews occurred? 6. Describe how the document meets any required formal expert review criteria, @@ -135,5 +135,5 @@ to answer all of them. [15]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.2 [16]: https://authors.ietf.org/en/content-guidelines-overview [17]: https://www.ietf.org/about/groups/iesg/statements/normative-informative-references/ -{% else %}There is no default shepherd writeup template for the {{doc.stream}} stream. -{% endif %}{% else %}There is no stream set for this document (thus, no default shepherd writeup template).{% endif %} +{% else %}There is no default shepherd write-up template for the {{doc.stream}} stream. +{% endif %}{% else %}There is no stream set for this document (thus, no default shepherd write-up template).{% endif %} From bc818119fb4bfe204c403c42fd8465d5f0111905 Mon Sep 17 00:00:00 2001 From: Lars Eggert Date: Thu, 2 Jun 2022 18:00:23 +0300 Subject: [PATCH 06/22] Revise question 5 based on suggestions from @cabo --- ietf/templates/doc/shepherd_writeup.txt | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/ietf/templates/doc/shepherd_writeup.txt b/ietf/templates/doc/shepherd_writeup.txt index 672554bb1c0..641cd568128 100644 --- a/ietf/templates/doc/shepherd_writeup.txt +++ b/ietf/templates/doc/shepherd_writeup.txt @@ -39,9 +39,10 @@ to answer all of them. ### Additional Reviews -5. Does this document closely relate to work in other IETF working groups or - external organizations, and would it hence benefit from their review? Have - those reviews occurred? +5. Do the contents of this document closely interact with technologies in other + IETF working groups or external organizations, and would it hence benefit + from their review? Have those reviews occurred? If yes, describe which + reviews took place. 6. Describe how the document meets any required formal expert review criteria, such as the MIB Doctor, YANG Doctor, media type, and URI type reviews. From d3fa8d91ae8536705f5d0d90867c425e9f5588d2 Mon Sep 17 00:00:00 2001 From: Lars Eggert Date: Wed, 1 Jun 2022 12:36:28 +0300 Subject: [PATCH 07/22] fix: Update document shepherd writeup template based on community review --- ietf/templates/doc/shepherd_writeup.txt | 56 ++++++++++++++----------- 1 file changed, 31 insertions(+), 25 deletions(-) diff --git a/ietf/templates/doc/shepherd_writeup.txt b/ietf/templates/doc/shepherd_writeup.txt index 5d40fad32ee..750fb4dd7c1 100644 --- a/ietf/templates/doc/shepherd_writeup.txt +++ b/ietf/templates/doc/shepherd_writeup.txt @@ -1,6 +1,6 @@ {# Keep in sync with https://github.com/ietf-chairs/chairs.ietf.org/blob/main/documents/qa-style-writeup-template.md #}{% if doc.stream %}{% if doc.stream.slug == 'ietf' %}# Document Shepherd Writeup -*This version is dated 8 April 2022.* +*This version is dated 1 June 2022.* Thank you for your service as a document shepherd. Among the responsibilities is answering the questions in this writeup to give helpful context to Last Call and @@ -39,8 +39,9 @@ to answer all of them. ### Additional Reviews -5. Does this document need review from other IETF working groups or external - organizations? Have those reviews occurred? +5. Does this document closely relate to work in other IETF working groups or + external organizations and would it hence benefit from their review? Have + those reviews occurred? 6. Describe how the document meets any required formal expert review criteria, such as the MIB Doctor, YANG Doctor, media type, and URI type reviews. @@ -63,30 +64,30 @@ to answer all of them. to be handed off to the responsible Area Director? 10. Several IETF Areas have assembled [lists of common issues that their - reviewers encounter][6]. Do any such issues remain that would merit specific - attention from subsequent reviews? + reviewers encounter][6]. Are any such issues still present in the document? -11. What type of RFC publication is being requested on the IETF stream (Best - Current Practice, Proposed Standard, Internet Standard, Informational, - Experimental, or Historic)? Why is this the proper type of RFC? Do all - Datatracker state attributes correctly reflect this intent? +11. What type of RFC publication is being requested on the IETF stream ([Best + Current Practice][13], [Proposed Standard, Internet Standard][14], + [Informational, Experimental or Historic][15])? Why is this the proper type + of RFC? Do all Datatracker state attributes correctly reflect this intent? -12. Has the interested community confirmed that any and all appropriate IPR - disclosures required by [BCP 78][7] and [BCP 79][8] have been filed? If not, - explain why. If yes, summarize any discussion and conclusion regarding the - intellectual property rights (IPR) disclosures, including links to relevant - emails. +12. Have the authors, editors and contributors confirmed that any and all + appropriate IPR disclosures required by [BCP 78][7] and [BCP 79][8] have + been filed? If not, explain why. If yes, summarize any discussion and + conclusion regarding the intellectual property rights (IPR) disclosures, + including links to relevant emails. -13. Has each Author or Contributor confirmed their willingness to be listed as - such? If the number of Authors/Editors on the front page is greater than 5, - please provide a justification. +13. Has each author or editor shown their willingness to be listed as such? If + the total number of authors and editors on the front page is greater than + five, please provide a justification. -14. Identify any remaining I-D nits in this document. (See [the idnits tool][9] - and the checkbox items found in Guidelines to Authors of Internet-Drafts). - Simply running the idnits tool is not enough; please review the entire - guidelines document. +14. Document any remaining I-D nits in this document. Simply running the [idnits + tool][9] is not enough; please review the ["Content Guide" pages on + authors.ietf.org][16]. (Also note that the current idnits tool generates + some incorrect warnings; a rewrite is underway.) -15. Should any informative references be normative or vice-versa? +15. Should any informative references be normative or vice-versa? See the [IESG + Statement on Normative and Informative References][17]. 16. List any normative references that are not freely available to anyone. Did the community have sufficient access to review any such normative @@ -95,9 +96,9 @@ to answer all of them. 17. Are there any normative downward references (see [RFC 3967][10], [BCP 97][11])? If so, list them. -18. Are there normative references to documents that are not ready for - advancement or are otherwise in an unclear state? If they exist, what is the - plan for their completion? +18. Are there normative references to documents that are not ready to be + submitted to the IESG for publication or are otherwise in an unclear state? + If they exist, what is the plan for their completion? 19. Will publication of this document change the status of any existing RFCs? If so, does the Datatracker metadata correctly reflect this and are those RFCs @@ -129,5 +130,10 @@ to answer all of them. [10]: https://www.rfc-editor.org/rfc/rfc3967.html [11]: https://www.rfc-editor.org/info/bcp97 [12]: https://www.rfc-editor.org/rfc/rfc8126.html +[13]: https://www.rfc-editor.org/rfc/rfc2026.html#section-5 +[14]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.1 +[15]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.2 +[16]: https://authors.ietf.org/ +[17]: https://www.ietf.org/about/groups/iesg/statements/normative-informative-references/ {% else %}There is no default shepherd writeup template for the {{doc.stream}} stream. {% endif %}{% else %}There is no stream set for this document (thus, no default shepherd writeup template).{% endif %} From f454ffe647e9886ba046688615418db89bef781f Mon Sep 17 00:00:00 2001 From: Lars Eggert Date: Wed, 1 Jun 2022 14:54:21 +0300 Subject: [PATCH 08/22] Point to the new "content guidelines" page @JayDaley added --- ietf/templates/doc/shepherd_writeup.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ietf/templates/doc/shepherd_writeup.txt b/ietf/templates/doc/shepherd_writeup.txt index 750fb4dd7c1..80850235aa7 100644 --- a/ietf/templates/doc/shepherd_writeup.txt +++ b/ietf/templates/doc/shepherd_writeup.txt @@ -82,7 +82,7 @@ to answer all of them. five, please provide a justification. 14. Document any remaining I-D nits in this document. Simply running the [idnits - tool][9] is not enough; please review the ["Content Guide" pages on + tool][9] is not enough; please review the ["Content Guidelines" on authors.ietf.org][16]. (Also note that the current idnits tool generates some incorrect warnings; a rewrite is underway.) @@ -133,7 +133,7 @@ to answer all of them. [13]: https://www.rfc-editor.org/rfc/rfc2026.html#section-5 [14]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.1 [15]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.2 -[16]: https://authors.ietf.org/ +[16]: https://authors.ietf.org/en/content-guidelines-overview [17]: https://www.ietf.org/about/groups/iesg/statements/normative-informative-references/ {% else %}There is no default shepherd writeup template for the {{doc.stream}} stream. {% endif %}{% else %}There is no stream set for this document (thus, no default shepherd writeup template).{% endif %} From 7ee9afc0162f03a04682adbc51efb59b12e14228 Mon Sep 17 00:00:00 2001 From: Lars Eggert Date: Wed, 1 Jun 2022 14:56:25 +0300 Subject: [PATCH 09/22] Suggestion from Jane Coffin --- ietf/templates/doc/shepherd_writeup.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ietf/templates/doc/shepherd_writeup.txt b/ietf/templates/doc/shepherd_writeup.txt index 80850235aa7..3b9a501979a 100644 --- a/ietf/templates/doc/shepherd_writeup.txt +++ b/ietf/templates/doc/shepherd_writeup.txt @@ -6,8 +6,8 @@ Thank you for your service as a document shepherd. Among the responsibilities is answering the questions in this writeup to give helpful context to Last Call and Internet Engineering Steering Group ([IESG][1]) reviewers, and your diligence in completing it, is appreciated. The full role of the shepherd is further -described in [RFC 4858][2], and informally. You will need the cooperation of -authors to complete these checks. +described in [RFC 4858][2]. You will need the cooperation of authors to complete +these checks. Note that some numbered items contain multiple related questions; please be sure to answer all of them. From df0b79cf3637098f20532128fc86a24a9db9a1bf Mon Sep 17 00:00:00 2001 From: Lars Eggert Date: Wed, 1 Jun 2022 14:57:30 +0300 Subject: [PATCH 10/22] Also extend this to contributors --- ietf/templates/doc/shepherd_writeup.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ietf/templates/doc/shepherd_writeup.txt b/ietf/templates/doc/shepherd_writeup.txt index 3b9a501979a..c0b1b33654a 100644 --- a/ietf/templates/doc/shepherd_writeup.txt +++ b/ietf/templates/doc/shepherd_writeup.txt @@ -77,9 +77,9 @@ to answer all of them. conclusion regarding the intellectual property rights (IPR) disclosures, including links to relevant emails. -13. Has each author or editor shown their willingness to be listed as such? If - the total number of authors and editors on the front page is greater than - five, please provide a justification. +13. Has each author, editor and contributor shown their willingness to be listed + as such? If the total number of authors and editors on the front page is + greater than five, please provide a justification. 14. Document any remaining I-D nits in this document. Simply running the [idnits tool][9] is not enough; please review the ["Content Guidelines" on From 3c74045a64d50abce0db0fc1b761193418987d94 Mon Sep 17 00:00:00 2001 From: Lars Eggert Date: Wed, 1 Jun 2022 15:01:50 +0300 Subject: [PATCH 11/22] Fix grammar nits --- ietf/templates/doc/shepherd_writeup.txt | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/ietf/templates/doc/shepherd_writeup.txt b/ietf/templates/doc/shepherd_writeup.txt index c0b1b33654a..672554bb1c0 100644 --- a/ietf/templates/doc/shepherd_writeup.txt +++ b/ietf/templates/doc/shepherd_writeup.txt @@ -1,13 +1,13 @@ -{# Keep in sync with https://github.com/ietf-chairs/chairs.ietf.org/blob/main/documents/qa-style-writeup-template.md #}{% if doc.stream %}{% if doc.stream.slug == 'ietf' %}# Document Shepherd Writeup +{# Keep in sync with https://github.com/ietf-chairs/chairs.ietf.org/blob/main/documents/qa-style-writeup-template.md #}{% if doc.stream %}{% if doc.stream.slug == 'ietf' %}# Document Shepherd Write-Up *This version is dated 1 June 2022.* Thank you for your service as a document shepherd. Among the responsibilities is -answering the questions in this writeup to give helpful context to Last Call and -Internet Engineering Steering Group ([IESG][1]) reviewers, and your diligence in -completing it, is appreciated. The full role of the shepherd is further -described in [RFC 4858][2]. You will need the cooperation of authors to complete -these checks. +answering the questions in this write-up to give helpful context to Last Call +and Internet Engineering Steering Group ([IESG][1]) reviewers, and your +diligence in completing it is appreciated. The full role of the shepherd is +further described in [RFC 4858][2]. You will need the cooperation of the authors +and editors to complete these checks. Note that some numbered items contain multiple related questions; please be sure to answer all of them. @@ -40,7 +40,7 @@ to answer all of them. ### Additional Reviews 5. Does this document closely relate to work in other IETF working groups or - external organizations and would it hence benefit from their review? Have + external organizations, and would it hence benefit from their review? Have those reviews occurred? 6. Describe how the document meets any required formal expert review criteria, @@ -135,5 +135,5 @@ to answer all of them. [15]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.2 [16]: https://authors.ietf.org/en/content-guidelines-overview [17]: https://www.ietf.org/about/groups/iesg/statements/normative-informative-references/ -{% else %}There is no default shepherd writeup template for the {{doc.stream}} stream. -{% endif %}{% else %}There is no stream set for this document (thus, no default shepherd writeup template).{% endif %} +{% else %}There is no default shepherd write-up template for the {{doc.stream}} stream. +{% endif %}{% else %}There is no stream set for this document (thus, no default shepherd write-up template).{% endif %} From 571077d8b20804fc2d4987af56bf6029ca7beb3b Mon Sep 17 00:00:00 2001 From: Lars Eggert Date: Thu, 2 Jun 2022 18:00:23 +0300 Subject: [PATCH 12/22] Revise question 5 based on suggestions from @cabo --- ietf/templates/doc/shepherd_writeup.txt | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/ietf/templates/doc/shepherd_writeup.txt b/ietf/templates/doc/shepherd_writeup.txt index 672554bb1c0..641cd568128 100644 --- a/ietf/templates/doc/shepherd_writeup.txt +++ b/ietf/templates/doc/shepherd_writeup.txt @@ -39,9 +39,10 @@ to answer all of them. ### Additional Reviews -5. Does this document closely relate to work in other IETF working groups or - external organizations, and would it hence benefit from their review? Have - those reviews occurred? +5. Do the contents of this document closely interact with technologies in other + IETF working groups or external organizations, and would it hence benefit + from their review? Have those reviews occurred? If yes, describe which + reviews took place. 6. Describe how the document meets any required formal expert review criteria, such as the MIB Doctor, YANG Doctor, media type, and URI type reviews. From f073981acf43508b22c30161082494a8be451641 Mon Sep 17 00:00:00 2001 From: Lars Eggert Date: Fri, 3 Jun 2022 09:38:11 +0300 Subject: [PATCH 13/22] Apply suggestions from code review By @richsalz --- ietf/templates/doc/shepherd_writeup.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ietf/templates/doc/shepherd_writeup.txt b/ietf/templates/doc/shepherd_writeup.txt index 641cd568128..f3303719fc7 100644 --- a/ietf/templates/doc/shepherd_writeup.txt +++ b/ietf/templates/doc/shepherd_writeup.txt @@ -40,7 +40,7 @@ to answer all of them. ### Additional Reviews 5. Do the contents of this document closely interact with technologies in other - IETF working groups or external organizations, and would it hence benefit + IETF working groups or external organizations, and would it therefore benefit from their review? Have those reviews occurred? If yes, describe which reviews took place. @@ -78,7 +78,7 @@ to answer all of them. conclusion regarding the intellectual property rights (IPR) disclosures, including links to relevant emails. -13. Has each author, editor and contributor shown their willingness to be listed +13. Has each author, editor, and contributor shown their willingness to be listed as such? If the total number of authors and editors on the front page is greater than five, please provide a justification. @@ -99,7 +99,7 @@ to answer all of them. 18. Are there normative references to documents that are not ready to be submitted to the IESG for publication or are otherwise in an unclear state? - If they exist, what is the plan for their completion? + If so, what is the plan for their completion? 19. Will publication of this document change the status of any existing RFCs? If so, does the Datatracker metadata correctly reflect this and are those RFCs From b29f69a999791e3a0d07bae056813625c3ab2a11 Mon Sep 17 00:00:00 2001 From: Lars Eggert Date: Thu, 9 Jun 2022 09:52:50 +0300 Subject: [PATCH 14/22] Update ietf/templates/doc/shepherd_writeup.txt --- ietf/templates/doc/shepherd_writeup.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/ietf/templates/doc/shepherd_writeup.txt b/ietf/templates/doc/shepherd_writeup.txt index f3303719fc7..370e86371b0 100644 --- a/ietf/templates/doc/shepherd_writeup.txt +++ b/ietf/templates/doc/shepherd_writeup.txt @@ -65,7 +65,8 @@ to answer all of them. to be handed off to the responsible Area Director? 10. Several IETF Areas have assembled [lists of common issues that their - reviewers encounter][6]. Are any such issues still present in the document? + reviewers encounter][6]. For which areas have such issues been identified and addressed? + For which does this still need to happen in subsequent reviews? 11. What type of RFC publication is being requested on the IETF stream ([Best Current Practice][13], [Proposed Standard, Internet Standard][14], From 3192d7bc23082bead40e56eb9e4cd9a6e2717b44 Mon Sep 17 00:00:00 2001 From: Lars Eggert Date: Thu, 9 Jun 2022 09:54:40 +0300 Subject: [PATCH 15/22] Update ietf/templates/doc/shepherd_writeup.txt --- ietf/templates/doc/shepherd_writeup.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/ietf/templates/doc/shepherd_writeup.txt b/ietf/templates/doc/shepherd_writeup.txt index 370e86371b0..4d7ce8871e7 100644 --- a/ietf/templates/doc/shepherd_writeup.txt +++ b/ietf/templates/doc/shepherd_writeup.txt @@ -73,9 +73,10 @@ to answer all of them. [Informational, Experimental or Historic][15])? Why is this the proper type of RFC? Do all Datatracker state attributes correctly reflect this intent? -12. Have the authors, editors and contributors confirmed that any and all +12. Have the authors and editors confirmed that any and all appropriate IPR disclosures required by [BCP 78][7] and [BCP 79][8] have - been filed? If not, explain why. If yes, summarize any discussion and + been filed; and have all contributors been reminded of this obligation? + If not, explain why. If yes, summarize any discussion and conclusion regarding the intellectual property rights (IPR) disclosures, including links to relevant emails. From 408f1db91fb6322d6f73a6dbada845e3d07ae287 Mon Sep 17 00:00:00 2001 From: Lars Eggert Date: Thu, 9 Jun 2022 09:54:46 +0300 Subject: [PATCH 16/22] Update ietf/templates/doc/shepherd_writeup.txt --- ietf/templates/doc/shepherd_writeup.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ietf/templates/doc/shepherd_writeup.txt b/ietf/templates/doc/shepherd_writeup.txt index 4d7ce8871e7..8aa51b0d2ce 100644 --- a/ietf/templates/doc/shepherd_writeup.txt +++ b/ietf/templates/doc/shepherd_writeup.txt @@ -78,7 +78,7 @@ to answer all of them. been filed; and have all contributors been reminded of this obligation? If not, explain why. If yes, summarize any discussion and conclusion regarding the intellectual property rights (IPR) disclosures, - including links to relevant emails. + include links to any relevant public email discussion. 13. Has each author, editor, and contributor shown their willingness to be listed as such? If the total number of authors and editors on the front page is From 2cc80b571f2ec1b762cc051a1d95b127232b4893 Mon Sep 17 00:00:00 2001 From: Lars Eggert Date: Thu, 9 Jun 2022 09:55:29 +0300 Subject: [PATCH 17/22] Update ietf/templates/doc/shepherd_writeup.txt --- ietf/templates/doc/shepherd_writeup.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ietf/templates/doc/shepherd_writeup.txt b/ietf/templates/doc/shepherd_writeup.txt index 8aa51b0d2ce..87d725cab83 100644 --- a/ietf/templates/doc/shepherd_writeup.txt +++ b/ietf/templates/doc/shepherd_writeup.txt @@ -78,7 +78,7 @@ to answer all of them. been filed; and have all contributors been reminded of this obligation? If not, explain why. If yes, summarize any discussion and conclusion regarding the intellectual property rights (IPR) disclosures, - include links to any relevant public email discussion. + and include links to any relevant public email discussion. 13. Has each author, editor, and contributor shown their willingness to be listed as such? If the total number of authors and editors on the front page is From 64dbdc20dadd51a8fd130c8b80b2eecea0579673 Mon Sep 17 00:00:00 2001 From: Lars Eggert Date: Thu, 9 Jun 2022 09:57:34 +0300 Subject: [PATCH 18/22] Apply suggestions from code review --- ietf/templates/doc/shepherd_writeup.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/ietf/templates/doc/shepherd_writeup.txt b/ietf/templates/doc/shepherd_writeup.txt index 87d725cab83..21fdd52a87c 100644 --- a/ietf/templates/doc/shepherd_writeup.txt +++ b/ietf/templates/doc/shepherd_writeup.txt @@ -97,7 +97,7 @@ to answer all of them. references? 17. Are there any normative downward references (see [RFC 3967][10], - [BCP 97][11])? If so, list them. + [BCP 97][11], and the [DOWNREF registry][18])? If so, list them. 18. Are there normative references to documents that are not ready to be submitted to the IESG for publication or are otherwise in an unclear state? @@ -138,5 +138,6 @@ to answer all of them. [15]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.2 [16]: https://authors.ietf.org/en/content-guidelines-overview [17]: https://www.ietf.org/about/groups/iesg/statements/normative-informative-references/ +[18]: https://datatracker.ietf.org/doc/downref/ {% else %}There is no default shepherd write-up template for the {{doc.stream}} stream. {% endif %}{% else %}There is no stream set for this document (thus, no default shepherd write-up template).{% endif %} From 5742e1d5dcd995ff884217d193ca26259e035164 Mon Sep 17 00:00:00 2001 From: Lars Eggert Date: Tue, 21 Jun 2022 14:31:02 +0300 Subject: [PATCH 19/22] Question 12 from Brad --- ietf/templates/doc/shepherd_writeup.txt | 50 ++++++++++++------------- 1 file changed, 24 insertions(+), 26 deletions(-) diff --git a/ietf/templates/doc/shepherd_writeup.txt b/ietf/templates/doc/shepherd_writeup.txt index 21fdd52a87c..3c573cdf2df 100644 --- a/ietf/templates/doc/shepherd_writeup.txt +++ b/ietf/templates/doc/shepherd_writeup.txt @@ -69,35 +69,34 @@ to answer all of them. For which does this still need to happen in subsequent reviews? 11. What type of RFC publication is being requested on the IETF stream ([Best - Current Practice][13], [Proposed Standard, Internet Standard][14], - [Informational, Experimental or Historic][15])? Why is this the proper type + Current Practice][12], [Proposed Standard, Internet Standard][13], + [Informational, Experimental or Historic][14])? Why is this the proper type of RFC? Do all Datatracker state attributes correctly reflect this intent? -12. Have the authors and editors confirmed that any and all - appropriate IPR disclosures required by [BCP 78][7] and [BCP 79][8] have - been filed; and have all contributors been reminded of this obligation? - If not, explain why. If yes, summarize any discussion and - conclusion regarding the intellectual property rights (IPR) disclosures, - and include links to any relevant public email discussion. +12. Have reasonable efforts been made to remind all authors of the intellectual + property rights (IPR) disclosure obligations described in [BCP 79][8]? + To the best of your knowledge, have all required disclosures been filed? + If not, explain why. If yes, summarize any relevant discussion, including + links to publicly-available messages when applicable. 13. Has each author, editor, and contributor shown their willingness to be listed as such? If the total number of authors and editors on the front page is greater than five, please provide a justification. 14. Document any remaining I-D nits in this document. Simply running the [idnits - tool][9] is not enough; please review the ["Content Guidelines" on - authors.ietf.org][16]. (Also note that the current idnits tool generates + tool][8] is not enough; please review the ["Content Guidelines" on + authors.ietf.org][15]. (Also note that the current idnits tool generates some incorrect warnings; a rewrite is underway.) 15. Should any informative references be normative or vice-versa? See the [IESG - Statement on Normative and Informative References][17]. + Statement on Normative and Informative References][16]. 16. List any normative references that are not freely available to anyone. Did the community have sufficient access to review any such normative references? -17. Are there any normative downward references (see [RFC 3967][10], - [BCP 97][11], and the [DOWNREF registry][18])? If so, list them. +17. Are there any normative downward references (see [RFC 3967][9], + [BCP 97][10], and the [DOWNREF registry][17])? If so, list them. 18. Are there normative references to documents that are not ready to be submitted to the IESG for publication or are otherwise in an unclear state? @@ -115,7 +114,7 @@ to answer all of them. associated with the appropriate reservations in IANA registries. Confirm that any referenced IANA registries have been clearly identified. Confirm that each newly created IANA registry specifies its initial contents, - allocations procedures, and a reasonable name (see [RFC 8126][12]). + allocations procedures, and a reasonable name (see [RFC 8126][11]). 21. List any new IANA registries that require Designated Expert Review for future allocations. Are the instructions to the Designated Expert clear? @@ -127,17 +126,16 @@ to answer all of them. [4]: https://trac.ietf.org/trac/ops/wiki/yang-review-tools [5]: https://www.rfc-editor.org/rfc/rfc8342.html [6]: https://trac.ietf.org/trac/iesg/wiki/ExpertTopics -[7]: https://www.rfc-editor.org/info/bcp78 -[8]: https://www.rfc-editor.org/info/bcp79 -[9]: https://www.ietf.org/tools/idnits/ -[10]: https://www.rfc-editor.org/rfc/rfc3967.html -[11]: https://www.rfc-editor.org/info/bcp97 -[12]: https://www.rfc-editor.org/rfc/rfc8126.html -[13]: https://www.rfc-editor.org/rfc/rfc2026.html#section-5 -[14]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.1 -[15]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.2 -[16]: https://authors.ietf.org/en/content-guidelines-overview -[17]: https://www.ietf.org/about/groups/iesg/statements/normative-informative-references/ -[18]: https://datatracker.ietf.org/doc/downref/ +[7]: https://www.rfc-editor.org/info/bcp79 +[8]: https://www.ietf.org/tools/idnits/ +[9]: https://www.rfc-editor.org/rfc/rfc3967.html +[10]: https://www.rfc-editor.org/info/bcp97 +[11]: https://www.rfc-editor.org/rfc/rfc8126.html +[12]: https://www.rfc-editor.org/rfc/rfc2026.html#section-5 +[13]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.1 +[14]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.2 +[15]: https://authors.ietf.org/en/content-guidelines-overview +[16]: https://www.ietf.org/about/groups/iesg/statements/normative-informative-references/ +[17]: https://datatracker.ietf.org/doc/downref/ {% else %}There is no default shepherd write-up template for the {{doc.stream}} stream. {% endif %}{% else %}There is no stream set for this document (thus, no default shepherd write-up template).{% endif %} From 2df6803b5243216ebdc05e108ec382e886063a0c Mon Sep 17 00:00:00 2001 From: Lars Eggert Date: Wed, 22 Jun 2022 09:08:09 +0300 Subject: [PATCH 20/22] Update ietf/templates/doc/shepherd_writeup.txt --- ietf/templates/doc/shepherd_writeup.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/ietf/templates/doc/shepherd_writeup.txt b/ietf/templates/doc/shepherd_writeup.txt index 3c573cdf2df..cf24ebe8654 100644 --- a/ietf/templates/doc/shepherd_writeup.txt +++ b/ietf/templates/doc/shepherd_writeup.txt @@ -95,8 +95,9 @@ to answer all of them. the community have sufficient access to review any such normative references? -17. Are there any normative downward references (see [RFC 3967][9], - [BCP 97][10], and the [DOWNREF registry][17])? If so, list them. +17. Are there any normative downward references (see [RFC 3967][9] and + [BCP 97][10]) that are not already listed in the [DOWNREF registry][17]? + If so, list them. 18. Are there normative references to documents that are not ready to be submitted to the IESG for publication or are otherwise in an unclear state? From 6d4fe197e6925d582d47ffd168625a7b7caddaad Mon Sep 17 00:00:00 2001 From: Lars Eggert Date: Mon, 4 Jul 2022 18:39:32 +0300 Subject: [PATCH 21/22] Rewrap --- ietf/templates/doc/shepherd_writeup.txt | 27 +++++++++++++------------ 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/ietf/templates/doc/shepherd_writeup.txt b/ietf/templates/doc/shepherd_writeup.txt index cf24ebe8654..88a1c523074 100644 --- a/ietf/templates/doc/shepherd_writeup.txt +++ b/ietf/templates/doc/shepherd_writeup.txt @@ -65,23 +65,24 @@ to answer all of them. to be handed off to the responsible Area Director? 10. Several IETF Areas have assembled [lists of common issues that their - reviewers encounter][6]. For which areas have such issues been identified and addressed? - For which does this still need to happen in subsequent reviews? + reviewers encounter][6]. For which areas have such issues been identified + and addressed? For which does this still need to happen in subsequent + reviews? 11. What type of RFC publication is being requested on the IETF stream ([Best Current Practice][12], [Proposed Standard, Internet Standard][13], [Informational, Experimental or Historic][14])? Why is this the proper type of RFC? Do all Datatracker state attributes correctly reflect this intent? -12. Have reasonable efforts been made to remind all authors of the intellectual - property rights (IPR) disclosure obligations described in [BCP 79][8]? - To the best of your knowledge, have all required disclosures been filed? - If not, explain why. If yes, summarize any relevant discussion, including - links to publicly-available messages when applicable. +12. Have reasonable efforts been made to remind all authors of the intellectual + property rights (IPR) disclosure obligations described in [BCP 79][8]? To + the best of your knowledge, have all required disclosures been filed? If + not, explain why. If yes, summarize any relevant discussion, including links + to publicly-available messages when applicable. -13. Has each author, editor, and contributor shown their willingness to be listed - as such? If the total number of authors and editors on the front page is - greater than five, please provide a justification. +13. Has each author, editor, and contributor shown their willingness to be + listed as such? If the total number of authors and editors on the front page + is greater than five, please provide a justification. 14. Document any remaining I-D nits in this document. Simply running the [idnits tool][8] is not enough; please review the ["Content Guidelines" on @@ -95,9 +96,9 @@ to answer all of them. the community have sufficient access to review any such normative references? -17. Are there any normative downward references (see [RFC 3967][9] and - [BCP 97][10]) that are not already listed in the [DOWNREF registry][17]? - If so, list them. +17. Are there any normative downward references (see [RFC 3967][9] and [BCP + 97][10]) that are not already listed in the [DOWNREF registry][17]? If so, + list them. 18. Are there normative references to documents that are not ready to be submitted to the IESG for publication or are otherwise in an unclear state? From 526049c397b48a9b0adabaa642b6ad5c091cc3ec Mon Sep 17 00:00:00 2001 From: Lars Eggert Date: Mon, 4 Jul 2022 18:44:03 +0300 Subject: [PATCH 22/22] Fix test --- ietf/doc/tests_draft.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ietf/doc/tests_draft.py b/ietf/doc/tests_draft.py index 4fa6b46700c..61fe2f6c7e3 100644 --- a/ietf/doc/tests_draft.py +++ b/ietf/doc/tests_draft.py @@ -1215,7 +1215,7 @@ def test_doc_change_shepherd_writeup(self): r = self.client.post(url,dict(txt=test_file,reset_text="1")) self.assertEqual(r.status_code, 200) q = PyQuery(r.content) - self.assertTrue(q('textarea')[0].text.strip().startswith("# Document Shepherd Writeup")) # TODO: This is a poor test of whether the reset did anything + self.assertTrue(q('textarea')[0].text.strip().startswith("# Document Shepherd Write-Up")) # TODO: This is a poor test of whether the reset did anything def test_edit_doc_extresources(self): url = urlreverse('ietf.doc.views_draft.edit_doc_extresources', kwargs=dict(name=self.docname))