idnits 2.17.1 draft-leiba-extended-doc-shepherd-03.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: ---------------------------------------------------------------------------- == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 2) being 60 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 27 instances of too long lines in the document, the longest one being 12 characters in excess of 72. -- 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 (May 16, 2014) is 3634 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- No issues found here. Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 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) May 16, 2014 5 Intended status: Informational 6 Expires: November 15, 2014 8 Process Experiment: Document Shepherding Throughout a Document's 9 Lifecycle 10 draft-leiba-extended-doc-shepherd-03 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 at the 17 time that a working group begins discussing a version of the idea 18 that's been posted as an individual draft. This document extends RFC 19 4858, discussing the potential for extending shepherding and what 20 tasks might be involved throughout a working group document's 21 lifecycle, from start to finish. 23 Status of this Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on November 15, 2014. 40 Copyright Notice 42 Copyright (c) 2014 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents (http://trustee.ietf.org/ 47 license-info) in effect on the date of publication of this document. 48 Please review these documents carefully, as they describe your rights 49 and restrictions with respect to this document. Code Components 50 extracted from this document must include Simplified BSD License text 51 as described in Section 4.e of the Trust Legal Provisions and are 52 provided without warranty as described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 57 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . . 3 58 2. The Document Shepherd as a "Function" . . . . . . . . . . . . 3 59 3. Stages in a Document's Lifecycle . . . . . . . . . . . . . . . 4 60 3.1. Preparing for Adoption and Shepherding . . . . . . . . . . . 5 61 3.2. Stage: Call for Adoption . . . . . . . . . . . . . . . . . . 7 62 3.3. Stage: Working Group Document . . . . . . . . . . . . . . . 8 63 3.4. Stage: Working Group Last Call . . . . . . . . . . . . . . . 10 64 3.5. Stage: Shepherd Writeup Underway . . . . . . . . . . . . . . 11 65 3.6. Stage: AD Evaluation . . . . . . . . . . . . . . . . . . . . 12 66 3.7. Stage: IETF Last Call . . . . . . . . . . . . . . . . . . . 13 67 3.8. Stage: Waiting for AD Go-Ahead . . . . . . . . . . . . . . . 15 68 3.9. Stage: IESG Evaluation . . . . . . . . . . . . . . . . . . . 15 69 3.10. Stage: Approved by the IESG . . . . . . . . . . . . . . . . 17 70 3.11. Stage: In RFC Editor Queue . . . . . . . . . . . . . . . . . 18 71 3.12. Stage: AUTH48 . . . . . . . . . . . . . . . . . . . . . . . 18 72 3.13. Stage: Published . . . . . . . . . . . . . . . . . . . . . . 19 73 4. Some Final Notes . . . . . . . . . . . . . . . . . . . . . . . 19 74 5. Security Considerations . . . . . . . . . . . . . . . . . . . 20 75 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 76 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 20 77 7.1. Normative References . . . . . . . . . . . . . . . . . . . . 20 78 7.2. Informative References . . . . . . . . . . . . . . . . . . . 20 79 Appendix A. Lifecycle Stages and Corresponding Document States . . 21 80 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 21 82 1. Introduction 84 RFC 4858 talks about "Document Shepherding from Working Group Last 85 Call to Publication" [RFC4858]. There's a significant part of a 86 document's life that happens before Working Group Last Call, 87 starting, really, at the time that a working group begins discussing 88 a version of the idea that's been posted as an individual draft. It 89 seems reasonable and helpful in many situations to begin shepherding 90 when there's a call for adoption as a working group document. This 91 document extends RFC 4858, describing how that extended shepherding 92 function might work and what tasks might be involved throughout the 93 document's lifecycle, and suggesting how Working Group Chairs might 94 choose to implement extended shepherding. 96 It is very common to see documents progress far too slowly, sometimes 97 languishing for many months and even for years due to neglect. 98 Sometimes a working group will intentionally set a document aside, 99 put it on a back burner while it works on more pressing things. But 100 it's often not intentional: the document sits around because of lack 101 of follow-through, waking up occasionally when someone realizes that 102 the last version has expired and an IETF meeting is coming up soon. 104 We would really prefer to process documents efficiently, ensuring 105 that whatever happens is intentional: that documents are set aside 106 only when it makes sense to do so, and that active documents move 107 forward in the process, with someone responsible for making sure that 108 happens. 110 This document suggests specific tasks a Working Group Chair should be 111 doing or delegating in order to maintain forward progress, 112 accountability, and quality control on a working group document. It 113 adds to what's in RFC 4858, intending to extend it, not replace it. 114 Major extensions involve assigning a Shepherd and defining specific 115 tasks earlier in a document's life, and possibly delegating Document 116 Shepherd tasks to a Shepherd who is neither a Chair nor the Working 117 Group Secretary (consistent with the IESG Statement on Document 118 Shepherds [Stmt]). 120 The summaries in each section of the tasks expected at that stage in 121 the document's lifecycle can make this an easy reference and 122 checklist for Working Group Chairs and Document Shepherds. 124 The specific mechanism suggested here will not be suitable for all 125 working groups, all management models, and all situations. While 126 it's a good idea to have the stages laid out and the tasks at each 127 stage identified, not all working groups will benefit from having a 128 single document shepherd designated at the start. Indeed, when a 129 document is legitimately years in the making, personnel may come and 130 go and changes will be necessary. A particular working group might 131 be working only on one document at a time, with all tasks shared 132 between the chairs. 134 For these and other reasons, the suggestions herein are meant to be 135 adapted to specific situations to retain the underlying objective of 136 maintaining progress through active involvement. 138 1.1. Notational Conventions 140 It is important to note that this document makes no formal process 141 changes and there is no normative language here. 143 Initial Capitals are used in some terms, such as "Document Shepherd", 144 to indicate that those terms represent specific roles in the 145 management model that is described. 147 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. Of course, either way, the 189 Chair has to answer to the working group and the responsible AD if 190 the work lags. 192 3. Stages in a Document's Lifecycle 194 From the time a working group is asked to take on a document as one 195 of its work items, the document will go through a number of stages, 196 most of which correspond closely to working group document states 197 [RFC6174] or IESG document states in the datatracker (see Appendix 198 Appendix A for a mapping): 200 1. Call for Adoption 202 2. Working Group Document 204 3. Working Group Last Call 206 4. Shepherd Writeup Underway 207 5. AD Evaluation 209 6. IETF Last Call 211 7. Waiting for AD Go-Ahead 213 8. IESG Evaluation 215 9. Approved by the IESG 217 10. In RFC Editor Queue 219 11. AUTH48 221 12. Published 223 Through most of those stages steps will have to be taken, tasks will 224 need to be performed, to make sure the document moves forward, that 225 consensus is reached, that the right reviews are done, that updates 226 are made, that consensus still holds after significant changes, and 227 so on. The Document Shepherd Function comprises that set of tasks, 228 and the document shepherd works with the Chairs as needed, and to 229 have the datatracker state changes recorded. 231 The following sections will discuss some of the tasks needed at each 232 stage, and will suggest how Working Group Chairs might handle those 233 tasks and their delegation -- how the Document Shepherd Function 234 might work. The details will vary, depending upon how each working 235 group is managed, but what follows should be a good example, and will 236 provide a basis for adaptation. And see also [RFC4858], Section 3. 238 3.1. Preparing for Adoption and Shepherding 240 At the point that the working group begins considering adoption of a 241 document, the Working Group Chairs have some decisions to make, 242 beginning with confirming that the document is within the scope of 243 the working group's charter. This is the time to choose a 244 Responsible Chair for the document, much as it will eventually have a 245 Responsible Area Director later in its life. The Responsible Chair 246 will be the one who oversees the Document Shepherd Function and has 247 primary responsibility for making sure that everything gets done. 249 The Responsible Chair should then (perhaps in consultation with the 250 other Chair(s), depending upon the Chairs' agreement about division 251 of work) decide how much of the Document Shepherd Function to handle 252 herself, and which pieces, if any, to delegate. Examples might be as 253 follows: 255 o The Responsible Chair will be the sole Document Shepherd. 257 o The Responsible Chair will be the Document Shepherd through the 258 end of the Working Group Document stage, and will appoint a non- 259 chair Shepherd during that stage to handle subsequent shepherding 260 tasks (similar to what's set out in RFC 4858). 262 o The Responsible Chair will appoint a non-chair Shepherd to handle 263 the early shepherding tasks, and the Responsible Chair will take 264 over the Document Shepherd tasks for Working Group Last Call and 265 beyond (the converse of the previous example). 267 o The Responsible Chair will appoint a non-chair Shepherd to handle 268 all shepherding tasks from start to end. The delegate will work 269 closely with the Responsible Chair, heavily supervised (perhaps 270 this is a training situation). 272 o The Responsible Chair will appoint a non-chair Shepherd to handle 273 all shepherding tasks from start to end. The delegate will report 274 to the Responsible Chair, and will be supervised at certain key 275 points. 277 o The Responsible Chair will appoint a non-chair Shepherd to handle 278 all shepherding tasks autonomously (perhaps for a very experienced 279 Shepherd, well trusted by the Chairs). 281 And so on... there may be many combinations, many levels of 282 supervision vs autonomy, many ways to divide the work. It's also 283 possible to delegate to more than one non-chair Shepherd at different 284 stages. The Chairs need to judge the extent to which continuity and 285 centralized responsibility are important for the document in question 286 and the management style of the chairs, and whether making it one 287 other person (supervised by one Responsible Chair) is best. 289 In choosing Shepherds, the Chairs should be alert to real and 290 perceived conflicts of interest, and should make the appointment of 291 Shepherds and the work they do as open a process as is reasonable 292 within the management of the working group. Chairs need to be 293 comfortable with the Shepherds they appoint; at the same time, 294 appointing the same shepherds for every document might not be the 295 best choice. Consider balance, and use this as an opportunity to 296 distribute responsibility. 298 Some Chairs may prefer to handle all tasks themselves, because, after 299 all, they remain formally responsible for their successful 300 completion. Yet there can be a lot gained by delegating much of the 301 work. Delegating work and giving a degree of responsibility to 302 relatively more junior participants gets people more closely engaged 303 with the working group and with the IETF. Giving significant 304 responsibility can be an excellent training exercise, preparing 305 participants to take on future roles as Working Group Chairs. And in 306 a busy working group, offloading work from the Chairs to senior, 307 experienced people can prevent the Chairs from being overcommitted, 308 enabling the work to move forward much more efficiently. 310 This document will often talk about the Shepherd making certain 311 decisions and judgments, such as judging consensus. It's important 312 to keep in mind that when the Shepherd is not one of the Chairs (when 313 the function is delegated), these judgments take the form of advice 314 to the Chairs, and that the Chairs have the formal responsibility for 315 making process-related decisions and for judging consensus. Any 316 appeals will always be made with respect to decisions by the Chairs. 318 And, of course, a non-chair Shepherd can and should consult with the 319 Responsible Chair whenever she feels the need, and certainly whenever 320 issues arise of which the Chairs should be aware, or about which the 321 Shepherd needs advice or other help. 323 Tasks that need to be taken in preparation might be as follows: 325 1. Chairs: Confirm that the document falls within the working 326 group's charter. 327 2. Chairs: Select a Responsible Chair to handle the document. 328 3. Responsible Chair: Decide on a work/delegation plan. 329 4. Responsible Chair: Possibly appoint a non-chair Shepherd; else 330 the Responsible Chair becomes the Shepherd. 332 3.2. Stage: Call for Adoption 334 Once it is determined who will handle the Document Shepherd tasks, 335 the Shepherd needs to do the actual adoption process. The details 336 will vary based on how the particular working group is run, but a 337 typical process will start with posting a call for adoption to the 338 working group mailing list, pointing to the individual draft that's 339 being considered. There'll be a comment period for adoption 340 discussion, after which the Shepherd will, based on working group 341 discussion, give a recommended judgment to the Chairs. 343 Often, working groups are chartered with a startup document list, and 344 specific calls for adoption are not needed. In those cases, the 345 Shepherd will not need to handle a call and comment period, and can 346 begin with the next paragraph. 348 Assuming that the document was adopted, the Chairs will appoint one 349 or more Editors for the working group version of the document (these 350 are often, but not always, the same people who wrote the individual 351 version, and the Chairs should put some thought into who the right 352 Editors should be), and will handle the datatracker updates (for 353 which Chair access is required). The Chairs should not forget to 354 record the name and email address of the Document Shepherd in the 355 tracker -- this will ensure that the Shepherd is copied on necessary 356 email later. 358 In summary, the tasks at the Call for Adoption stage might be as 359 follows: 361 1. Shepherd: Make the call for adoption; set deadlines and schedule. 362 2. Shepherd: Communicate the result to the Chairs; 363 3. Chairs: Announce the result and appoint Document Editor(s) for 364 the WG document. 365 4. Chairs: Update the datatracker; approve -00 version submission. 367 3.3. Stage: Working Group Document 369 Once a -00 version is posted, the Shepherd's primary task is to keep 370 the document moving forward: keeping discussion going, making sure 371 issues are tracked and document updates are posted, and helping 372 things toward consensus. Let's not downplay the importance of active 373 management here: this is where things so often fall short, what 374 causes documents to take *years* to complete. The Shepherd should 375 not rush discussions that are useful, but the Shepherd should make 376 sure that things don't get lost in the forest either. 378 The Chairs will decide how the working group should be managed, and 379 any non-chair Shepherd should be working with the Chairs at this 380 stage, communicating any difficulties and getting help with issue 381 resolution when needed. Tools such as the issue tracker and the 382 working group wiki, which are available to every working group, may 383 be helpful here -- particularly if many issues come up, if issues are 384 often taking a long time to be resolved, or if the same issues tend 385 to come up repeatedly. 387 The issue tracker can be used to record not just the issues 388 themselves, but significant parts of the discussion on both sides, 389 helping to make it clearer what the resolution was and why, and 390 whether a particular request to re-open a closed issue really 391 involves new points or is just a re-hash. This is also a good time 392 to record implementation and interoperability information in the 393 working group wiki, along with any other information that will be 394 helpful to the community and the IESG when the document comes out of 395 the working group. 397 When implementations are proceeding in parallel with document 398 development, it is sometimes useful to get early allocation of 399 protocol parameters and code points [RFC7120]. The Shepherd should 400 watch for those situations and raise the issue with the working 401 group, bringing the request to the Chairs and responsible AD if it's 402 decided that early allocation is needed. 404 Discussions need to be steered, with a goal of avoiding unproductive, 405 circular discussions, re-hashing of old arguments, and tangential 406 discussions that go "off into the weeds". Discussions also often 407 need to be prodded. Lulls can be fine, but when it looks like 408 nothing is happening for a while, remind the participants of open 409 issues, ask for reviews of updated document versions or of recent 410 changes that don't seem to have been discussed. It's often useful to 411 make specific requests of participants off list, not just relying on 412 sending "please review" messages to the list. The goal here is to 413 ensure that rough consensus is reached on the document, covering as 414 much of the document as possible, and certainly covering the key 415 points. See [I-D.resnick-on-consensus] for a detailed discussion of 416 rough consensus in the IETF. 418 Document Editors need to be prodded as well. We're all volunteers, 419 and many of us are working on a lot of things. A particular document 420 can fall off to the side for a long while. It's best to avoid the 421 trap of getting updates only before each IETF meeting, just in time 422 to beat the submission cutoff. If updates aren't posted fairly 423 promptly after a set of issues is resolved, ask the Editors when 424 they'll be able to get changes rolled into a new document version. 425 Check that the Editors are following working group consensus as they 426 make their updates. 428 Even with plenty of prodding and reminding and steering, it sometimes 429 happens that a document simply can't be finished and abandoning it 430 needs to be considered. Perhaps there's no longer the interest there 431 was at adoption. Perhaps the document has been overtaken by other 432 events. Or perhaps there's too much controversy over it, and rough 433 consensus just isn't going to happen. The Shepherd should consult 434 with the Chairs to decide whether the working group should stop work 435 on the document. 437 The Shepherd will know when the document is moving from this stage 438 into the next, and when she needs to shift the focus into preparation 439 for last call and for getting the document to the AD. 441 In summary, the tasks for the Shepherd at the Working Group Document 442 stage might be as follows: 444 1. Work with the Chairs to understand the desired mechanism for 445 managing discussions. 446 2. Watch the discussions as they unfold; call out and record 447 specific issues that come up. 448 3. Steer the discussion when necessary. 449 4. Prod the discussions when necessary. 450 5. Prod the Document Editors when necessary. 451 6. Use appropriate tools, such as issue trackers and wikis. 452 7. Consider early IANA allocation and bring it up for discussion if 453 appropriate. 454 8. Determine when it's time to start wrapping things up and moving 455 to Working Group Last Call, and advise the chairs. 457 9. Alternatively, determine that it's not possible to move the 458 document forward, and the Chairs need to consider abandoning it. 460 3.4. Stage: Working Group Last Call 462 When any contentious issues have been resolved and the document has 463 had a good level of review, the Shepherd should start looking at when 464 it's time to wrap things up, have a last call within the working 465 group, and get the document ready to send to the Responsible AD. 466 What needs to be done now is largely the same as in the Working Group 467 Document stage, but with a particular aim of getting remaining issues 468 closed and making sure that discussions are tightly focused. Where 469 veering off to explore things that might be added to the document was 470 a fine thing to do in the earlier stages, this is the time to say 471 that the document is "feature complete", and to keep discussions 472 reined in. 474 Working Group Last Call is a recommended step, though not a required 475 one (it is not part of the formal process), and most working groups 476 do issue a formal "last call" before sending the document to the 477 Responsible AD. The Shepherd, in consultation with the chairs, can 478 take the responsibility of issuing that message and of analyzing 479 comments to determine whether things are ready to go ahead. 481 This is also the time to make sure that important reviews are done. 482 Ask for reviews from key working group contributors, and check 483 whether any external reviews are needed. External reviews might 484 include expert reviews for IANA registrations (some registrations 485 require early review on specific mailing lists), reviews of formal 486 specifications such as MIBs, XML, and ABNF, and reviews from experts 487 in other areas (does the document need to be checked by a web 488 services expert, a security expert, a DNS expert?). Some of this 489 will happen automatically later -- there will be a Security 490 Directorate review at some point, for example, and IANA will formally 491 kick off expert review during Last Call -- but it's easier on the 492 Document Editors and the working group if you know something is 493 particularly necessary and arrange for it sooner. The IANA folks are 494 willing to do an early review of the IANA actions at this stage, so 495 consider asking for that if the document has a large or unusually 496 involved set of IANA actions. 498 The shepherd writeup, which can be found in the IESG section of the 499 IETF web site [Writeup], is a good reference for the Shepherd for 500 making sure the necessary bits are being covered, so this is also a 501 good time to start the writeup. It will be finished later, when the 502 document is ready to be sent to the Responsible AD, but getting a 503 start now can be helpful, and will serve as a reminder to ask the 504 questions and request the reviews that will later be needed. 506 The tasks for the Shepherd at the Working Group Last Call stage might 507 be as follows: 509 1. Issue an official "Working Group Last Call" message on the list, 510 with a reasonable deadline given. 512 2. Closely watch the reviews and discussions at this stage, and make 513 sure they are focused on closing final issues and giving the 514 document final review. 515 3. Specifically ask (perhaps off list) for key reviews. 516 4. Begin preparing the shepherd writeup, and request any external 517 reviews that will be needed. 518 5. Analyze the results of Working Group Last Call and get final 519 updates from the Document Editors. 521 3.5. Stage: Shepherd Writeup Underway 523 Working Group Last Call is over, and the Shepherd and Chairs have 524 determined that any issues that came out of that have been adequately 525 resolved. It's time to finish up the shepherd writeup, dotting the 526 last of the "i"s and crossing the final "t"s. 528 Remember that the shepherd writeup serves two major purposes: 530 1. It ensures that some key items have been double checked. 531 2. It provides information to the IESG, which is useful during IESG 532 Evaluation. 534 For the first purpose, "yes" and "no" are reasonable answers to some 535 of the writeup questions. In particular, a number of the questions 536 ask if something has been checked, or it some abnormal situation 537 exists. "Yes" to confirm that the check has been made, or "no" to 538 state that the abnormal situation does not exist are fine responses. 539 Of course, if the answer to the first is "no" or to the second is 540 "yes", further explanation is necessary. In other words, "yes" could 541 be a reasonable answer by itself, but "no" would require more by way 542 of explanation... or vice versa. 544 But for the second purpose, providing useful information to the IESG, 545 yes/no responses are often of little or no use. Questions about the 546 working group process and discussions are especially looking for some 547 sort of narrative information. Don't just say that there was much 548 discussion that eventually reached consensus, or that there were a 549 number of controversial points that were resolved -- say something 550 about the discussion, talk a bit about the controversies. If there 551 were particular points that simply did not get any discussion but 552 probably should have, say that. 554 Knowing the trouble spots and the strong and weak points of the 555 discussion and consensus will allow the IESG to properly evaluate the 556 document. That can avoid the IESG's revisiting issues that were 557 already done to death in the working group. It's common to have 558 DISCUSS positions in which ADs are questioning a point that the 559 working group discussed at length, and a brief explanation in the 560 writeup could have avoided having it come up again then. 562 When the Shepherd has the writeup done, a non-chair Shepherd should 563 consult with the Chairs to make sure they're happy with it and agree 564 with what's in it. The Chairs will then need to make some 565 datatracker updates that only they have authorization for: they will 566 upload the writeup to the tracker and change the document state. 568 Changing the document's working group state to "Submitted to IESG for 569 Publication" will trigger the necessary email messages and IESG state 570 changes, and will get the document into IESG "Publication Requested" 571 state, from which the Responsible AD will begin her processing of the 572 document. And as RFC 4858 says, the Shepherd should also email the 573 writeup to the working group's mailing list, so the working group is 574 aware of it. The writeup will be public anyway, because it will be 575 in the datatracker, so it can only help the open process to make it 576 more visible to the working group whose work it reflects. 578 See also [RFC4858], Section 3.1, but note that the writeup template 579 has changed significantly since the version in that document. The 580 current writeup is in the IESG section of the IETF web site 581 [Writeup]. 583 The tasks at the Shepherd Writeup Underway stage might be as follows: 585 1. Shepherd: Complete the shepherd writeup and send it to the Chairs 586 for approval. 587 2. Chairs: Work with the Shepherd to finalize the writeup. 588 3. Chairs: Put the writeup into the datatracker, and change the 589 tracker document state to the appropriate one for requesting 590 publication. 591 4. Shepherd: Send the writeup to the working group mailing list and 592 inform the working group that publication has been requested. 594 3.6. Stage: AD Evaluation 596 The next stage in the process is up to the Responsible Area Director, 597 and the Document Shepherd has but one easy task: help make this stage 598 as short as possible. The Responsible AD or the IESG Secretary will 599 do some document state changes in the datatracker (to Publication 600 Requested and then to AD Evaluation), and the AD will review the 601 document and either request IETF Last Call or respond to the authors 602 (and, we hope, to the Shepherd as well; here's where it was useful to 603 have put the Shepherd's email address in the tracker) with review 604 comments and suggested changes. In the latter case, the document's 605 state might change to "AD Evaluation, Revised I-D Needed". 607 The Shepherd needs to watch for the key state changes and the AD's 608 review. If the review doesn't happen in a reasonable time -- 609 allowing for a busy AD's schedule and remembering that the document 610 you're shepherding isn't the only one on the AD's docket -- send a 611 reminder... perhaps as a question, "How is the review on draft-ietf- 612 frobozz-xyzzy coming?" Use your judgment to decide how long to wait, 613 but most ADs will appreciate a reminder here and there as long as 614 it's not at the level of "pestering". 616 Once the review comes in, make sure the Document Editors are on top 617 of it and respond in a timely manner. Make sure that the working 618 group is consulted on issues brought up in the review that are 619 significant enough to require the working group's engagement in the 620 response. Editorial tweaks can arguably be handled by the editors 621 alone at this point, and changes to the protocol clearly need to go 622 back to the working group, but many issues fall in between, and good 623 judgment is important. The Chairs should be involved in deciding 624 where the line is drawn. 626 Many documents spend *months* in AD Evaluation state, largely because 627 of lack of good shepherding. It may look like there's only one major 628 task here, but it's an important one. Please don't give it short 629 shrift. 631 See also [RFC4858], Section 3.2. 633 The tasks for the Shepherd at the AD Evaluation stage might be as 634 follows: 636 1. Make sure the AD reviews the document in a timely manner, and 637 send occasional reminders as needed. 638 2. Make sure the Document Editors respond to the review in a timely 639 manner, and poke them as well, as needed. 640 3. Keep the dialogue going between the Responsible AD and the 641 editors until all issues have been dealt with and the document is 642 ready for the next stage. 643 4. See to it that issues are brought back before the working group 644 if they are significant enough to require it. 646 3.7. Stage: IETF Last Call 648 Once the Responsible AD is satisfied that the document is ready to 649 move ahead, she will put it in Last Call Requested state. That 650 prompts the IESG Secretary to send out the Last Call announcement and 651 to put the document into "In Last Call". 653 The Shepherd's job in the IETF Last Call stage is very similar to 654 what's needed in AD Evaluation. Start by watching for last-call 655 comments, including various special reviews. Reviews will come in 656 from the Security Directorate and the General Area Review Team 657 (GenART), and some may also come from other review teams and 658 directorates. Reviews might also be coming in at this stage, if they 659 haven't already, that were specifically requested by the Shepherd 660 (see the Working Group Last Call stage in Section 3.4). 662 The Shepherd needs to make sure all of those reviews are addressed by 663 the document editors, and that the specifically requested reviews get 664 done. "Addressed" doesn't mean that every change asked for in every 665 last-call comment needs to be made. Sometimes, a reasonable response 666 is to say that the working group discussed the point, and the 667 document correctly reflects its consensus -- that is, the working 668 group disagrees with the last-call comment. At other times, it's 669 reasonable to disagree with the reviewer and look for any other 670 support for the reviewer's position. Rough consensus can be a tricky 671 thing [I-D.resnick-on-consensus], but the bottom line is that all 672 comments need at least be considered. Directorate and review-team 673 reviews, in particular, require acknowledgment and response (though 674 they, too, can be disagreed with). 676 Throughout the IETF Last Call stage, as well as in the upcoming IESG 677 Evaluation, it is important that the working group be kept aware of 678 the changes that are being made to their document. Continued use of 679 the issue tracker is a useful way to do that. For especially 680 significant changes, explicitly calling the working group's attention 681 to them on the mailing list is a good idea. It's very important to 682 continue transparency into these later stages of the process. 684 During Last Call, IANA will review the document's IANA 685 Considerations, will respond with their summary of what they think 686 needs to be done by IANA after the document is approved, and will ask 687 any questions they have. The Shepherd should watch for this review 688 and make sure that the actions IANA proposes are correct and that any 689 questions they have are answered. At this point, IANA will also 690 contact any Designated Experts required to formally approve any 691 registrations, so it will help if the shepherd has done the necessary 692 preparatory work (see Section 3.4). See also [RFC4858], Section 4. 694 Different Responsible ADs will have different preferences for whether 695 documents in IETF Last Call should be updated while they're still in 696 that state. The Shepherd should check with the AD and advise the 697 Document Editors. Sometimes it's best to keep a stable version 698 throughout last-call review; other times it's better to get changes 699 posted quickly, so the same issues aren't brought up by multiple 700 reviewers. Work with the AD and the editors to handle this. 702 The tasks for the Shepherd at the IETF Last Call stage might be as 703 follows: 705 1. Monitor the last-call comments, and make sure that specifically 706 requested reviews arrive. 707 2. Make sure the Document Editors respond to all reviews and 708 comments in a timely manner. 709 3. Keep the dialogue going between the community and the editors 710 until all issues have been dealt with. 711 4. See to it that issues are brought back before the working group 712 if they are significant enough to require it. 714 3.8. Stage: Waiting for AD Go-Ahead 716 When Last Call completes, the tracker state for the document will 717 automatically go to "Waiting for AD Go-Ahead". This is the 718 Shepherd's signal to re-check the comments from last call, to make 719 sure an updated I-D is posted that is ready for IESG Evaluation, and 720 to let the Responsible AD know when everything is set. The AD will 721 be watching for this as well, but, as in the other stages, it's the 722 Shepherd's responsibility to keep an eye on things and make sure 723 what's needed gets done. 725 This is also a good time to remember that the document shepherd 726 writeup is not static. If significant time has elapsed, significant 727 discussion has happened, or significant changes have been made, it's 728 a good idea to work with the Chairs to update the shepherd writeup in 729 the datatracker, making sure that delays, discussions, and major 730 changes are outlined in the writeup for the IESG. 732 The Responsible AD has some manual work to do here: she must record 733 the IETF consensus in the datatracker, move the document into IESG 734 Evaluation, issue an IESG ballot for the document, and schedule the 735 document on an IESG telechat agenda. The Shepherd should watch for 736 this and make sure the Responsible AD is on top of it. 738 The tasks for the Shepherd at the Waiting for AD Go-Ahead stage might 739 be as follows: 741 1. Make sure a new I-D is posted with the latest changes, and inform 742 the Responsible AD that all changes have been incorporated and 743 that the document is ready for IESG Evaluation, or... 744 2. ...inform the Responsible AD that no changes are required and 745 that the document is ready for IESG Evaluation. 746 3. Update the Shepherd writeup if anything has come up during Last 747 Call that the IESG should know about. The Chairs will update the 748 writeup in the datatracker. 749 4. Follow up with the Responsible AD if necessary, to make sure she 750 takes the necessary steps to enter IESG Evaluation. 752 3.9. Stage: IESG Evaluation 753 As the ADs do their reviews they will record ballot positions on the 754 document. Ballot positions can be one of "Yes", "No Objection", 755 "Discuss", and "Abstain" (there's also "Recuse" for cases when the AD 756 has a conflict of interest with the document, if, for example, the AD 757 is one of the authors/editors). Any of these ballot positions can be 758 accompanied by non-blocking review comments, and "Discuss" also comes 759 with blocking comments in addition -- these must be resolved to the 760 satisfaction of the Discussing AD before the document can be approved 761 by by the IESG. The document will be scheduled for a bi-weekly 762 "telechat" (at the time of this writing they're on Thursdays), and it 763 will be approved then or left in one of several follow-up states. 765 The IESG Evaluation period is normally somewhere between one and 766 three weeks, though it can be as little as a few days in unusual 767 circumstances. Be aware, though, that there's usually a burst of 768 review activity in the final few days before the telechat, and expect 769 most reviews to come in then. 771 The IESG Evaluation comments and DISCUSS positions will be copied to 772 the Document Shepherd (again, it was important to have put the 773 Shepherd's email address in the tracker), and the Shepherd should be 774 watching for them and making sure that the Document Editors respond 775 promptly -- at this stage, quick turnaround is most important. 776 Sometimes the Shepherd or Chairs might respond to AD questions and 777 comments themselves, and sometimes they might leave it to the 778 editors. The process works best when everyone engages, with the goal 779 of resolving the issues brought up by the ADs as efficiently as 780 possible. 782 A word about DISCUSS positions: Many Document Editors treat these as 783 adversarial situations created by aggressive ADs, but that's 784 generally not the intent. First, many DISCUSSes are resolved quickly 785 and easily by a round of email with the Discussing AD, and that's as 786 it should be: the point is that the AD has something to "discuss" 787 with those responsible for the document before she can agree to the 788 document's approval. Second, many DISCUSSes that do take more 789 effort, often significant back and forth with the Discussing AD and 790 other IESG members, result in a better document, having cleared up 791 some significant confusion or having closed a hole in the 792 specification that was missed at earlier stages. Please try to treat 793 the situation as one in which everyone is looking to make the 794 document better. 796 Most often, ADs who record DISCUSS positions (and review comments) 797 are quite responsive, and will work with the Editors and Shepherd to 798 get everything resolved. Sometimes, though, a busy AD can find 799 herself lacking the time to respond. The Shepherd should keep the 800 ADs honest, pushing for quick responses. In earlier stages, too- 801 frequent reminders might be considered unreasonable, but at this 802 stage discussion should be fairly brisk, and a delay of more than a 803 couple of days should be unusual, on either side. 805 Non-blocking IESG Evaluation comments should be treated as IETF Last 806 Call comments are: the Document Editors should respond to them and do 807 their best to address them, but failure to come to agreement on them 808 will not block the document's progress. 810 And, as at other stages, the Shepherd should work with the Chairs to 811 ensure that any changes of significance are brought back to the 812 working group for their review before the final approval notice goes 813 out. 815 The IESG web site has more details about IESG ballot positions 816 [Ballot] and about IESG DISCUSS ballots in particular [Discuss]. And 817 see also [RFC4858], Section 3.3. 819 The tasks for the Shepherd at the IESG Evaluation stage might be as 820 follows: 822 1. Keep track of the DISCUSS positions and review comments by the 823 IESG. 824 2. Make sure all comments are addressed, and help the discussions of 825 DISCUSS positions reach closure. 826 3. Keep both the Document Editors and the Discussing AD engaged in 827 the resolution of the issues. 828 4. See to it that issues are brought back before the working group 829 if they are significant enough to require it. 831 3.10. Stage: Approved by the IESG 833 Once the document has been on a telechat, any necessary revised 834 versions have been posted, and all DISCUSS positions are "cleared", 835 the Responsible AD (or the IESG Secretary) will put the document into 836 the "Approved, Announcement to be Sent" state. If there's any 837 follow-up that needs to be done, it will be held with a sub-state 838 (usually "Point Raised, Writeup Needed"), and the Shepherd should 839 make sure that whatever final checks are needed get done, and that 840 the Responsible AD clears the sub-state and informs the IESG 841 Secretary. 843 At this stage, it's usually a matter of making sure that the latest 844 version of the document adequately addresses the non-blocking 845 comments by the ADs. Final adjustments to the document will be made 846 either by an updated draft (submitted by the editors) or by RFC 847 Editor notes (entered by the Responsible AD, and not directly 848 visible). The Shepherd should work with the Responsible AD to 849 understand what still needs to be done and to make sure it happens, 850 and to check on RFC Editor notes and make sure they're correct and 851 that the working group is aware of them. 853 The tasks for the Shepherd at the Approved by the IESG stage might be 854 as follows: 856 1. Work with the Responsible AD to understand what still needs to be 857 addressed. 858 2. Double-check the IANA actions and ask the AD about any RFC Editor 859 notes; follow up on any errors or omissions. 860 3. Make sure the Document Editors and the Responsible AD move the 861 document to the final Approved state. 863 3.11. Stage: In RFC Editor Queue 865 Shortly after the approval announcement is sent out, the document 866 will go into the RFC Editor queue, and the Shepherd will start seeing 867 it pass through a number of RFC Editor states. For most of this, the 868 Shepherd need do nothing, and is just waiting for the AUTH48 state. 869 This will usually take between a few weeks and a few months, 870 depending upon many factors, but it can be held up indefinitely by 871 normative references to documents that are not yet ready for 872 publication. Be aware of what the document is waiting for, and 873 otherwise just wait. If anything looks odd, ask the Responsible AD 874 to check. 876 Watch particularly for states that indicate that IANA is waiting for 877 something, and be aware of likely timing on missing references (RFC 878 Editor "MISSREF" states). For the former, make sure that IANA gets 879 the responses they need. For the latter, consider alternatives in 880 cases where missing references are likely to cause significant delays 881 that might be avoided by using different references. Consult with 882 the Chairs and Responsible AD if it seems that some action would be 883 useful. 885 The tasks for the Shepherd at the In RFC Editor Queue stage might be 886 as follows: 888 1. Sip tea or drink beer or wine, and wait for AUTH48. 889 2. Talk to the Responsible AD if something doesn't look right. 891 3.12. Stage: AUTH48 893 AUTH48 is an RFC Editor state that occurs when the RFC Editors have 894 done their final edits on the document before publication. It's 895 meant to represent a 48-hour period in which the AUTHors can review 896 what the RFC Editor has changed, have a final look at the document, 897 and make sure it's ready to go. 899 AUTH48 is a critical document state; do not downplay its importance. 900 At this stage, the Shepherd should re-review the document, paying 901 special attention to recent changes. The Document Editors must do 902 the same, and a response from every Author/Editor listed at the top 903 of the document is required before the RFC Editor will finish the 904 publication process. The Document Shepherd needs to make sure that 905 the Editors all respond, and should take the lead in prompting them 906 early and frequently. Remember that "AUTH48" is meant to refer to 48 907 hours, not 48 days. Don't let this drag on. 909 The RFC Editor will often have questions that the Authors/Editors 910 need to answer. The Document Editors often have minor changes to 911 insert at this point. The Shepherd should consider those answers, 912 those changes, and the changes the RFC Editor has made leading into 913 AUTH48, and assess, in consultation with the Chairs and the 914 Responsible AD, whether any changes need to be passed back to the 915 working group -- remember that the document has been approved by 916 rough consensus of the working group, and then of the IETF as a 917 whole, and the final, published version must continue to reflect that 918 consensus. 920 It's unusual for there to be significant controversy at this stage, 921 but it's been known to happen. Sometimes a change or a question by 922 the RFC Editor will raise a question with the Document Editors that 923 had not come up before. Sometimes, the right answer to one of those 924 questions will be more than just editorial, and sometimes it will 925 involve a significant technical decision. Decisions of that nature 926 should not be made by the Document Editors alone, and the Shepherd 927 should arrange with the Chairs to have those issues discussed by the 928 working group. 930 Most of the time, though, this stage will run smoothly, the Document 931 Editors will respond to the AUTH48 messages with a minimum of 932 prodding, and the RFC Editor will announce their happiness and 933 proceed with the publication process. 935 See also Section 5 of [RFC4858]. 937 The tasks for the Shepherd at the AUTH48 stage might be as follows: 939 1. Monitor the AUTH48 process and make sure all questions are 940 answered and all Authors/Editors respond as needed. 941 2. Assess whether any issues that come up are significant enough to 942 need review by the working group. 944 3.13. Stage: Published 946 We're done. The RFC Editor has published the document, and the RFC 947 announcement has been made. Many thanks to the Shepherd for having 948 seen it through and for helping to assure a high quality document. 950 4. Some Final Notes 952 We have outlined a Document Shepherding Function, above, in a lot of 953 detail, so let's put the executive summary back here: 955 What it all boils down to is setting up one person who takes 956 responsibility for following the progress of a document from Call for 957 Adoption through Publication, staying actively involved with managing 958 the discussion and issue resolution at every stage, and making sure 959 the necessary participants are responsive and that things don't 960 languish from inattention. 962 And again, Working Group Chairs may delegate all or part of this 963 function to a non-chair participant, or retain all responsibility for 964 it themselves. In the latter case, what is described here is nothing 965 different to what should be happening already. Setting it out as 966 clear tasks and a set of stages in the document's lifecycle will make 967 it easier to recognize what needs to be done when, and to handle 968 delegation when the Chairs choose to delegate. 970 5. Security Considerations 972 This document describes practices by IETF working group chairs and 973 document shepherds that support carrying out the IETF standards 974 process. It is entirely unrelated to security in any way. 976 6. IANA Considerations 978 No IANA actions are requested by this document, and the RFC Editor is 979 asked to remove this section before publication. 981 7. References 983 7.1. Normative References 985 [RFC2418] Bradner, S., "IETF Working Group Guidelines and 986 Procedures", BCP 25, RFC 2418, September 1998. 988 [RFC4858] Levkowetz, H., Meyer, D., Eggert, L. and A. Mankin, 989 "Document Shepherding from Working Group Last Call to 990 Publication", RFC 4858, May 2007. 992 7.2. Informative References 994 [Ballot] IESG, , "IESG Ballot Procedures", May 2009, . 997 [Discuss] IESG, , "DISCUSS Criteria in IESG Review", July 2007, 998 . 1001 [I-D.resnick-on-consensus] 1002 Resnick, P., "On Consensus and Humming in the IETF", 1003 Internet-Draft draft-resnick-on-consensus-07, April 2014. 1005 [RFC6174] Juskevicius, E., "Definition of IETF Working Group 1006 Document States", RFC 6174, March 2011. 1008 [RFC7120] Cotton, M., "Early IANA Allocation of Standards Track Code 1009 Points", BCP 100, RFC 7120, January 2014. 1011 [Stmt] IESG, , "IESG Statement on Document Shepherds", October 1012 2010, . 1015 [Writeup] IESG, , "Working Group Submission Writeup", February 2012, 1016 . 1018 Appendix A. Lifecycle Stages and Corresponding Document States 1020 +===========================+===================================+===============+ 1021 | Lifecycle stage | Document state | State owner | 1022 +===========================+===================================+===============+ 1023 | Call for Adoption | Call for Adoption by WG Issued | WG | 1024 +---------------------------+-----------------------------------+---------------+ 1025 | Working Group Document | WG Document | WG | 1026 +---------------------------+-----------------------------------+---------------+ 1027 | Working Group Last Call | In WG Last Call | WG | 1028 +---------------------------+-----------------------------------+---------------+ 1029 | Shepherd Writeup Underway | WG Consensus: Waiting for Writeup | WG | 1030 +---------------------------+-----------------------------------+---------------+ 1031 | AD Evaluation | AD Evaluation | IESG | 1032 +---------------------------+-----------------------------------+---------------+ 1033 | IETF Last Call | In Last Call | IESG | 1034 +---------------------------+-----------------------------------+---------------+ 1035 | Waiting for AD Go-Ahead | Waiting for AD Go-Ahead | IESG | 1036 +---------------------------+-----------------------------------+---------------+ 1037 | IESG Evaluation | IESG Evaluation | IESG | 1038 +---------------------------+-----------------------------------+---------------+ 1039 | Approved by the IESG | Approved-announcement to be sent | IESG | 1040 +---------------------------+-----------------------------------+---------------+ 1041 | In RFC Editor Queue | RFC Ed Queue | IESG | 1042 +---------------------------+-----------------------------------+---------------+ 1043 | AUTH48 | AUTH48 | RFC Ed | 1044 +---------------------------+-----------------------------------+---------------+ 1045 | Published | RFC Published | RFC Ed | 1046 +---------------------------+-----------------------------------+---------------+ 1048 Author's Address 1050 Barry Leiba 1051 Huawei Technologies 1053 Phone: +1 646 827 0648 1054 Email: barryleiba@computer.org 1055 URI: http://internetmessagingtechnology.org/