idnits 2.17.00 (12 Aug 2021) /tmp/idnits49123/draft-ietf-proto-wgchair-doc-shepherding-09.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 19. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 918. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 929. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 936. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 942. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (February 1, 2007) is 5581 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Obsolete informational reference (is this intentional?): RFC 4020 (Obsoleted by RFC 7120) -- Obsolete informational reference (is this intentional?): RFC 2434 (Obsoleted by RFC 5226) == Outdated reference: draft-narten-iana-considerations-rfc2434bis has been published as RFC 5226 Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 PROTO Team H. Levkowetz 3 Internet-Draft Ericsson 4 Intended status: Informational D. Meyer 5 Expires: August 5, 2007 Cisco/University of Oregon 6 L. Eggert 7 Nokia 8 A. Mankin 9 February 1, 2007 11 Document Shepherding from Working Group Last Call to Publication 12 draft-ietf-proto-wgchair-doc-shepherding-09 14 Status of this Memo 16 By submitting this Internet-Draft, each author represents that any 17 applicable patent or other IPR claims of which he or she is aware 18 have been or will be disclosed, and any of which he or she becomes 19 aware will be disclosed, in accordance with Section 6 of BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF), its areas, and its working groups. Note that 23 other groups may also distribute working documents as Internet- 24 Drafts. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 The list of current Internet-Drafts can be accessed at 32 http://www.ietf.org/ietf/1id-abstracts.txt. 34 The list of Internet-Draft Shadow Directories can be accessed at 35 http://www.ietf.org/shadow.html. 37 This Internet-Draft will expire on August 5, 2007. 39 Copyright Notice 41 Copyright (C) The IETF Trust (2007). 43 Abstract 45 This document describes methodologies that have been designed to 46 improve and facilitate IETF document flow processing. It specifies a 47 set of procedures under which a working group chair or secretary 48 serves as the primary Document Shepherd for a document that has been 49 submitted to the IESG for publication. Before this, the Area 50 Director responsible for the working group has traditionally filled 51 the shepherding role. 53 A Document Shepherd's responsibilities include: 55 o Providing the Document Shepherd Write-Up accompanying a document 56 that is forwarded to the IESG when publication is requested. 58 o During AD Evaluation by the Responsible Area Director, managing 59 the discussion between the editors, the working group, and the 60 Responsible Area Director. 62 o During an IETF Last Call, if performed for the shepherded 63 document, following up on community feedback and review comments. 65 o During IESG evaluation, following up on all IESG feedback 66 ("DISCUSS" and "COMMENT" items) related to the shepherded 67 document. 69 o Following up on IANA and RFC Editor requests in the post-approval 70 shepherding of the document. 72 In summary, a Document Shepherd continues to care for a shepherded 73 document during its post-WG lifetime just as he or she has cared for 74 it while responsible for the document in the working group. 76 Table of Contents 78 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 79 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 80 3. Process Description . . . . . . . . . . . . . . . . . . . . . 5 81 3.1. Document Shepherd Write-Up . . . . . . . . . . . . . . . . 6 82 3.2. Document Shepherding during AD Evaluation . . . . . . . . 10 83 3.3. Document Shepherding during IESG Evaluation . . . . . . . 11 84 4. Shepherding the Document's IANA Actions . . . . . . . . . . . 14 85 5. Document Shepherding after IESG Approval . . . . . . . . . . . 15 86 6. When Not to Use the Document Shepherding Process . . . . . . . 16 87 7. Security Considerations . . . . . . . . . . . . . . . . . . . 17 88 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 89 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 17 90 10. Informative References . . . . . . . . . . . . . . . . . . . . 18 91 Appendix A. Example Document Announcement Write-Ups . . . . . . . 18 92 A.1. Example Document Announcement Write-Up for 93 draft-ietf-avt-rtp-midi-format . . . . . . . . . . . . . . 19 94 A.2. Example Document Announcement Write-Up for 95 draft-ietf-imss-ip-over-fibre-channel . . . . . . . . . . 19 96 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 20 97 Intellectual Property and Copyright Statements . . . . . . . . . . 22 99 1. Introduction 101 Early in 2004, the IESG undertook several experiments aimed at 102 evaluating whether any of the proposed changes to the IETF document 103 flow process would yield qualitative improvements in document 104 throughput and quality. One such experiment, referred to as the 105 "PROTO process" or "PROTO" (because it was created by the "PROcess 106 and TOols" or PROTO [PROTO] team), is a set of methodologies designed 107 to involve working group chairs or secretaries more directly in their 108 documents' approval life cycle. In particular, the PROTO team 109 focused on improvements to the part of a document's life cycle that 110 occurs after the working group and document editor have forwarded it 111 to the IESG for publication. 113 By the end of 2004, the IESG had evaluated the utility of the PROTO 114 methodologies based on data obtained through several pilot projects 115 that had run throughout the year, and subsequently decided to adopt 116 the PROTO process for all documents and working groups. This 117 document describes this process. 119 The methodologies developed and piloted by the PROTO team focus on 120 the working group chair or secretary as the primary Document 121 Shepherd. The primary objective of this document shepherding process 122 is to improve document-processing throughput and document quality by 123 enabling a partnership between the Responsible Area Director and the 124 Document Shepherd. In particular, this partnership has the explicit 125 goal of enfranchising the Document Shepherd while at the same time 126 offloading a specific part of the follow-up work that has 127 traditionally been responsibility of the Responsible Area Director. 128 The Responsible Area Director has tens or many tens of documents to 129 follow, while the Document Shepherd has only a few at a time. 130 Flowing the responsibility to the working group level can ensure more 131 attention and more timely response. 133 Consequently, the document shepherding process includes follow-up 134 work during all document-processing stages after Working Group Last 135 Call, i.e., during AD Evaluation of a document, during IESG 136 evaluation, and during post-approval processing by IANA and the RFC 137 Editor. In these stages, it is the responsibility of the Document 138 Shepherd to track and follow up on feedback received on a document 139 from all relevant parties. 141 The Document Shepherd is usually a chair of the working group that 142 has produced the document. In consultation with the Responsible Area 143 Director, the chairs may instead decide to appoint the working group 144 secretary as the responsible Document Shepherd. 146 The remainder of this document is organised as follows: Section 3 147 outlines the overall document shepherding process. Section 3.1 148 describes the Document Shepherd Write-Up that accompanies the 149 publication request of a document. Section 3.2 describes the AD 150 Evaluation shepherding process and Section 3.3 describes IESG DISCUSS 151 shepherding. Finally, Section 6 describes those cases in which the 152 document shepherding process should not be used. 154 2. Terminology 156 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 157 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 158 document are to be interpreted as described in BCP 14, RFC 2119 159 [RFC2119]. 161 3. Process Description 163 The document shepherding process consists of the following tasks: 165 o Providing the Document Shepherd Write-Up accompanying a document 166 that is forwarded to the IESG when publication is requested, as 167 described in Section 3.1. 169 o During AD Evaluation of the document by the Responsible Area 170 Director, managing the discussion between the editors, the working 171 group and the Responsible Area Director, as described in 172 Section 3.2. 174 o During an IETF Last Call, if performed for the shepherded 175 document, following up on community feedback and review comments. 177 o During IESG evaluation, following up on all IESG feedback 178 ("DISCUSS" and "COMMENT" items) related to the shepherded 179 document, as described in Section 3.3. 181 o Following up on IANA and RFC Editor requests as described in 182 Section 4 and Section 5. 184 The shepherd must keep the document moving forward, communicating 185 about it with parties who review and comment it. The shepherd must 186 obtain the working group's consensus for any substantive proposed 187 changes. The shepherd is the leader for the document and for the 188 working group, and maintains a critical and technical perspective. 189 In summary, the Document Shepherd continues to care for a shepherded 190 document during its post-WG lifetime just as he or she has done while 191 responsible for the document in the working group. 193 Before any document shepherding takes place, a single Document 194 Shepherd MUST be identified for a document (he or she will be named 195 in the Document Shepherd Write-Up) . Frequently, the chairs and the 196 Responsible Area Director will decide that the working group will 197 adopt the PROTO process for all their future documents. After that 198 decision, the chairs, in consultation with the Responsible Area 199 Director, decide on who should act as Document Shepherd for any given 200 document. This is typically and by default one of the chairs of the 201 working group. In consultation with the Responsible Area Director, 202 the chairs MAY also decide to appoint the working group secretary as 203 Document Shepherd for a given document. The Document Shepherd SHOULD 204 NOT be an editor of the shepherded document. 206 It is intended that the Document Shepherd role is filled by one 207 person during the entire shepherding process. However, situations 208 may occur when the Document Shepherd role may be reassigned to 209 different persons during the lifetime of a document. It is up to the 210 chairs and Responsible Area Director to identify situations when this 211 may become necessary, and then consult to appoint a new Document 212 Shepherd. 214 It is important to note that the document shepherding process only 215 applies to documents that are the product of a working group. It 216 does not apply to documents that originate elsewhere. Additionally, 217 Section 6 discusses other instances in which the document shepherding 218 process does not apply. 220 3.1. Document Shepherd Write-Up 222 When a working group decides that a document is ready for submission 223 to the IESG for publication, it is the task of the Document Shepherd 224 to complete a "Document Shepherd Write-Up" for the document. 226 There are two parts to this task. First, the Document Shepherd 227 answers questions (1.a) to (1.j) below to give the Responsible Area 228 Director insight into the working group process that applied to this 229 document. Note that while these questions may appear redundant in 230 some cases, they are written to elicit information that the 231 Responsible Area Director must be aware of (to this end, pointers to 232 relevant entries in the WG archive are helpful). The goal here is to 233 inform the Responsible Area Director about any issues that may have 234 come up in IETF meetings, on the mailing list, or in private 235 communication that they should be aware of prior to IESG evaluation 236 of the shepherded document. Any significant issues mentioned in the 237 questionnaire will probably lead to a follow-up discussion with the 238 Responsible Area Director. 240 The second part of the task is to prepare the "Document Announcement 241 Write-Up" that is input to both the ballot for the IESG telechat and 242 to the eventual IETF-wide announcement message. Item number (1.k) 243 describes the elements of the Document Announcement Write-Up. 245 Some examples of Document Announcement Write-Ups are included in 246 Appendix A, and there are many more examples with subject lines such 247 as "Protocol Action" and "Document Action" in the IETF-announce 248 mailing list archive. 250 The initial template for the Document Shepherd Write-Up is included 251 below, but changes are expected over time. The latest version of 252 this template is available from the IESG section of the IETF web 253 site. 255 (1.a) Who is the Document Shepherd for this document? Has the 256 Document Shepherd personally reviewed this version of the 257 document and, in particular, does he or she believe this 258 version is ready for forwarding to the IESG for publication? 260 (1.b) Has the document had adequate review both from key WG members 261 and from key non-WG members? Does the Document Shepherd have 262 any concerns about the depth or breadth of the reviews that 263 have been performed? 265 (1.c) Does the Document Shepherd have concerns that the document 266 needs more review from a particular or broader perspective, 267 e.g., security, operational complexity, someone familiar with 268 AAA, internationalization or XML? 270 (1.d) Does the Document Shepherd have any specific concerns or 271 issues with this document that the Responsible Area Director 272 and/or the IESG should be aware of? For example, perhaps he 273 or she is uncomfortable with certain parts of the document, or 274 has concerns whether there really is a need for it. In any 275 event, if the WG has discussed those issues and has indicated 276 that it still wishes to advance the document, detail those 277 concerns here. Has an IPR disclosure related to this document 278 been filed? If so, please include a reference to the 279 disclosure and summarize the WG discussion and conclusion on 280 this issue. 282 (1.e) How solid is the WG consensus behind this document? Does it 283 represent the strong concurrence of a few individuals, with 284 others being silent, or does the WG as a whole understand and 285 agree with it? 287 (1.f) Has anyone threatened an appeal or otherwise indicated extreme 288 discontent? If so, please summarise the areas of conflict in 289 separate email messages to the Responsible Area Director. (It 290 should be in a separate email because this questionnaire is 291 entered into the ID Tracker.) 293 (1.g) Has the Document Shepherd personally verified that the 294 document satisfies all ID nits? (See 295 http://www.ietf.org/ID-Checklist.html and 296 http://tools.ietf.org/tools/idnits/). Boilerplate checks are 297 not enough; this check needs to be thorough. Has the document 298 met all formal review criteria it needs to, such as the MIB 299 Doctor, media type and URI type reviews? 301 (1.h) Has the document split its references into normative and 302 informative? Are there normative references to documents that 303 are not ready for advancement or are otherwise in an unclear 304 state? If such normative references exist, what is the 305 strategy for their completion? Are there normative references 306 that are downward references, as described in [RFC3967]? If 307 so, list these downward references to support the Area 308 Director in the Last Call procedure for them [RFC3967]. 310 (1.i) Has the Document Shepherd verified that the document IANA 311 consideration section exists and is consistent with the body 312 of the document? If the document specifies protocol 313 extensions, are reservations requested in appropriate IANA 314 registries? Are the IANA registries clearly identified? If 315 the document creates a new registry, does it define the 316 proposed initial contents of the registry and an allocation 317 procedure for future registrations? Does it suggest a 318 reasonable name for the new registry? See [RFC2434]. If the 319 document describes an Expert Review process has Shepherd 320 conferred with the Responsible Area Director so that the IESG 321 can appoint the needed Expert during the IESG Evaluation? 323 (1.j) Has the Document Shepherd verified that sections of the 324 document that are written in a formal language, such as XML 325 code, BNF rules, MIB definitions, etc., validate correctly in 326 an automated checker? 328 (1.k) The IESG approval announcement includes a Document 329 Announcement Write-Up. Please provide such a Document 330 Announcement Write-Up? Recent examples can be found in the 331 "Action" announcements for approved documents. The approval 332 announcement contains the following sections: 334 Technical Summary 335 Relevant content can frequently be found in the abstract 336 and/or introduction of the document. If not, this may be 337 an indication that there are deficiencies in the abstract 338 or introduction. 340 Working Group Summary 341 Was there anything in WG process that is worth noting? For 342 example, was there controversy about particular points or 343 were there decisions where the consensus was particularly 344 rough? 346 Document Quality 347 Are there existing implementations of the protocol? Have a 348 significant number of vendors indicated their plan to 349 implement the specification? Are there any reviewers that 350 merit special mention as having done a thorough review, 351 e.g., one that resulted in important changes or a 352 conclusion that the document had no substantive issues? If 353 there was a MIB Doctor, Media Type or other expert review, 354 what was its course (briefly)? In the case of a Media Type 355 review, on what date was the request posted? 357 Personnel 358 Who is the Document Shepherd for this document? Who is the 359 Responsible Area Director? 361 The Document Shepherd MUST send the Document Shepherd Write-Up to the 362 Responsible Area Director and iesg-secretary@ietf.org together with 363 the request to publish the document. The Document Shepherd SHOULD 364 also send the entire Document Shepherd Write-Up to the working group 365 mailing list. If the Document Shepherd feels that information which 366 may prove to be sensitive, lead to possible appeals or is personal 367 information needs to be written up, it SHOULD be sent in direct email 368 to the Responsible Area Director, because the Document Shepherd 369 Write-Up is published openly in the ID Tracker. Question (1.f) of 370 the Write-Up covers any material of this nature and specifies this 371 more confidential handling. 373 The Document Shepherd Write-Up is entered into the ID Tracker 374 [IDTRACKER] as a "Comment." The name and email address of the 375 Document Shepherd are entered into the ID Tracker, currently as a 376 "Brief Note" (this may change in the future). The email address of 377 the Document Shepherd MUST also be added to the "State or Version 378 Change Notice To" field (typically the email addresses of all working 379 group chairs, authors and the secretary will be added). 381 Entering the name and email of the Document Shepherd into the ID 382 Tracker is REQUIRED to ensure that he or she will be copied on the 383 email exchange between the editors, chairs, the IESG, the IESG 384 secretariat, IANA and the RFC Editor during the review and approval 385 process. There are still manual steps required for these parties to 386 ensure they include the Document Shepherd, but it is hoped that in 387 future, automated tools will ensure that Document Shepherds (and 388 others) receive necessary communications. 390 The contact information for the Document Shepherd is also important 391 for the Gen-ART team [GEN-ART], area directorates and other review 392 teams, so they can know to whom to address reviews, in addition to 393 the Responsible Area Director. 395 3.2. Document Shepherding during AD Evaluation 397 The steps for document shepherding during AD Evaluation are as 398 follows: 400 (2.a) The Responsible Area Director reads, evaluates and comments on 401 the document, as is the case when not using the document 402 shepherding process. If the Responsible Area Director 403 determines that the document is ready for IESG Evaluation, he 404 or she indicates this to the Document Shepherd and the 405 document shepherding process continues as described in 406 Section 3.3. 408 (2.b) If the Responsible Area Director has identified issues with a 409 document that must be addressed before IESG Evaluation can 410 commence, he or she sends a full evaluation to the Document 411 Shepherd and SHOULD also enter the review into the ID Tracker. 413 (2.c) The Document Shepherd reads the AD Evaluation comments, making 414 very certain that all comments are understood, so that it is 415 possible to follow up on them with the editors and working 416 group. If there is some uncertainty as to what is requested, 417 this SHOULD be resolved with the Responsible Area Director. 419 (2.d) The Document Shepherd sends the AD Evaluation comments to the 420 editors and to the working group mailing list, in order to 421 have a permanent record of the comments. It is RECOMMENDED 422 that the Document Shepherd solicit from the editors an 423 estimate on when the required changes will be complete and a 424 revised document can be expected. Working groups that use 425 issue tracking SHOULD also record the issues (and eventually 426 their resolution) in their issue tracker. 428 (2.e) During the production of a revised document that addresses the 429 AD Evaluation comments, it is RECOMMENDED that the editors 430 keep a list showing how each comment was addressed and what 431 the revised text is. It is RECOMMENDED that this list be 432 forwarded to the Responsible Area Director together with the 433 revised document. 435 (2.f) In the event that the editors or working group disagrees with 436 a comment raised by the Responsible Area Director or has 437 previously considered and dismissed the issue, the Document 438 Shepherd MUST resolve the issue with the Responsible Area 439 Director before a revised document can be submitted. 441 (2.g) The Document Shepherd iterates with the editors (and working 442 group, if required) until all outstanding issues have been 443 resolved and a revised document is available. At this point, 444 the Document Shepherd notifies the Responsible Area Director 445 and provides him or her with the revised document, the summary 446 of issues and the resulting text changes. 448 (2.h) The Responsible Area Director verifies that the issues he or 449 she found during AD Evaluation are resolved in the revised 450 version of the document by starting the process described in 451 this section at step (2.a). 453 (2.i) If the document underwent an IETF Last Call and the AD 454 concludes that significant issues were raised during the Last 455 Call, then steps (2.b) through (2.h) need to be applied 456 addressing the Last Call issues. This requires the 457 Responsible Area Director to present to the Document Shepherd 458 those Last Call Issues raised only to the IESG. 460 3.3. Document Shepherding during IESG Evaluation 462 During IESG Evaluation of a document, ADs can bring forward two kinds 463 of remarks about a document: DISCUSS item and COMMENT items. A 464 DISCUSS blocks a document's approval process until it has been 465 resolved; a COMMENT does not. This section details the steps that a 466 Document Shepherd takes to resolve any DISCUSS and COMMENT items 467 brought forward against a shepherded document during IESG Evaluation. 469 Note that DISCUSS and COMMENT items are occasionally written in a 470 manner that makes their intent unclear. In these cases, the Document 471 Shepherd SHOULD start a discussion with the ADs who brought the items 472 up to clarify their intent, keeping the Responsible Area Director 473 informed. If this fails to clarify the intent, the Responsible Area 474 Director may need to work towards a clarification inside the IESG. 476 (3.a) Leading up to the IESG conference call, the Document Shepherd 477 may see emails about the document from directorate reviewers 478 on behalf of one or more ADs and also emailed copies of 479 DISCUSS and COMMENT items entered into the ID Tracker. The 480 Document Shepherd SHOULD immediately begin to work on 481 resolving DISCUSS and COMMENT items with the ADs who have 482 raised them, keeping the Responsible Area Director copied on 483 the email exchange, so that he or she is able to support the 484 the activity during the conference call. When dealing with 485 directorate reviews, the Document Shepherd MUST involve the 486 ADs to whom these directorates report to ensure that these ADs 487 consider the review comments that need resolving. 489 (3.b) Immediately following the conference call, when the document 490 changes state from the "IESG Evaluation" state to one of the 491 states requiring Document Shepherd action, e.g., "IESG 492 Evaluation: Revised ID Needed" or "IESG Evaluation: AD 493 Followup", the Document Shepherd will receive email. A state 494 of "AD Followup" typically signifies the Responsible Area 495 Director's hope that a resolution may be possible through a 496 continued discussion or (more usually) through a small set of 497 changes as "Notes to the RFC Editor." 499 Note that there may be very exceptional cases when DISCUSS 500 items are registered after an IESG conference call. In these 501 cases, the AD who has raised the DISCUSS MUST notify the 502 Document Shepherd about it. (The notification facility in the 503 ID Tracker is very convenient for this purpose and also for 504 the cases where the DISCUSS and COMMENT items are updated 505 after they are partially resolved.) 507 (3.c) The Document Shepherd then queries the ID Tracker to collect 508 the remaining DISCUSS and COMMENT items raised against the 509 document. The Document Shepherd analyses these items and 510 initialises contact with the ADs who have placed them. The 511 Responsible Area Director MUST be copied on all correspondence 512 related to active DISCUSS or COMMENT items. This does not 513 place the Responsible Area Director in the critical path 514 towards a resolution, but should keep him or her informed 515 about the state of the discussion. 517 +-------+ +-------+ +-------+ 518 | (3.b) | -----------> | (3.c) | ------------> | (3.d) | 519 +-------+ Comments +-------+ Comments +-------+ 520 collected /|\ | understood 521 | | 522 | | Comments not fully understood 523 | | (Further AD/Document Shepherd 524 | | discussion required) 525 +---+ 527 (3.d) The Document Shepherd then coordinates the resolution of 528 DISCUSS and COMMENT items and builds a consistent 529 interpretation of the comments. This step is similar to much 530 of the process described in Section 3.2. 532 +-------+ +-------+ 533 | (3.c) | ---------------> | (3.d) | 534 +-------+ Consistent +-------+ 535 /|\ interpretation | 536 | | Further AD/Document Shepherd 537 | | discussion required 538 +--------------------------+ 540 (3.e) The Document Shepherd then communicates the DISCUSS and 541 COMMENT items to the document editors and the working group, 542 alerting them of any changes to the document that have 543 accumulated during IESG processing, such as "Notes to the RFC 544 Editor." If any changes will be substantive, the Document 545 Shepherd, in consultation with the Responsible Area Director, 546 as during other stages, MUST confirm working group consensus 547 or sometimes even IETF consensus. 549 (3.f) After the editors resolve the DISCUSS and COMMENT items, the 550 Document Shepherd reviews the resulting new version of the 551 document, which will be a revised document, a set of "Notes to 552 the RFC Editor", or both, using his or her technical expertise 553 to ensure that all raised DISCUSS and COMMENT issues have been 554 resolved. 556 Note that the Document Shepherd MAY also suggest resolutions 557 to DISCUSS and COMMENT items, enter them into an issue 558 tracker, or perform other steps to streamline the resolution 559 of the evaluation comments. It is very important to resolve 560 the comments in a timely way, while the discussion is current 561 for everyone involved. 563 (3.g) When the Document Shepherd is satisfied that the revised 564 document addresses the evaluation comments, he or she 565 communicates the resolution to the Responsible Area Director 566 and the ADs that had raised the DISCUSS and COMMENT items. 568 (3.h) Each AD who had raised a DISCUSS checks whether the 569 communicated resolution addresses his or her items. If it 570 does, the AD will clear the DISCUSS. It it does not, the AD 571 notifies the Document Shepherd and adds information to the ID 572 Tracker explaining why the DISCUSS was not resolved. The 573 Document Shepherd informs the working group accordingly. 574 (COMMENT items need not be checked and cleared, because they 575 do not block the document, but ADs are encouraged to do so.) 577 If a DISCUSS was not resolved to the satisfaction of the AD 578 that has raised it or the Responsible Area Director, two 579 possibilities exist: 581 (a) The process returns to step (3.d), or 583 (b) If no progress can be made on the resolution of the 584 DISCUSS with the AD who has raised it, despite repeated 585 clarifications and discussions, the Responsible Area 586 Director should take over continued shepherding of the 587 document. Such a situation may be indicative of larger 588 issues that the PROTO process was not designed to handle. 590 Once the process above has cleared all DISCUSS items, document 591 shepherding continues with step (3.i). 593 (3.i) The Responsible Area Director moves the document to the 594 "Approved - Announcement to be sent" state in the ID Tracker. 595 If he or she deems the changes to the revised document 596 significant, there may be a new WG last call, or possibly a 597 new IETF last call. The document goes through a new full IESG 598 Evaluation process if there is a new IETF last call. 600 4. Shepherding the Document's IANA Actions 602 IETF working group documents often include considerations requiring 603 actions by the IANA, such as creating a new registry or adding 604 information to an existing registry, perhaps after consulting an 605 IESG-appointed Expert. Sometimes the Document Shepherd must keep 606 track of certain IANA actions to be completed by the IESG, such as 607 ratifying the appointment of a designated Expert called for in the 608 IANA Considerations. IANA-related processing may also include a 609 specified type of Expert review, such as review of proposed MIME 610 media types on the designated ietf-types mailing list. 612 The IANA reviews IETF documents and requests responses at any or all 613 of the following times: in response to IETF Last Call, during the 614 IESG Evaluation review of the document, and at the time when the IANA 615 performs actions in its web-based registry for the document, usually 616 but not always after IESG approval of the document. More details of 617 the IANA process and IETF interaction are found in [RFC2434]. 619 At the time of this publication, RFC2434 is under revision 620 [I-D.narten-iana-considerations-rfc2434bis] and the updates are and 621 will be of value to the Document Shepherd. Note that the Document 622 Shepherd MUST determine (by individual review and consultation with 623 others) what is the most recent and the most applicable IANA 624 information and guidance for his or her document, be it the overall 625 guidance, or external documents in his or her area, or in other 626 areas. An example of an external document is [RFC4020]. 628 Whenever an IANA request comes, during whatever phase of the 629 shepherding process, the requester from IANA MUST ensure that the 630 Document Shepherd and the Responsible Area Director both receive the 631 request. The Document Shepherd is responsible for responding as 632 rapidly as possible. He or she should discuss requests that 633 introduce any possible concerns with the working group. The Document 634 Shepherd and the Responsible Area Director may decide in consultation 635 that an IANA request leads to a change that needs additional review 636 or approval. 638 In general, the Document Shepherd ensures that the IANA process 639 completes, checks that the registry is correct and that the IANA 640 Matrix (http://www.iana.org/numbers.html) is complete and consistent, 641 and troubleshoots when all is not well. At the end of IANA 642 processing, the Document Shepherd should be sure that the RFC Editor 643 has acknowledged IANA conclusion, i.e., that the handoff has been 644 made. 646 In summary, the task of shepherding the IANA actions is often 647 overlooked, but is as important to coordinate and manage as all the 648 other document reviews the Document Shepherd has managed. As with 649 those, the Document Shepherd contributes greatly to quality and 650 timeliness of the document by effective and responsive shepherding of 651 the IANA requests. 653 5. Document Shepherding after IESG Approval 655 After the IESG evaluation and resolution described in Section 3.3, 656 the IESG approves the document, and the Responsible Area Director 657 uses the ID Tracker to ask for any final changes to the Document 658 Announcement Write-Up and for it to be issued. The Document Shepherd 659 may have some edits for the Responsible Area Director, such as minor 660 "Notes to the RFC Editor", and this is the time to consult and 661 provide them. 663 The IESG approval announcement goes to the general community and to 664 the RFC Editor, and now the Document Shepherd (identified in the 665 Announcement Write-Up) continues to shepherd the document through its 666 technical publication. The RFC Editor currently makes a number of 667 types of requests to the authors, Document Shepherd and Responsible 668 Area Director. The Document Shepherd SHOULD lead in responding to 669 the RFC Editor and shepherd the document during the post-approval 670 period to its publication. 672 The RFC Editor request types include: editorial queries about 673 dangling, missing, informative and normative citations (good 674 shepherding should try to catch these earlier, but they happen); 675 requests for the document source (e.g., XML or nroff); occasional 676 technical comments; and copy-edits for review and close scrutiny by 677 the authors (AUTH48). For the latter, the Document Shepherd SHOULD 678 lead in checking that copy-edits have in no case affected a consensus 679 wording of the working group which prepared the document, and SHOULD 680 bring speed to this checking by multiple coauthors. The Document 681 Shepherd also consults with the Responsible Area Director on 682 reviewing proposed post-approval changes to the document by any 683 author. These may require Area Director approval, and they often 684 need to be presented to the working group for consent if not a full 685 consensus procedure. 687 As in other phases of document shepherding, the Document Shepherd 688 provides attentiveness and timeliness by serving as the informed 689 representative of the document and helping its advancement and its 690 integrity. 692 6. When Not to Use the Document Shepherding Process 694 As mentioned in Section 3, the Document Shepherd SHOULD NOT be an 695 editor of the shepherded document. If this cannot be avoided by 696 making another working group chair or secretary the Document 697 Shepherd, the document shepherding process SHOULD NOT be used. There 698 are several other cases in which the document shepherding process 699 SHOULD NOT be used. These include: 701 1. Cases, where the Document Shepherd is the primary author or 702 editor of a large percentage of the documents produced by the 703 working group. 705 2. Cases, where the Responsible Area Director expects communication 706 difficulties with the Document Shepherd (either due to 707 experience, strong views stated by the Document Shepherd, or 708 other issues). 710 3. Cases, where the working group itself is either very old, losing 711 energy, or winding down, i.e., cases, where it would not be 712 productive to initiate new processes or procedures. 714 Finally, note that other cases exist in which using the document 715 shepherding process may not be productive. The final determination 716 as to whether to use the document shepherding process or not is left 717 to the Responsible Area Director. If the document shepherding 718 process is not used, the Responsible Area Director acts as Document 719 Shepherd, per the existing procedures of shepherding by Area 720 Directors. 722 7. Security Considerations 724 This document specifies a change to IETF document-processing 725 procedures. As such, it neither raises nor considers protocol- 726 specific security issues. 728 8. IANA Considerations 730 This document creates no new requirements on IANA namespaces or other 731 IANA requirements. 733 9. Acknowledgments 735 This document is the product of PROTO team, which includes the 736 authors as well as Bill Fenner, Barbara Fuller, and Margaret 737 Wasserman. Aaron Falk worked actively in PROTO until the start of 738 2006 and worked on earlier versions of the document. 740 The Document Shepherd Write-Up originated in an idea by John Klensin. 741 Thomas Narten and Margaret Wasserman implemented it for the entire 742 Internet Area, and their template was the basis of the version used 743 today. 745 Colin Perkins wrote the original Document Announcement Write-Up for 746 draft-ietf-avt-rtp-midi-format included in Appendix A.1. David Black 747 wrote the original Document Announcement Write-Up for 748 draft-ietf-imss-ip-over-fibre-channel included in Appendix A.2. Both 749 original announcements have been modified to reflect changes to the 750 Document Announcement Write-Up template since they were written. 752 Frank Ellermann and Olafur Gudmundsson have suggested improvements to 753 the document during IETF Last Call. 755 10. Informative References 757 [RFC4020] Kompella, K. and A. Zinin, "Early IANA Allocation of 758 Standards Track Code Points", BCP 100, RFC 4020, 759 February 2005. 761 [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an 762 IANA Considerations Section in RFCs", BCP 26, RFC 2434, 763 October 1998. 765 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 766 Requirement Levels", BCP 14, RFC 2119, March 1997. 768 [RFC3967] Bush, R. and T. Narten, "Clarifying when Standards Track 769 Documents may Refer Normatively to Documents at a Lower 770 Level", BCP 97, RFC 3967, December 2004. 772 [I-D.narten-iana-considerations-rfc2434bis] 773 Narten, T. and H. Alvestrand, "Guidelines for Writing an 774 IANA Considerations Section in RFCs", 775 draft-narten-iana-considerations-rfc2434bis-05 (work in 776 progress), September 2006. 778 [IDTRACKER] 779 "The IETF Internet-Draft Tracker", Web 780 Application: https://datatracker.ietf.org/, 2002. 782 [PROTO] "The IESG PROcess and TOols (PROTO) Team", Web 783 Page: http://psg.com/~mrw/PROTO-Team, 2004. 785 [GEN-ART] "The General Area Review Team (GEN-ART)", Web Page: 786 http://www.alvestrand.no/ietf/gen/review-guidelines.html, 787 2005. 789 Appendix A. Example Document Announcement Write-Ups 791 This appendix includes two examples of Document Announcement Write- 792 Ups. Many more examples with Subject lines such as "Protocol Action" 793 and "Document Action" can be found in the IETF-announce mailing list 794 archive. 796 A.1. Example Document Announcement Write-Up for 797 draft-ietf-avt-rtp-midi-format 799 Technical Summary 801 These documents define the RTP Payload format for MIDI (Musical 802 Instrument Digital Interface), and additional guidelines on 803 implementation specifically concerning the timing of reception and 804 transmission for best performance in different applications. MIDI 805 is a real-time media, which however is brittle to losses and 806 errors. Therefore the RTP payload format defines recovery 807 journals as a way of avoiding persistent audible errors, and 808 discusses congestion control handling for these journals. 810 The RTP payload for MIDI encodes the broad range of MIDI commands. 811 The format is suitable for interactive applications (such as 812 network musical performance) and content-delivery (such as file 813 streaming). 815 Working Group Summary 817 There is consensus in the WG to publish these documents. 819 Document Quality 821 This RTP Payload format has been implemented during the 822 development of the specification and successfully tested over an 823 IP network between two remote sites, thus showing that the 824 technical solution is successfully working. It has been reviewed 825 by the MIDI Manufacturers Association and their comments have been 826 addressed. 828 Personnel 830 Magnus Westerlund and Colin Perkins jointly shepherded this 831 document. Allison Mankin reviewed the document for the IESG, 832 including a careful review with the editor of the media types, in 833 parallel with ietf-types list review requested on 2006-01-08, 834 which raised no issues. 836 A.2. Example Document Announcement Write-Up for 837 draft-ietf-imss-ip-over-fibre-channel 839 Technical Summary 841 This document specifies the encapsulation of IPv6, IPv4 and ARP 842 packets over Fibre Channel. This document also specifies the 843 methods for forming IPv6 link-local addresses and statelessly 844 autoconfigured IPv6 addresses on Fibre Channel networks, and a 845 mechanism to perform IPv4 address resolution over Fibre Channel 846 networks. This document (when published as RFC) obsoletes RFC2625 847 and RFC3831. 849 Working Group Summary 851 This document has been reviewed by Fibre Channel experts in 852 Technical Committee T11 (Fibre Channel standards organization) in 853 addition to members of the IMSS WG. There is solid support for 854 this document both in the WG and from T11. 856 Document Quality 858 This document replaces and consolidates two separate RFCs on IPv4 859 over Fibre Channel (RFC 2625) and IPv6 over Fibre Channel (RFC 860 3831). Most of its technical content is unchanged from those 861 RFCs. The technical changes that have been made are primarily 862 based on implementation experience. 864 Personnel 866 The protocol has been reviewed for the IESG by David L. Black (WG 867 chair). Bert Wijnen has reviewed this document for the IESG. In 868 addition, Brian Haberman has done a review for the INT Area as 869 requested by WG-chair (David Black) via Margaret Wasserman. 871 Authors' Addresses 873 Henrik Levkowetz 874 Torsgatan 71 875 Stockholm S-113 37 876 Sweden 878 Phone: +46 708 32 16 08 879 Email: henrik@levkowetz.com 881 David Meyer 882 1225 Kincaid St 883 Eugene, OR 97403 884 USA 886 Phone: +1 541 346 1747 887 Email: dmm@1-4-5.net 888 Lars Eggert 889 Nokia Research Center 890 P.O. Box 407 891 Nokia Group 00045 892 Finland 894 Phone: +49 50 48 24461 895 Email: lars.eggert@nokia.com 896 URI: http://research.nokia.com/people/lars_eggert 898 Allison Mankin 900 Phone: +1-301-728-7199 901 Email: mankin@psg.com 902 URI: http://www.psg.com/~mankin 904 Full Copyright Statement 906 Copyright (C) The IETF Trust (2007). 908 This document is subject to the rights, licenses and restrictions 909 contained in BCP 78, and except as set forth therein, the authors 910 retain all their rights. 912 This document and the information contained herein are provided on an 913 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 914 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 915 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 916 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 917 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 918 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 920 Intellectual Property 922 The IETF takes no position regarding the validity or scope of any 923 Intellectual Property Rights or other rights that might be claimed to 924 pertain to the implementation or use of the technology described in 925 this document or the extent to which any license under such rights 926 might or might not be available; nor does it represent that it has 927 made any independent effort to identify any such rights. Information 928 on the procedures with respect to rights in RFC documents can be 929 found in BCP 78 and BCP 79. 931 Copies of IPR disclosures made to the IETF Secretariat and any 932 assurances of licenses to be made available, or the result of an 933 attempt made to obtain a general license or permission for the use of 934 such proprietary rights by implementers or users of this 935 specification can be obtained from the IETF on-line IPR repository at 936 http://www.ietf.org/ipr. 938 The IETF invites any interested party to bring to its attention any 939 copyrights, patents or patent applications, or other proprietary 940 rights that may cover technology that may be required to implement 941 this standard. Please address the information to the IETF at 942 ietf-ipr@ietf.org. 944 Acknowledgment 946 Funding for the RFC Editor function is provided by the IETF 947 Administrative Support Activity (IASA).