idnits 2.17.00 (12 Aug 2021) /tmp/idnits58424/draft-leiba-extended-doc-shepherd-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. 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 : ---------------------------------------------------------------------------- -- The draft header indicates that this document updates RFC4858, but the abstract doesn't seem to directly say this. It does mention RFC4858 though, so this could be OK. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year (Using the creation date from RFC4858, updated by this document, for RFC5378 checks: 2004-07-13) -- 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 (July 10, 2013) is 3236 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- No issues found here. Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group B. Leiba 3 Internet-Draft Huawei Technologies 4 Updates: 4858 (if approved) July 10, 2013 5 Intended status: Informational 6 Expires: January 09, 2014 8 Process Experiment: Document Shepherding Throughout a Document's 9 Lifecycle 10 draft-leiba-extended-doc-shepherd-02 12 Abstract 14 RFC 4858 talks about "Document Shepherding from Working Group Last 15 Call to Publication". There's a significant part of a document's 16 life that happens before working group last call, starting, really, 17 at the time a working group begins discussing a version of the idea 18 that's been posted as an individual draft. It seems reasonable and 19 helpful in many situations to begin shepherding when there's a call 20 for adoption as a working group document. This document extends RFC 21 4858, describing how that extended shepherding function might work 22 and what tasks might be involved throughout the document's lifecycle, 23 and suggesting how Working Group Chairs might choose to implement 24 extended shepherding. 26 Status of this Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at http://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on January 09, 2014. 43 Copyright Notice 45 Copyright (c) 2013 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents (http://trustee.ietf.org/ 50 license-info) in effect on the date of publication of this document. 51 Please review these documents carefully, as they describe your rights 52 and restrictions with respect to this document. Code Components 53 extracted from this document must include Simplified BSD License text 54 as described in Section 4.e of the Trust Legal Provisions and are 55 provided without warranty as described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 60 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . . 3 61 2. The Document Shepherd as a "Function" . . . . . . . . . . . . 3 62 3. Stages in a Document's Lifecycle . . . . . . . . . . . . . . . 4 63 3.1. Stage: Call for Adoption . . . . . . . . . . . . . . . . . . 5 64 3.2. Stage: Working Group Document . . . . . . . . . . . . . . . 7 65 3.3. Stage: Working Group Last Call . . . . . . . . . . . . . . . 9 66 3.4. Stage: Shepherd Writeup Underway . . . . . . . . . . . . . . 10 67 3.5. Stage: AD Review . . . . . . . . . . . . . . . . . . . . . . 12 68 3.6. Stage: IETF Last Call . . . . . . . . . . . . . . . . . . . 12 69 3.7. Stage: Waiting for AD Go-Ahead . . . . . . . . . . . . . . . 14 70 3.8. Stage: IESG Evaluation . . . . . . . . . . . . . . . . . . . 14 71 3.9. Stage: Approved by the IESG . . . . . . . . . . . . . . . . 16 72 3.10. Stage: In RFC Editor Queue . . . . . . . . . . . . . . . . . 16 73 3.11. Stage: AUTH48 . . . . . . . . . . . . . . . . . . . . . . . 17 74 3.12. Stage: Published . . . . . . . . . . . . . . . . . . . . . . 18 75 4. Some Final Notes . . . . . . . . . . . . . . . . . . . . . . . 18 76 5. Security Considerations . . . . . . . . . . . . . . . . . . . 18 77 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 78 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18 79 7.1. Normative References . . . . . . . . . . . . . . . . . . . . 18 80 7.2. Informative References . . . . . . . . . . . . . . . . . . . 18 81 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 19 83 1. Introduction 85 RFC 4858 talks about "Document Shepherding from Working Group Last 86 Call to Publication" [RFC4858]. There's a significant part of a 87 document's life that happens before Working Group Last Call, 88 starting, really, at the time a working group begins discussing a 89 version of the idea that's been posted as an individual draft. It 90 seems reasonable and helpful in many situations to begin shepherding 91 when there's a call for adoption as a working group document. This 92 document extends RFC 4858, describing how that extended shepherding 93 function might work and what tasks might be involved throughout the 94 document's lifecycle, and suggesting how Working Group Chairs might 95 choose to implement extended shepherding. 97 It is very common to see documents progress far too slowly, sometimes 98 languishing for many months and even for years due to neglect. 99 Sometimes a working group will intentionally set a document aside, 100 put it on a back burner while it works on more pressing things. But 101 it's often not intentional: the document sits around because of lack 102 of follow-through, waking up occasionally when someone realizes that 103 the last version has expired and an IETF meeting is coming up soon. 105 We would really prefer to process documents efficiently, ensuring 106 that whatever happens is intentional: that documents are set aside 107 only when it makes sense to do so, and that active documents move 108 forward in the process, with someone responsible for making sure that 109 happens. 111 This document suggests specific tasks a Working Group Chair should be 112 doing or delegating in order to maintain forward progress, 113 accountability, and quality control on a working group document. It 114 adds to what's in RFC 4858, intending to extend it, not replace it. 115 Major extensions involve assigning a Shepherd and defining specific 116 tasks earlier in a document's life, and possibly delegating Document 117 Shepherd tasks to a Shepherd who is neither a Chair nor the Working 118 Group Secretary (consistent with the IESG Statement on Document 119 Shepherds [Stmt]). 121 The summaries in each section of the tasks expected at that stage in 122 the document's lifecycle can make this an easy reference and 123 checklist for Working Group Chairs and Document Shepherds. 125 The specific mechanism suggested here will not be suitable for all 126 working groups, all management models, and all situations. While 127 it's a good idea to have the stages laid out and the tasks at each 128 stage identified, not all working groups will benefit from having a 129 single document shepherd designated at the start. Indeed, when a 130 document is legitimately years in the making, personnel may come and 131 go and changes will be necessary. A particular working group might 132 be working only on one document at a time, with all tasks shared 133 between the chairs. 135 For these and other reasons, the suggestions herein are meant to be 136 adapted to specific situations to retain the underlying objective of 137 maintaining progress through active involvement. 139 1.1. Notational Conventions 141 It is important to note that this document makes no formal process 142 changes and there is no normative language here. 144 Initial Capitals are used in some terms, such as "Document Shepherd", 145 to indicate that those terms represent specific roles in the 146 management model that is described. 148 2. The Document Shepherd as a "Function" 149 This document looks at the Document Shepherd as a "function", rather 150 than as a single person. The Document Shepherd Function has a set of 151 tasks that need to be performed, but the tasks do not all have to be 152 performed by one individual. 154 While, ultimately, it is the responsibility of the Working Group 155 Chairs to ensure that the shepherding tasks get done, the Chairs do 156 not have to do all those tasks by themselves. From Section 6.1 of 157 the Working Group Guidelines and Procedures [RFC2418]: 159 The Working Group Chair is concerned with making forward progress 160 through a fair and open process, and has wide discretion in the 161 conduct of WG business. The Chair must ensure that a number of 162 tasks are performed, either directly or by others assigned to the 163 tasks. 165 This document proposes an extended set of Document Shepherd tasks, 166 well beyond those covered in RFC 4858. In many cases it will be 167 reasonable to assign the entire Document Shepherd Function to one 168 person (to a Chair or to a non-chair delegate), but in many other 169 cases the Chairs will likely choose to delegate parts of that 170 function and keep other parts for themselves. In any case, the 171 Chairs remain responsible for the management of the working group; 172 they are whom the Area Director will come to if something goes wrong 173 or things fail to make progress. 175 As we talk, then, about what the "Document Shepherd" does, understand 176 that the individual doing each particular task will be the one 177 assigned that task as the work on a particular document is laid out. 178 When we say that the Shepherd should do a task in consultation with 179 the Chairs, that's automatically true when it's already a Chair who's 180 doing it. 182 And this bears repeating: Nothing in this document is suggesting that 183 the Working Group Chairs abdicate any responsibility. They have the 184 final responsibility for managing each document's progress and for 185 managing the working group in general. Any Chair who chooses to 186 delegate some of this responsibility must still ensure that it's 187 carried out properly. And any Chair who does not feel comfortable 188 delegating any of this should not do so. 190 3. Stages in a Document's Lifecycle 192 From the time a working group is asked to take on a document as one 193 of its work items, the document will go through a number of stages: 195 1. Call for Adoption 196 2. Working Group Document 197 3. Working Group Last Call 198 4. Shepherd Writeup Underway 199 5. AD Review 200 6. IETF Last Call 201 7. Waiting for AD Go-Ahead 202 8. IESG Evaluation 203 9. Approved by the IESG 204 10. In RFC Editor Queue 205 11. AUTH48 206 12. Published 208 Through most of those stages steps will have to be taken, tasks will 209 need to be performed, to make sure the document moves forward, that 210 consensus is reached, that the right reviews are done, that updates 211 are made, that consensus still holds after significant changes, and 212 so on. The Document Shepherd Function comprises that set of tasks. 214 The following sections will discuss some of the tasks needed at each 215 stage, and will suggest how Working Group Chairs might handle those 216 tasks and their delegation -- how the Document Shepherd Function 217 might work. The details will vary, depending upon how each working 218 group is managed, but what follows should be a good example, and will 219 provide a basis for adaptation. And see also [RFC4858], Section 3. 221 3.1. Stage: Call for Adoption 223 At the point that the working group begins considering adoption of a 224 document, the Working Group Chairs have some decisions to make. This 225 is the time to choose a Responsible Chair for the document, much as 226 it will eventually have a Responsible Area Director later in its 227 life. The Responsible Chair will be the one who oversees the 228 Document Shepherd Function and has primary responsibility for making 229 sure that everything gets done. 231 The Responsible Chair should then (perhaps in consultation with the 232 other Chair(s), depending upon the Chairs' agreement about division 233 of work) decide how much of the Document Shepherd Function to handle 234 herself, and which pieces, if any, to delegate. Examples might be as 235 follows: 237 o The Responsible Chair will be the sole Document Shepherd. 239 o The Responsible Chair will be the Document Shepherd through the 240 end of the Working Group Document stage, and will appoint a non- 241 chair Shepherd during that stage to handle subsequent shepherding 242 tasks (similar to what's set out in RFC 4858). 244 o The Responsible Chair will appoint a non-chair Shepherd to handle 245 the early shepherding tasks, and the Responsible Chair will take 246 over the Document Shepherd tasks for Working Group Last Call and 247 beyond (the converse of the previous example). 249 o The Responsible Chair will appoint a non-chair Shepherd to handle 250 all shepherding tasks from start to end. The delegate will work 251 closely with the Responsible Chair, heavily supervised (perhaps 252 this is a training situation). 254 o The Responsible Chair will appoint a non-chair Shepherd to handle 255 all shepherding tasks from start to end. The delegate will report 256 to the Responsible Chair, and will be supervised at certain key 257 points. 259 o The Responsible Chair will appoint a non-chair Shepherd to handle 260 all shepherding tasks autonomously (perhaps for a very experienced 261 Shepherd, well trusted by the Chairs). 263 And so on... there may be many combinations, many levels of 264 supervision vs autonomy, many ways to divide the work. It's also 265 possible to delegate to more than one non-chair Shepherd at different 266 stages. The Chairs need to judge the extent to which continuity and 267 centralized responsibility are important for the document in question 268 and the management style of the chairs, and whether making it one 269 other person (supervised by one Responsible Chair) is best. 271 Some Chairs may prefer to handle all tasks themselves, because, after 272 all, they remain responsible for their successful completion. Yet 273 there can be a lot gained by delegating much of the work. Delegating 274 work and giving a degree of responsibility to relatively more junior 275 participants gets people more closely engaged with the working group 276 and with the IETF. Giving significant responsibility can be an 277 excellent training exercise, preparing participants to take on future 278 roles as Working Group Chairs. And in a busy working group, 279 offloading work from the Chairs to senior, experienced people can 280 prevent the Chairs from being overcommitted, enabling the work to 281 move forward much more efficiently. 283 And, of course, a non-chair Shepherd can and should consult with the 284 Responsible Chair whenever she feels the need, and certainly whenever 285 issues arise of which the Chairs should be aware, or about which the 286 Shepherd needs advice or other help. 288 Once it is determined who will handle the Document Shepherd tasks, 289 the Shepherd needs to do the actual adoption process. The details 290 will vary based on how the particular working group is run, but a 291 typical process will start with posting a call for adoption to the 292 working group mailing list, pointing to the individual draft that's 293 being considered. There'll be a comment period for adoption 294 discussion, after which the Shepherd will, based on working group 295 discussion, give a recommended judgment to the Chairs. 297 Assuming that the document was adopted, the Chairs will appoint one 298 or more Editors for the working group version of the document (these 299 are often, but not always, the same people who wrote the individual 300 version, and the Chairs should put some thought into who the right 301 Editors should be), and will handle the datatracker updates (for 302 which Chair access is required). The Chairs should not forget to 303 record the name and email address of the Document Shepherd in the 304 tracker -- this will ensure that the Shepherd is copied on necessary 305 email later. 307 In summary, the tasks at the Call for Adoption stage might be as 308 follows: 310 1. Chairs: Select a Responsible Chair to handle the document. 311 2. Responsible Chair: Decide on a work/delegation plan. 312 3. Responsible Chair: Possibly appoint a non-chair Shepherd; else 313 the Responsible Chair becomes the Shepherd. 314 4. Shepherd: Make the call for adoption; set deadlines and schedule. 315 5. Shepherd: Communicate the result to the Chairs; 316 6. Chairs: Announce the result and appoint Document Editor(s) for 317 the WG document. 318 7. Chairs: Update the datatracker; approve -00 version submission. 320 3.2. Stage: Working Group Document 322 Once a -00 version is posted, the Shepherd's primary task is to keep 323 the document moving forward: keeping discussion going, making sure 324 issues are tracked and document updates are posted, and helping 325 things toward consensus. Let's not downplay the importance of active 326 management here: this is where things so often fall short, what 327 causes documents to take *years* to complete. The Shepherd should 328 not rush discussions that are useful, but the Shepherd should make 329 sure that things don't get lost in the forest either. 331 The Chairs will decide how the working group should be managed, and 332 any non-chair Shepherd should be working with the Chairs at this 333 stage, communicating any difficulties and getting help with issue 334 resolution when needed. Tools such as the issue tracker and the 335 working group wiki, which are available to every working group, may 336 be helpful here -- particularly if many issues come up, if issues are 337 often taking a long time to be resolved, or if the same issues tend 338 to come up repeatedly. 340 The issue tracker can be used to record not just the issues 341 themselves, but significant parts of the discussion on both sides, 342 helping to make it clearer what the resolution was and why, and 343 whether a particular request to re-open a closed issue really 344 involves new points or is just a re-hash. This is also a good time 345 to record implementation and interoperability information in the 346 working group wiki, along with any other information that will be 347 helpful to the community and the IESG when the document comes out of 348 the working group. 350 Discussions need to be steered, with a goal of avoiding unproductive, 351 circular discussions, re-hashing of old arguments, and tangential 352 discussions that go "off into the weeds". Discussions also often 353 need to be prodded. Lulls can be fine, but when it looks like 354 nothing is happening for a while, remind the participants of open 355 issues, ask for reviews of updated document versions or of recent 356 changes that don't seem to have been discussed. It's often useful to 357 make specific requests of participants off list, not just relying on 358 sending "please review" messages to the list. The goal here is to 359 ensure that rough consensus is reached on the document, covering as 360 much of the document as possible, and certainly covering the key 361 points. 363 Document Editors need to be prodded as well. We're all volunteers, 364 and many of us are working on a lot of things. A particular document 365 can fall off to the side for a long while. It's best to avoid the 366 trap of getting updates only before each IETF meeting, just in time 367 to beat the submission cutoff. If updates aren't posted fairly 368 promptly after a set of issues is resolved, ask the Editors when 369 they'll be able to get changes rolled into a new document version. 370 Check that the Editors are following working group consensus as they 371 make their updates. 373 Even with plenty of prodding and reminding and steering, it sometimes 374 happens that a document simply can't be finished and abandoning it 375 needs to be considered. Perhaps there's no longer the interest there 376 was at adoption. Perhaps the document has been overtaken by other 377 events. Or perhaps there's too much controversy over it, and rough 378 consensus just isn't going to happen. The Shepherd should consult 379 with the Chairs to decide whether the working group should stop work 380 on the document. 382 The Shepherd will know when the document is moving from this stage 383 into the next, and when she needs to shift the focus into preparation 384 for last call and for getting the document to the AD. 386 In summary, the tasks for the Shepherd at the Working Group Document 387 stage might be as follows: 389 1. Work with the Chairs to understand the desired mechanism for 390 managing discussions. 391 2. Watch the discussions as they unfold; call out and record 392 specific issues that come up. 393 3. Steer the discussion when necessary. 394 4. Prod the discussions when necessary. 395 5. Prod the Document Editors when necessary. 396 6. Use appropriate tools, such as issue trackers and wikis. 397 7. Determine when it's time to start wrapping things up and moving 398 to Working Group Last Call, and advise the chairs. 399 8. Alternatively, determine that it's not possible to move the 400 document forward, and the Chairs need to consider abandoning it. 402 3.3. Stage: Working Group Last Call 404 When any contentious issues have been resolved and the document has 405 had a good level of review, the Shepherd should start looking at when 406 it's time to wrap things up, have a last call within the working 407 group, and get the document ready to send to the Responsible AD. 408 What needs to be done now is largely the same as in the Working Group 409 Document stage, but with a particular aim of getting remaining issues 410 closed and making sure that discussions are tightly focused. Where 411 veering off to explore things that might be added to the document was 412 a fine thing to do in the earlier stages, this is the time to say 413 that the document is "feature complete", and to keep discussions 414 reined in. 416 Working Group Last Call is a recommended step, though not a required 417 one (it is not part of the formal process), and most working groups 418 do issue a formal "last call" before sending the document to the 419 Responsible AD. The Shepherd, in consultation with the chairs, can 420 take the responsibility of issuing that message and of analyzing 421 comments to determine whether things are ready to go ahead. 423 This is also the time to make sure that important reviews are done. 424 Ask for reviews from key working group contributors, and check 425 whether any external reviews are needed. External reviews might 426 include expert reviews for IANA registrations (some registrations 427 require early review on specific mailing lists), reviews of formal 428 specifications such as MIBs, XML, and ABNF, and reviews from experts 429 in other areas (does the document need to be checked by a web 430 services expert, a security expert, a DNS expert?). Some of this 431 will happen automatically later -- there will be a Security 432 Directorate review at some point, for example, and IANA will formally 433 kick off expert review during Last Call -- but it's easier on the 434 Document Editors and the working group if you know something is 435 particularly necessary and arrange for it sooner. The IANA folks are 436 willing to do an early review of the IANA actions at this stage, so 437 consider asking for that if the document has a large or unusually 438 involved set of IANA actions. 440 The shepherd writeup, which can be found in the IESG section of the 441 IETF web site [Writeup], is a good reference to the Shepherd for 442 making sure the necessary bits are being covered, so this is also a 443 good time to start the writeup. It will be finished later, when the 444 document is ready to be sent to the Responsible AD, but getting a 445 start now can be helpful, and will serve as a reminder to ask the 446 questions and request the reviews that will later be needed. 448 The tasks for the Shepherd at the Working Group Last Call stage might 449 be as follows: 451 1. Issue an official "Working Group Last Call" message on the list, 452 with a reasonable deadline given. 453 2. Closely watch the reviews and discussions at this stage, and make 454 sure they are focused on closing final issues and giving the 455 document final review. 456 3. Specifically ask (perhaps off list) for key reviews. 457 4. Begin preparing the shepherd writeup, and request any external 458 reviews that will be needed. 459 5. Analyze the results of Working Group Last Call and get final 460 updates from the Document Editors. 462 3.4. Stage: Shepherd Writeup Underway 464 Working Group Last Call is over, and the Shepherd and Chairs have 465 determined that any issues that came out of that have been adequately 466 resolved. It's time to finish up the shepherd writeup, dotting the 467 last of the "i"s and crossing the final "t"s. 469 Remember that the shepherd writeup serves two major purposes: 471 1. It ensures that some key items have been double checked. 472 2. It provides information to the IESG, which is useful during IESG 473 Evaluation. 475 For the first purpose, "yes" and "no" are reasonable answers to some 476 of the writeup questions. In particular, a number of the questions 477 ask if something has been checked, or it some abnormal situation 478 exists. "Yes" to confirm that the check has been made, or "no" to 479 state that the abnormal situation does not exist are fine responses. 480 Of course, if the answer to the first is "no" or to the second is 481 "yes", further explanation is necessary. In other words, "yes" could 482 be a reasonable answer by itself, but "no" would require more by way 483 of explanation... or vice versa. 485 But for the second purpose, providing useful information to the IESG, 486 yes/no responses are often of little or no use. Questions about the 487 working group process and discussions are especially looking for some 488 sort of narrative information. Don't just say that there was much 489 discussion that eventually reached consensus, or that there were a 490 number of controversial points that were resolved -- say something 491 about the discussion, talk a bit about the controversies. If there 492 were particular points that simply did not get any discussion but 493 probably should have, say that. 495 Knowing the trouble spots and the strong and weak points of the 496 discussion and consensus will allow the IESG to properly evaluate the 497 document. That can avoid the IESG's revisiting issues that were 498 already done to death in the working group. It's common to have 499 DISCUSS positions in which ADs are questioning a point that the 500 working group discussed at length, and a brief explanation in the 501 writeup could have avoided having it come up again then. 503 When the Shepherd has the writeup done, a non-chair Shepherd should 504 consult with the Chairs to make sure they're happy with it and agree 505 with what's in it. The Chairs will then need to make some 506 datatracker updates that only they have authorization for: they will 507 upload the writeup to the tracker and change the document state. 509 Changing the document's working group state to "Submitted to IESG for 510 Publication" will trigger the necessary email messages and IESG state 511 changes, and will get the document into IESG "Publication Requested" 512 state, from which the Responsible AD will begin her processing of the 513 document. And as RFC 4858 says, the Shepherd should also email the 514 writeup to the working group's mailing list, so the working group is 515 aware of it. The writeup will be public anyway, because it will be 516 in the datatracker, so it can only help the open process to make it 517 more visible to the working group whose work it reflects. 519 See also [RFC4858], Section 3.1, but note that the writeup template 520 has changed significantly since the version in that document. The 521 current writeup is in the IESG section of the IETF web site 522 [Writeup]. 524 The tasks at the Shepherd Writeup Underway stage might be as follows: 526 1. Shepherd: Complete the shepherd writeup and send it to the Chairs 527 for approval. 528 2. Chairs: Work with the Shepherd to finalize the writeup. 529 3. Chairs: Put the writeup into the datatracker, and change the 530 tracker document state to the appropriate one for requesting 531 publication. 532 4. Shepherd: Send the writeup to the working group mailing list and 533 inform the working group that publication has been requested. 535 3.5. Stage: AD Review 537 The next stage in the process is up to the Responsible Area Director, 538 and the Document Shepherd has but one easy task: help make this stage 539 as short as possible. The Responsible AD or the IESG Secretary will 540 do some document state changes in the datatracker (to Publication 541 Requested and then to AD Review), and the AD will review the document 542 and either request IETF Last Call or respond to the authors (and, we 543 hope, to the Shepherd as well; here's where it was useful to have put 544 the Shepherd's email address in the tracker) with review comments and 545 suggested changes. In the latter case, the document's state might 546 change to "AD Review, Revised I-D Needed". 548 The Shepherd needs to watch for the key state changes and the AD's 549 review. If the review doesn't happen in a reasonable time -- 550 allowing for a busy AD's schedule and remembering that the document 551 you're shepherding isn't the only one on the AD's docket -- send a 552 reminder... perhaps as a question, "How is the review on draft-ietf- 553 frobozz-xyzzy coming?" Use your judgment to decide how long to wait, 554 but most ADs will appreciate a reminder here and there as long as 555 it's not at the level of "pestering". 557 Once the review comes in, make sure the Document Editors are on top 558 of it and respond in a timely manner. Make sure that the working 559 group is consulted on issues brought up in the review that are 560 significant enough to require the working group's engagement in the 561 response. Editorial tweaks can arguably be handled by the editors 562 alone at this point, and changes to the protocol clearly need to go 563 back to the working group, but many issues fall in between, and good 564 judgment is important. The Chairs should be involved in deciding 565 where the line is drawn. 567 Many documents spend *months* in AD Review state, largely because of 568 lack of good shepherding. It may look like there's only one major 569 task here, but it's an important one. Please don't give it short 570 shrift. 572 See also [RFC4858], Section 3.2. 574 The tasks for the Shepherd at the AD Review stage might be as 575 follows: 577 1. Make sure the AD reviews the document in a timely manner, and 578 send occasional reminders as needed. 579 2. Make sure the Document Editors respond to the review in a timely 580 manner, and poke them as well, as needed. 581 3. Keep the dialogue going between the Responsible AD and the 582 editors until all issues have been dealt with and the document is 583 ready for the next stage. 584 4. See to it that issues are brought back before the working group 585 if they are significant enough to require it. 587 3.6. Stage: IETF Last Call 588 Once the Responsible AD is satisfied that the document is ready to 589 move ahead, she will put it in Last Call Requested state. That 590 prompts the IESG Secretary to send out the Last Call announcement and 591 to put the document into "In Last Call". 593 The Shepherd's job in the IETF Last Call stage is very similar to 594 what's needed in AD Review. Start by watching for last-call 595 comments, including various special reviews. Reviews will come in 596 from the Security Directorate and the General Area Review Team 597 (GenART), and some may also come from other review teams and 598 directorates. Reviews might also be coming in at this stage, if they 599 haven't already, that were specifically requested by the Shepherd 600 (see the Working Group Last Call stage in Section 3.3). 602 The Shepherd needs to make sure all of those reviews are addressed by 603 the document editors, and that the specifically requested reviews get 604 done. "Addressed" doesn't mean that every change asked for in every 605 last-call comment needs to be made. Sometimes, a reasonable response 606 is to say that the working group discussed the point, and the 607 document correctly reflects its consensus -- that is, the working 608 group disagrees with the last-call comment. At other times, it's 609 reasonable to disagree with the reviewer and look for any other 610 support for the reviewer's position. Rough consensus can be a tricky 611 thing, but the bottom line is that all comments need at least be 612 considered. Directorate and review-team reviews, in particular, 613 require acknowledgment and response (though they, too, can be 614 disagreed with). 616 During Last Call, IANA will review the document's IANA 617 Considerations, will respond with their summary of what they think 618 needs to be done by IANA after the document is approved, and will ask 619 any questions they have. The Shepherd should watch for this review 620 and make sure that the actions IANA proposes are correct and that any 621 questions they have are answered. At this point, IANA will also 622 contact any Designated Experts required to formally approve any 623 registrations, so it will help if the shepherd has done the necessary 624 preparatory work (see Section 3.3). See also [RFC4858], Section 4. 626 Different Responsible ADs will have different preferences for whether 627 documents in IETF Last Call should be updated while they're still in 628 that state. The Shepherd should check with the AD and advise the 629 Document Editors. Sometimes it's best to keep a stable version 630 throughout last-call review; other times it's better to get changes 631 posted quickly, so the same issues aren't brought up by multiple 632 reviewers. Work with the AD and the editors to handle this. 634 The tasks for the Shepherd at the IETF Last Call stage might be as 635 follows: 637 1. Monitor the last-call comments, and make sure that specifically 638 requested reviews arrive. 639 2. Make sure the Document Editors respond to all reviews and 640 comments in a timely manner. 642 3. Keep the dialogue going between the community and the editors 643 until all issues have been dealt with. 644 4. See to it that issues are brought back before the working group 645 if they are significant enough to require it. 647 3.7. Stage: Waiting for AD Go-Ahead 649 When Last Call completes, the tracker state for the document will 650 automatically go to "Waiting for AD Go-Ahead". This is the 651 Shepherd's signal to re-check the comments from last call, to make 652 sure an updated I-D is posted that is ready for IESG Evaluation, and 653 to let the Responsible AD know when everything is set. The AD will 654 be watching for this as well, but, as in the other stages, it's the 655 Shepherd's responsibility to keep an eye on things and make sure 656 what's needed gets done. 658 This is also a good time to remember that the document shepherd 659 writeup is not static. If significant time has elapsed, significant 660 discussion has happened, or significant changes have been made, it's 661 a good idea to work with the Chairs to update the shepherd writeup in 662 the datatracker, making sure that delays, discussions, and major 663 changes are outlined in the writeup for the IESG. 665 The tasks for the Shepherd at the Waiting for AD Go-Ahead stage might 666 be as follows: 668 1. Make sure a new I-D is posted with the latest changes, and inform 669 the Responsible AD that all changes have been incorporated and 670 that the document is ready for IESG Evaluation, or... 671 2. ...inform the Responsible AD that no changes are required and 672 that the document is ready for IESG Evaluation. 673 3. Update the Shepherd writeup if anything has come up during Last 674 Call that the IESG should know about. The Chairs will update the 675 writeup in the datatracker. 677 3.8. Stage: IESG Evaluation 679 As the ADs do their reviews they will record ballot positions on the 680 document. Ballot positions can be one of "Yes", "No Objection", 681 "Discuss", and "Abstain" (there's also "Recuse" for cases when the AD 682 has a conflict of interest with the document, if, for example, the AD 683 is one of the authors/editors). Any of these ballot positions can be 684 accompanied by non-blocking review comments, and "Discuss" also comes 685 with blocking comments in addition -- these must be resolved to the 686 satisfaction of the Discussing AD before the document can be approved 687 by by the IESG. The document will be scheduled for a bi-weekly 688 "telechat" (at the time of this writing they're on Thursdays), and it 689 will be approved then or left in one of several follow-up states. 691 The IESG Evaluation period is normally somewhere between one and 692 three weeks, though it can be as little as a few days in unusual 693 circumstances. Be aware, though, that there's usually a burst of 694 review activity in the final few days before the telechat, and expect 695 most reviews to come in then. 697 The IESG Evaluation comments and DISCUSS positions will be copied to 698 the Document Shepherd (again, it was important to have put the 699 Shepherd's email address in the tracker), and the Shepherd should be 700 watching for them and making sure that the Document Editors respond 701 promptly -- at this stage, quick turnaround is most important. 702 Sometimes the Shepherd or Chairs might respond to AD questions and 703 comments themselves, and sometimes they might leave it to the 704 editors. The process works best when everyone engages, with the goal 705 of resolving the issues brought up by the ADs as efficiently as 706 possible. 708 A word about DISCUSS positions: Many Document Editors treat these as 709 adversarial situations created by aggressive ADs, but that's 710 generally not the intent. First, many DISCUSSes are resolved quickly 711 and easily by a round of email with the Discussing AD, and that's as 712 it should be: the point is that the AD has something to "discuss" 713 with those responsible for the document before she can agree to the 714 document's approval. Second, many DISCUSSes that do take more 715 effort, often significant back and forth with the Discussing AD and 716 other IESG members, result in a better document, having cleared up 717 some significant confusion or having closed a hole in the 718 specification that was missed at earlier stages. Please try to treat 719 the situation as one in which everyone is looking to make the 720 document better. 722 Most often, ADs who record DISCUSS positions (and review comments) 723 are quite responsive, and will work with the Editors and Shepherd to 724 get everything resolved. Sometimes, though, a busy AD can find 725 herself lacking the time to respond. The Shepherd should keep the 726 ADs honest, pushing for quick responses. In earlier stages, too- 727 frequent reminders might be considered unreasonable, but at this 728 stage discussion should be fairly brisk, and a delay of more than a 729 couple of days should be unusual, on either side. 731 Non-blocking IESG Evaluation comments should be treated as IETF Last 732 Call comments are: the Document Editors should respond to them and do 733 their best to address them, but failure to come to agreement on them 734 will not block the document's progress. 736 And, as at other stages, the Shepherd should work with the Chairs to 737 ensure that any changes of significance are brought back to the 738 working group for their review before the final approval notice goes 739 out. 741 The IESG web site has more details about IESG ballot positions 742 [Ballot] and about IESG DISCUSS ballots in particular [Discuss]. And 743 see also [RFC4858], Section 3.3. 745 The tasks for the Shepherd at the IESG Evaluation stage might be as 746 follows: 748 1. Keep track of the DISCUSS positions and review comments by the 749 IESG. 750 2. Make sure all comments are addressed, and help the discussions of 751 DISCUSS positions reach closure. 752 3. Keep both the Document Editors and the Discussing AD engaged in 753 the resolution of the issues. 754 4. See to it that issues are brought back before the working group 755 if they are significant enough to require it. 757 3.9. Stage: Approved by the IESG 759 Once the document has been on a telechat, any necessary revised 760 versions have been posted, and all DISCUSS positions are "cleared", 761 the Responsible AD (or the IESG Secretary) will put the document into 762 the "Approved, Announcement to be Sent" state. If there's any 763 follow-up that needs to be done, it will be held with a sub-state 764 (usually "Point Raised, Writeup Needed"), and the Shepherd should 765 make sure that whatever final checks are needed get done, and that 766 the Responsible AD clears the sub-state and informs the IESG 767 Secretary. 769 At this stage, it's usually a matter of making sure that the latest 770 version of the document adequately addresses the non-blocking 771 comments by the ADs, and that any necessary RFC Editor notes are 772 entered. The Shepherd should work with the Responsible AD to 773 understand what still needs to be done, and to make sure it happens. 775 The tasks for the Shepherd at the Approved by the IESG stage might be 776 as follows: 778 1. Work with the Responsible AD to understand what still needs to be 779 addressed. 780 2. Double-check the IANA actions and the RFC Editor notes, and 781 follow up on any errors or omissions. 782 3. Make sure the Document Editors and the Responsible AD move the 783 document to the final Approved state. 785 3.10. Stage: In RFC Editor Queue 787 Shortly after the approval announcement is sent out, the document 788 will go into the RFC Editor queue, and the Shepherd will start seeing 789 it pass through a number of RFC Editor states. For most of this, the 790 Shepherd need do nothing, and is just waiting for the AUTH48 state. 791 This will usually take between a few weeks and a few months, 792 depending upon many factors, but it can be held up indefinitely by 793 normative references to documents that are not yet ready for 794 publication. Be aware of what the document is waiting for, and 795 otherwise just wait. If anything looks odd, ask the Responsible AD 796 to check. 798 The tasks for the Shepherd at the In RFC Editor Queue stage might be 799 as follows: 801 1. Sip tea or drink beer or wine, and wait for AUTH48. 802 2. Talk to the Responsible AD if something doesn't look right. 804 3.11. Stage: AUTH48 806 AUTH48 is an RFC Editor state that occurs when the RFC Editors have 807 done their final edits on the document before publication. It's 808 meant to represent a 48-hour period in which the AUTHors can review 809 what the RFC Editor has changed, have a final look at the document, 810 and make sure it's ready to go. 812 AUTH48 is a critical document state; do not downplay its importance. 813 At this stage, the Shepherd should re-review the document, paying 814 special attention to recent changes. The Document Editors must do 815 the same, and a response from every Author/Editor listed at the top 816 of the document is required before the RFC Editor will finish the 817 publication process. The Document Shepherd needs to make sure that 818 the Editors all respond, and should take the lead in prompting them 819 early and frequently. Remember that "AUTH48" is meant to refer to 48 820 hours, not 48 days. Don't let this drag on. 822 The RFC Editor will often have questions that the Authors/Editors 823 need to answer. The Document Editors often have minor changes to 824 insert at this point. The Shepherd should consider those answers, 825 those changes, and the changes the RFC Editor has made leading into 826 AUTH48, and assess, in consultation with the Chairs and the 827 Responsible AD, whether any changes need to be passed back to the 828 working group -- remember that the document has been approved by 829 rough consensus of the working group, and then of the IETF as a 830 whole, and the final, published version must continue to reflect that 831 consensus. 833 It's unusual for there to be significant controversy at this stage, 834 but it's been known to happen. Sometimes a change or a question by 835 the RFC Editor will raise a question with the Document Editors that 836 had not come up before. Sometimes, the right answer to one of those 837 questions will be more than just editorial, and sometimes it will 838 involve a significant technical decision. Decisions of that nature 839 should not be made by the Document Editors alone, and the Shepherd 840 should arrange with the Chairs to have those issues discussed by the 841 working group. 843 Most of the time, though, this stage will run smoothly, the Document 844 Editors will respond to the AUTH48 messages with a minimum of 845 prodding, and the RFC Editor will announce their happiness and 846 proceed with the publication process. 848 See also Section 5 of [RFC4858]. 850 The tasks for the Shepherd at the AUTH48 stage might be as follows: 852 1. Monitor the AUTH48 process and make sure all questions are 853 answered and all Authors/Editors respond as needed. 854 2. Assess whether any issues that come up are significant enough to 855 need review by the working group. 857 3.12. Stage: Published 859 We're done. The RFC Editor has published the document, and the RFC 860 announcement has been made. Many thanks to the Shepherd for having 861 seen it through and for helping to assure a high quality document. 863 4. Some Final Notes 865 We have outlined a Document Shepherding Function, above, in a lot of 866 detail, so let's put the executive summary back here: 868 What it all boils down to is setting up one person who takes 869 responsibility for following the progress of a document from Call for 870 Adoption through Publication, staying actively involved with managing 871 the discussion and issue resolution at every stage, and making sure 872 the necessary participants are responsive and that things don't 873 languish from inattention. 875 And again, Working Group Chairs may delegate all or part of this 876 function to a non-chair participant, or retain all responsibility for 877 it themselves. In the latter case, what is described here is nothing 878 different to what should be happening already. Setting it out as 879 clear tasks and a set of stages in the document's lifecycle will make 880 it easier to recognize what needs to be done when, and to handle 881 delegation when the Chairs choose to delegate. 883 5. Security Considerations 885 This document describes IETF process, and is entirely unrelated to 886 security in any way. 888 6. IANA Considerations 890 No IANA actions are requested by this document, and the RFC Editor is 891 asked to remove this section before publication. 893 7. References 895 7.1. Normative References 897 [RFC2418] Bradner, S., "IETF Working Group Guidelines and 898 Procedures", BCP 25, RFC 2418, September 1998. 900 [RFC4858] Levkowetz, H., Meyer, D., Eggert, L. and A. Mankin, 901 "Document Shepherding from Working Group Last Call to 902 Publication", RFC 4858, May 2007. 904 7.2. Informative References 906 [Ballot] IESG, , "IESG Ballot Procedures", May 2009, . 909 [Discuss] IESG, , "DISCUSS Criteria in IESG Review", July 2007, 910 . 913 [Stmt] IESG, , "IESG Statement on Document Shepherds", October 914 2010, . 917 [Writeup] IESG, , "Working Group Submission Writeup", February 2012, 918 . 920 Author's Address 922 Barry Leiba 923 Huawei Technologies 925 Phone: +1 646 827 0648 926 Email: barryleiba@computer.org 927 URI: http://internetmessagingtechnology.org/