Skip to content

Commit 21452b7

Browse files
larseggertlarseggert
authored
fix: Update document shepherd writeup template based on community review (ietf-tools#4042)
* fix: Update document shepherd writeup template based on community review * Point to the new "content guidelines" page @JayDaley added * Suggestion from Jane Coffin * Also extend this to contributors * Fix grammar nits * Revise question 5 based on suggestions from @cabo * fix: Update document shepherd writeup template based on community review * Point to the new "content guidelines" page @JayDaley added * Suggestion from Jane Coffin * Also extend this to contributors * Fix grammar nits * Revise question 5 based on suggestions from @cabo * Apply suggestions from code review By @richsalz * Update ietf/templates/doc/shepherd_writeup.txt * Update ietf/templates/doc/shepherd_writeup.txt * Update ietf/templates/doc/shepherd_writeup.txt * Update ietf/templates/doc/shepherd_writeup.txt * Apply suggestions from code review * Question 12 from Brad * Update ietf/templates/doc/shepherd_writeup.txt * Rewrap * Fix test
1 parent 2934ae2 commit 21452b7

2 files changed

Lines changed: 53 additions & 43 deletions

File tree

‎ietf/doc/tests_draft.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1215,7 +1215,7 @@ def test_doc_change_shepherd_writeup(self):
12151215
r = self.client.post(url,dict(txt=test_file,reset_text="1"))
12161216
self.assertEqual(r.status_code, 200)
12171217
q = PyQuery(r.content)
1218-
self.assertTrue(q('textarea')[0].text.strip().startswith("# Document Shepherd Writeup")) # TODO: This is a poor test of whether the reset did anything
1218+
self.assertTrue(q('textarea')[0].text.strip().startswith("# Document Shepherd Write-Up")) # TODO: This is a poor test of whether the reset did anything
12191219

12201220
def test_edit_doc_extresources(self):
12211221
url = urlreverse('ietf.doc.views_draft.edit_doc_extresources', kwargs=dict(name=self.docname))

‎ietf/templates/doc/shepherd_writeup.txt‎

Lines changed: 52 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
1-
{# 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
1+
{# 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
22

3-
*This version is dated 8 April 2022.*
3+
*This version is dated 1 June 2022.*
44

55
Thank you for your service as a document shepherd. Among the responsibilities is
6-
answering the questions in this writeup to give helpful context to Last Call and
7-
Internet Engineering Steering Group ([IESG][1]) reviewers, and your diligence in
8-
completing it, is appreciated. The full role of the shepherd is further
9-
described in [RFC 4858][2], and informally. You will need the cooperation of
10-
authors to complete these checks.
6+
answering the questions in this write-up to give helpful context to Last Call
7+
and Internet Engineering Steering Group ([IESG][1]) reviewers, and your
8+
diligence in completing it is appreciated. The full role of the shepherd is
9+
further described in [RFC 4858][2]. You will need the cooperation of the authors
10+
and editors to complete these checks.
1111

1212
Note that some numbered items contain multiple related questions; please be sure
1313
to answer all of them.
@@ -39,8 +39,10 @@ to answer all of them.
3939

4040
### Additional Reviews
4141

42-
5. Does this document need review from other IETF working groups or external
43-
organizations? Have those reviews occurred?
42+
5. Do the contents of this document closely interact with technologies in other
43+
IETF working groups or external organizations, and would it therefore benefit
44+
from their review? Have those reviews occurred? If yes, describe which
45+
reviews took place.
4446

4547
6. Describe how the document meets any required formal expert review criteria,
4648
such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.
@@ -63,41 +65,44 @@ to answer all of them.
6365
to be handed off to the responsible Area Director?
6466

6567
10. Several IETF Areas have assembled [lists of common issues that their
66-
reviewers encounter][6]. Do any such issues remain that would merit specific
67-
attention from subsequent reviews?
68+
reviewers encounter][6]. For which areas have such issues been identified
69+
and addressed? For which does this still need to happen in subsequent
70+
reviews?
6871

69-
11. What type of RFC publication is being requested on the IETF stream (Best
70-
Current Practice, Proposed Standard, Internet Standard, Informational,
71-
Experimental, or Historic)? Why is this the proper type of RFC? Do all
72-
Datatracker state attributes correctly reflect this intent?
72+
11. What type of RFC publication is being requested on the IETF stream ([Best
73+
Current Practice][12], [Proposed Standard, Internet Standard][13],
74+
[Informational, Experimental or Historic][14])? Why is this the proper type
75+
of RFC? Do all Datatracker state attributes correctly reflect this intent?
7376

74-
12. Has the interested community confirmed that any and all appropriate IPR
75-
disclosures required by [BCP 78][7] and [BCP 79][8] have been filed? If not,
76-
explain why. If yes, summarize any discussion and conclusion regarding the
77-
intellectual property rights (IPR) disclosures, including links to relevant
78-
emails.
77+
12. Have reasonable efforts been made to remind all authors of the intellectual
78+
property rights (IPR) disclosure obligations described in [BCP 79][8]? To
79+
the best of your knowledge, have all required disclosures been filed? If
80+
not, explain why. If yes, summarize any relevant discussion, including links
81+
to publicly-available messages when applicable.
7982

80-
13. Has each Author or Contributor confirmed their willingness to be listed as
81-
such? If the number of Authors/Editors on the front page is greater than 5,
82-
please provide a justification.
83+
13. Has each author, editor, and contributor shown their willingness to be
84+
listed as such? If the total number of authors and editors on the front page
85+
is greater than five, please provide a justification.
8386

84-
14. Identify any remaining I-D nits in this document. (See [the idnits tool][9]
85-
and the checkbox items found in Guidelines to Authors of Internet-Drafts).
86-
Simply running the idnits tool is not enough; please review the entire
87-
guidelines document.
87+
14. Document any remaining I-D nits in this document. Simply running the [idnits
88+
tool][8] is not enough; please review the ["Content Guidelines" on
89+
authors.ietf.org][15]. (Also note that the current idnits tool generates
90+
some incorrect warnings; a rewrite is underway.)
8891

89-
15. Should any informative references be normative or vice-versa?
92+
15. Should any informative references be normative or vice-versa? See the [IESG
93+
Statement on Normative and Informative References][16].
9094

9195
16. List any normative references that are not freely available to anyone. Did
9296
the community have sufficient access to review any such normative
9397
references?
9498

95-
17. Are there any normative downward references (see [RFC 3967][10],
96-
[BCP 97][11])? If so, list them.
99+
17. Are there any normative downward references (see [RFC 3967][9] and [BCP
100+
97][10]) that are not already listed in the [DOWNREF registry][17]? If so,
101+
list them.
97102

98-
18. Are there normative references to documents that are not ready for
99-
advancement or are otherwise in an unclear state? If they exist, what is the
100-
plan for their completion?
103+
18. Are there normative references to documents that are not ready to be
104+
submitted to the IESG for publication or are otherwise in an unclear state?
105+
If so, what is the plan for their completion?
101106

102107
19. Will publication of this document change the status of any existing RFCs? If
103108
so, does the Datatracker metadata correctly reflect this and are those RFCs
@@ -111,7 +116,7 @@ to answer all of them.
111116
associated with the appropriate reservations in IANA registries. Confirm
112117
that any referenced IANA registries have been clearly identified. Confirm
113118
that each newly created IANA registry specifies its initial contents,
114-
allocations procedures, and a reasonable name (see [RFC 8126][12]).
119+
allocations procedures, and a reasonable name (see [RFC 8126][11]).
115120

116121
21. List any new IANA registries that require Designated Expert Review for
117122
future allocations. Are the instructions to the Designated Expert clear?
@@ -123,11 +128,16 @@ to answer all of them.
123128
[4]: https://trac.ietf.org/trac/ops/wiki/yang-review-tools
124129
[5]: https://www.rfc-editor.org/rfc/rfc8342.html
125130
[6]: https://trac.ietf.org/trac/iesg/wiki/ExpertTopics
126-
[7]: https://www.rfc-editor.org/info/bcp78
127-
[8]: https://www.rfc-editor.org/info/bcp79
128-
[9]: https://www.ietf.org/tools/idnits/
129-
[10]: https://www.rfc-editor.org/rfc/rfc3967.html
130-
[11]: https://www.rfc-editor.org/info/bcp97
131-
[12]: https://www.rfc-editor.org/rfc/rfc8126.html
132-
{% else %}There is no default shepherd writeup template for the {{doc.stream}} stream.
133-
{% endif %}{% else %}There is no stream set for this document (thus, no default shepherd writeup template).{% endif %}
131+
[7]: https://www.rfc-editor.org/info/bcp79
132+
[8]: https://www.ietf.org/tools/idnits/
133+
[9]: https://www.rfc-editor.org/rfc/rfc3967.html
134+
[10]: https://www.rfc-editor.org/info/bcp97
135+
[11]: https://www.rfc-editor.org/rfc/rfc8126.html
136+
[12]: https://www.rfc-editor.org/rfc/rfc2026.html#section-5
137+
[13]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.1
138+
[14]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.2
139+
[15]: https://authors.ietf.org/en/content-guidelines-overview
140+
[16]: https://www.ietf.org/about/groups/iesg/statements/normative-informative-references/
141+
[17]: https://datatracker.ietf.org/doc/downref/
142+
{% else %}There is no default shepherd write-up template for the {{doc.stream}} stream.
143+
{% endif %}{% else %}There is no stream set for this document (thus, no default shepherd write-up template).{% endif %}

0 commit comments

Comments
 (0)