idnits 2.17.1 draft-juskevicius-datatracker-wgdocstate-reqts-08.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (November 18, 2010) is 4907 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- No issues found here. Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Proto E. Juskevicius 2 Internet Draft TrekAhead 3 Intended status: Informational November 18, 2010 4 Expires: May 18, 2011 6 Requirements to Extend the Datatracker for IETF WG Chairs and 7 Authors 8 draft-juskevicius-datatracker-wgdocstate-reqts-08.txt 10 Abstract 12 This document specifies requirements for new functionality to be 13 added to the IETF Datatracker tool to make it possible for Working 14 Group (WG) Chairs and their Delegates to input and update the status 15 of the Internet-Drafts (I-Ds) associated with their WGs. After 16 these requirements are implemented, WG Chairs will be able to use 17 the Datatracker to provide everyone with more information about the 18 status and progression of WG I-Ds than is currently possible. 20 Status of this Memo 22 This Internet-Draft is submitted to IETF in full conformance with 23 the provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six 31 months and may be updated, replaced, or obsoleted by other documents 32 at any time. It is inappropriate to use Internet-Drafts as 33 reference material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on May 18, 2011. 37 Copyright Notice 39 Copyright (c) 2010 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with 47 respect to this document. Code Components extracted from this 48 document must include Simplified BSD License text as described in 49 Section 4.e of the Trust Legal Provisions and are provided without 50 warranty as described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction...................................................2 55 2. Conventions Used In This Document..............................3 56 3. General Requirements...........................................4 57 4. Privilege and Access Control Requirements......................5 58 4.1. For Everyone..............................................5 59 4.2. For IETF Working Group Chairs.............................6 60 4.3. For Delegates of IETF WG Chairs...........................7 61 4.4. For IETF WG Document Shepherds............................7 62 4.5. For the Responsible Area Director.........................9 63 4.6. Role of the IETF Secretariat in Granting Permissions......9 64 5. Inputting and Updating WG Document Status Information..........9 65 5.1. WG I-D States.............................................9 66 5.2. WG I-D Status Annotation Tags............................10 67 5.3. WG I-D Protocol Write-ups................................11 68 6. Special Requirements for Some WG I-D States and Conditions....12 69 6.1. Call For Adoption By WG Issued...........................12 70 6.2. Adopted by a WG..........................................13 71 6.3. WG Document..............................................14 72 6.4. Parked WG Document.......................................15 73 6.5. Dead WG Document.........................................15 74 6.6. In WG Last Call..........................................16 75 6.7. WG Consensus: Waiting for Write-Up.......................16 76 6.8. Submitted to IESG for Publication........................17 77 6.9. Revised I-D Needed (annotation tag)......................17 78 7. Automatic State Changes for I-Ds..............................18 79 8. WG I-D Status Change Reporting Requirements...................18 80 9. WG I-D Status Reporting Requirements..........................19 81 10. Error Handling Requirements..................................20 82 11. Security Considerations......................................20 83 12. IANA Considerations..........................................21 84 13. References...................................................21 85 13.1. Normative References....................................21 86 13.2. Informative References..................................21 87 14. Acknowledgments..............................................21 89 1. Introduction 91 The IETF Datatracker is a web-based system for managing information 92 about Internet-Drafts (I-Ds) and RFCs, IPR disclosures, liaison 93 statements and several other important aspects of the IETF process. 94 [IDTRACKER] 96 The Datatracker can track and report on the status of every I-D that 97 has been submitted to the IESG for evaluation and publication. In 98 contrast, the tool currently has almost no ability to track the 99 status of I-Ds that have not been submitted to the IESG. [WGDRAFTS] 100 Document authors and others have asked for more visibility into the 101 status and progression of IETF Working Group (WG) drafts. 103 This document specifies requirements to extend the Datatracker to 104 enable status tracking and reporting for WG I-Ds. After these 105 requirements are implemented, WG Chairs will be able to use the 106 Datatracker to provide everyone more information about the WG status 107 of the I-Ds associated with their WGs than is currently possible. 109 2. Conventions Used In This Document 111 The terms "WG I-D", "WG document", and "WG draft" are used 112 synonymously throughout this document. The same is true for the 113 plural case of each term. 115 A "WG draft" is an I-D that has achieved consensus for adoption as a 116 work item by a WG (compared to an individual submission I-D that has 117 not, or has not yet, achieved consensus). 119 The terms "WG document" and "WG draft" are not intended to apply to 120 any other document that may be reviewed, discussed, or produced by 121 an IETF Working Group. WG meeting materials such as Blue Sheets, 122 agendas, jabber logs, scribe's notes, minutes, and presentation 123 slides are not to be considered as "WG documents" or "WG drafts" in 124 the context of this document. 126 The phrase "WG status of an I-D" refers to the WG state that an I-D 127 is in per the definitions in Section 4.2 of [WGDRAFTS]. This phrase 128 does not refer to an I-D's availability status (e.g. "Expired", 129 "Active", "Replaced by") as described in Section 3.1 of [WGDRAFTS], 130 or to any of the IESG states used by IETF Area Directors (ADs) to 131 describe the status of I-Ds they may be evaluating. Note that this 132 phrase encompasses all of the states that a WG I-D may be in, plus 133 one more (viz. "Call For Adoption By A WG Issued"). 135 The phrase "I-D associated with a WG" is intended to describe two 136 types of Internet-Drafts: 138 - I-Ds that have been accepted as WG drafts; and 140 - I-Ds that are being considered under the guidance of a WG Chair for 141 adoption by a WG. 143 An I-D having a filename that contains the string 'draft-ietf-' 144 followed by a WG acronym is almost always a WG draft and is to be 145 interpreted as being an "I-D associated with a WG" for the purposes 146 of this document. 148 An I-D having a filename that includes the author's name and a WG 149 acronym but does not include the string '-ietf-' may be a candidate 150 for adoption by a WG and, if so, is also to be interpreted as being 151 an "I-D associated with a WG" for the purposes of this document. 153 The requirements specified in this document use English phrases 154 ending with "(R-nnn)", where "nnn" is a unique requirement number. 156 When used in the context of the requirements in this document, the 157 key words "MUST", "MUST NOT", "SHALL", "SHALL NOT", "SHOULD", 158 "SHOULD NOT", and "MAY" are to be interpreted as described in 159 RFC 2119 [RFC2119]. RFC 2119 defines the use of these key words 160 to help make the intent of standards track documents as clear as 161 possible. The same key words are used in this document to make the 162 meaning of the requirements specified herein as clear as possible. 164 3. General Requirements 166 The enhancements to be made to the Datatracker described in this 167 document MUST be implemented in a manner that provides WG Chairs and 168 the people they designate to act as their Delegates with the option 169 to input and update the WG status of some, all, or none of the I-Ds 170 associated with their WGs using the WG I-D states and I-D status 171 annotation tags defined in [WGDRAFTS]. (R-001) In other words, the 172 implementation must not require that WG Chairs change their way of 173 working, but only provide optional features. WG Chairs must have 174 the flexibility to use the enhancements to the Datatracker to track 175 the WG status of their I-Ds as is most appropriate for them. 177 To ensure that at least some WG status information is tracked for 178 every I-D associated with a WG, the Datatracker must be enhanced to 179 generate a few automatic state transitions for every WG I-D. The 180 requirements for this feature are specified in Section 7 of this 181 document. 183 Requirement R-001 SHALL NOT impair the ability of the Datatracker to 184 track and display the availability state of any I-D. (R-002) I-D 185 availability states (e.g. "Active", "Expired", "Replaces") are 186 described in Section 3.1 of [WGDRAFTS]. 188 The Datatracker SHALL NOT permit users other than a Working Group's 189 Chairs (e.g. the Chairs of a different IETF WG) to update the WG 190 status of a WG's documents through the regular Datatracker 191 interface, unless the privileges to do so have been explicitly 192 delegated to them by one of the WG's Chairs. (R-003) 194 The user-interface to be provided by the Datatracker to WG Chairs 195 (and their Delegates) to input the WG status of the I-Ds associated 196 with their WGs SHOULD have a look and feel that is similar to the 197 interface currently used by ADs to identify the status of I-Ds under 198 formal evaluation by the IESG. (R-004) 200 Any new pages created to display the status of WG I-Ds SHOULD be 201 designed to have a look and feel that is similar to the pages 202 currently used by the Datatracker to display the status of I-Ds 203 under formal evaluation by the IESG. (R-005) 205 New javascript UI code and style sheets implemented to satisfy the 206 requirements in this document SHOULD reuse or share existing code 207 where practical so that when a change to the IESG status of an I-D 208 is entered into the Datatracker, the WG status tracking for that I-D 209 can benefit, and vice versa. (R-006) 211 The Datatracker MUST date and timestamp every update to the WG 212 status of an I-D that is associated with a WG and be able to use 213 that information when it displays the status change history for the 214 I-D. (R-007) The WG status change history for an I-D MUST also 215 identify the person or entity that updated the WG status of the I-D 216 (e.g. one of the WG's Chairs, a Delegate, an AD, the System, the 217 IETF Secretariat) and describe what changed (e.g. "WG State changed 218 from 'a' to 'b'", "WG Annotation Tag 'x' Set (or Reset)"). (R-008) 220 The inputting or updating of the WG status of an I-D SHALL NOT 221 overwrite any previously archived status change history information 222 for the I-D; every update to the WG status of an I-D MUST be added 223 to the status change history log for the I-D. (R-009) 225 WG I-D status tracking MUST be implemented per-draft, not per-WG. 226 (R-010) 228 WG I-D status tracking SHOULD be implemented as a new front-end to 229 the Datatracker's existing IESG state machine [IESGIDSM]. (R-011) 231 The Datatracker SHALL permit authorized users (e.g. WG Chairs, 232 Delagates) to change the WG state of a draft independently from the 233 IESG state of the same I-D and vice versa. (R-012) 235 4. Privilege and Access Control Requirements 237 4.1. For Everyone 239 Everyone needs to be able to view information about the WG status of 240 an I-D without logging on to the Datatracker. Everyone SHALL be 241 given 'read' access to WG I-D status information. (R-013) 243 People who need to input, modify or update the WG status of an I-D 244 (e.g. WG Chairs and their Delegates) need 'write' privileges; these 245 users SHALL be required to log-on to the Datatracker using a 246 personal user-id and password (e.g. an IETF tools password) in order 247 to gain 'write' access. (R-014) 249 4.2. For IETF Working Group Chairs 251 After successfully logging on to the Datatracker as specified in 252 Requirement R-014, WG Chairs: 254 - SHALL be given full 'read' and 'write' privileges to input and 255 update the WG status information for all of the I-Ds associated 256 with their WGs; (R-015) 258 - SHALL be able to able to choose from all of the WG I-D states and 259 WG I-D status annotation tags defined in [WGDRAFTS] to describe the 260 current WG status of the I-Ds associated with their WGs; (R-016) 262 - SHAALL NOT be allowed to create new WG I-D states or state names; 263 (R-017) 265 - SHALL NOT be allowed to update or modify information which is not 266 related to the WG status of an I-D (e.g. IANA status, RFC-Editor 267 status, IESG status); (R-018) 269 - SHALL be able to designate a maximum of three people to act as 270 their Delegates to input and update the WG status of the I-Ds 271 associated with each of their WGs; (R-019) A suitable way to 272 specify a Delegate may be to use the individual's current e-mail 273 address, but the delegation MUST be to the individual identified by 274 the login credentials used by the Datatracker at any given time 275 rather than to an e-mail address; (R-020) Individuals must be able 276 to update their e-mail addresses in the future without breaking the 277 delegation specified in Requirement R-019; 279 - SHALL be able to designate a maximum of three different people to 280 act as their Delegates in a different WG if a WG Chair is also 281 responsible for the different WG; (R-021) 283 - SHALL be able to designate people who have other roles in the IETF 284 process (e.g. are Chairs of different WGs, are ADs in a different 285 Area) to be their Delegates; (R-022) 287 - SHALL be able to review and change their Delegates; (R-023) 289 - SHALL be able to input or upload Document Shepherd protocol write- 290 ups for all of the I-Ds associated with their WGs; (R-024) 292 - SHALL be able to designate themselves as the Document Shepherds for 293 some or all of the I-Ds in their WGs; (R-025) 295 - SHALL be able to designate other people to be Document Shepherds 296 for one or more of their WG I-Ds if this role will not be performed 297 by the WG Chairs; (R-026) A suitable way to designate people to be 298 the Document Shepherds may be to use their e-mail addresses, but 299 the delegation MUST be to the individuals identified by the login 300 credentials used by the Datatracker at the time, rather than to the 301 e-mail addresses; (R-027) The Datatracker MUST be able to maintain 302 an individual's designation as a Delegate per R-026 in the event 303 that the person changes their e-mail address in the future; (R-028) 305 - SHALL be warned in real-time (e.g. via the Datatracker's regular 306 user-interface) if a person they try to designate as a Delegate or 307 Document Shepherd does not have the necessary login credentials for 308 the Datatracker; (R-029) The Datatracker SHALL then allow the WG 309 Chairs to confirm the original designee or to pick another. (R-030) 311 - SHALL be able to review and change the people designated to be 312 Document Shepherds for each of their WG I-Ds. (R-031) 314 - SHOULD be able to access the same user-interfaces the Datatracker 315 provides to their Delegates and Document Shepherds in order to 316 mentor or coach them on how to input and update WG I-D status 317 information in the Datatracker. (R-032). 319 4.3. For Delegates of IETF WG Chairs 321 After successfully logging on to the Datatracker, the Delegates of 322 WG Chairs (e.g. WG Secretaries) SHALL have the same privileges as 323 their WG Chairs to input WG I-D status information and Document 324 Shepherd protocol write-ups as specified in Requirements R-015 to 325 R-018 inclusive, R-024 and R-025. (R-033) 327 The Datatracker SHALL send an e-mail to the Chairs of the WG, the 328 IETF Secretariat, and to a newly designated Delegate if the newly 329 designated Delegate does not have a personal user-id and password to 330 log-on to the Datatracker. (R-034) The purpose of the e-mail is to 331 confirm to the WG Chairs that the person they designated to be a 332 Delegate needs to take action to obtain a personal user-id and 333 password, and to inform the Delegate that he/she needs to take 334 action (e.g. to contact the IETF Secretariat) to obtain their own 335 user-id and password for the Datatracker. 337 4.4. For IETF WG Document Shepherds 339 The IETF document shepherding process and the role of an IETF WG 340 Document Shepherd is described in RFC 4858 [RFC4858]. 342 The requirements in this Section describe the access privileges to 343 be granted to a WG Document Shepherd who is not a WG Chair or a 344 Delegate with the privileges specified in Section 4.3. 346 Per Requirement R-014, each person designated to be a Document 347 Shepherd for a WG draft needs to have their own personal user-id and 348 password to log-on to the Datatracker. 350 The Datatracker SHALL alert the WG Chairs, the IETF Secretariat, and 351 the newly designated Document Shepherd (e.g. via e-mail) if a person 352 newly designated as a Document Shepherd does not have a personal 353 user-id and password to log-on to the Datatracker. (R-035) The 354 purpose of the e-mail is to confirm to the WG Chairs that the 355 Document Shepherd needs to take action to obtain a personal user-id 356 and password, and to inform the Document Shepherd that he/she needs 357 to take action (e.g. to contact the IETF Secretariat) to obtain a 358 personal user-id and password for the Datatracker. 360 Document Shepherds need to be able to upload or input protocol 361 write-ups into the Datatracker for the WG I-Ds assigned to them. 362 They also need to be able to set and reset the WG I-D status 363 annotation tag called "Doc Shepherd Follow-up Underway" as defined 364 in Section 4.3.10 of [WGDRAFTS] for I-Ds in the "WG Consensus: 365 Waiting for Write-Up" state. 367 After successfully logging on to the Datatracker, Document Shepherds 368 SHALL have restricted 'write' privileges to upload or input protocol 369 write-ups for the WG I-Ds assigned to them when the I-Ds are in the 370 "WG Consensus: Waiting for Write-Up" state. (R-036) 372 Document Shepherds SHALL also have the ability to set and reset the 373 WG I-D status annotation tag called "Doc Shepherd Follow-Up 374 Underway" as defined in Section 4.3.10 of [WGDRAFTS]. (R-037) 376 The "Doc Shepherd Follow-Up Underway" annotation tag should be set 377 to indicate when the Document Shepherd has started work on a write- 378 up for the document. The absence or resetting of this annotation 379 tag may indicate the protocol write-up has not yet been started, or 380 has been put on-hold for some reason, or has been completed. The 381 log of set and reset operations performed on this annotation tag 382 will provide insight into the status of the protocol write-up for a 383 WG I-D. 385 Section 5.3 describes how Document Shepherds may input or upload 386 protocol write-ups to the Datatracker for the WG I-Ds assigned to 387 them. 389 4.5. For the Responsible Area Director 391 After successfully logging on to the Datatracker, an AD SHALL have 392 the same privileges as a WG Chair to input and update WG I-D status 393 information, to designate Delegates and Document Shepherds. (R-038) 394 An AD SHALL have the privileges specified in Requirement R-038 for 395 every WG in his or her Area. (R-039) ADs MUST also retain their 396 existing privileges to input and update the IESG status of the I-Ds 397 they are responsible for. (R-040) 399 To minimize confusion, the Datatracker MUST make it easy for ADs to 400 distinguish between their IESG-level privileges (to input or update 401 the IESG status of an I-D) and the WG-level privilege they will 402 obtain as a result of R-038 and R-039 for I-Ds associated with the 403 WGs they are responsible for. (R-041) 405 4.6. Role of the IETF Secretariat in Granting Permissions 407 The IETF Secretariat is involved in granting permissions to people 408 who need to login to the Datatracker. 410 Before granting permissions to update WG I-D status settings to a 411 person who does not have them, the IETF Secretariat should verify 412 that the person requesting the permissions is a WG Chair or an AD or 413 has been delegated the authority to update WG I-D status information 414 by one of the WG's Chairs or a Responsible AD. The e-mails to be 415 generated and sent by the Datatracker per Requirements R-034 and 416 R-035 will alert the Secretariat that the granting of permissions of 417 some new people will be needed. 419 5. Inputting and Updating WG Document Status Information 421 5.1. WG I-D States 423 Requirements R-001, R-016 and R017 specify that the WG state of an 424 I-D may only be described using the states defined in Section 4 of 425 [WGDRAFTS]. 427 When a WG Chair or Delegate logs-on to the Datatracker to input or 428 change the WG state of an I-D, the Datatracker SHOULD display the 429 current state of the I-D, the length of time the document has been 430 in its current state, the amount of time the I-D may continue to 431 remain in its current state if this information is available (viz. 432 per Requirements R-064 and R-083), and the most likely next WG state 433 (or states) for the I-D. (R-042) The Datatracker MAY use the WG I-D 434 state machine illustrated in Section 4.1 of [WGDRAFTS] to identify 435 the 'most likely next state' (or states) for an I-D that is 436 associated with a WG. (R-043) 437 After displaying the information required by R-042, the Datatracker 438 SHALL make it easy for the WG Chair or Delegate to select a next 439 state for the I-D and to enter some text to explain the state change 440 for the I-D's status change history. (R-044) The Datatracker SHALL 441 encourage the person who updates or changes the WG state of an I-D 442 to provide some context for the status change by entering text to 443 describe the change in the I-D's status change history log. (R-045) 445 The Datatracker SHALL allow a WG Chair (or Delegate) to select the 446 next state for an I-D from the 'most likely' next states described 447 by Requirement R-043, or from any of the other WG I-D states (per 448 Requirement R-016) if a different state change is required. (R-046) 450 5.2. WG I-D Status Annotation Tags 452 WG I-D status annotation tags may be used to describe a condition 453 that is affecting a document (e.g. why a WG I-D is in the state it 454 is in) or to indicate an action needed to progress the document, 455 however annotation tags do not change the state of WG I-Ds. 457 Section 4.3 of [WGDRAFTS] defines the meaning and usage of the WG 458 I-D status annotation tags to be added to the Datatracker. 460 The Datatracker SHALL allow WG Chairs and their Delegates to set and 461 reset each of the WG I-D status annotation tags defined in Section 462 4.3 of [WGDRAFTS] for every I-D associated with their WGs. (R-047) 464 WG I-D status annotation tags SHALL be able to be used one at a time 465 or in combination with other annotation tags to describe the status 466 of any I-D associated with a WG. (R-048) 468 When a WG Chair, Delegate or Document Shepherd logs into the 469 Datatracker to set or reset one or more WG I-D status annotation 470 tags for the I-Ds they are responsible for, the Datatracker SHOULD 471 display a summary of all annotation tag set/reset operations to date 472 for those WG I-Ds, from the present time backwards, split by pages, 473 and then guide the user to select one (or more) annotation tags to 474 be set or reset. (R-049) Note that Document Shepherds who are not 475 WG Chairs may only set and reset the annotation tag called "Doc 476 Shepherd Follow-up Underway" per Requirement R-037. 478 The summary of annotation tag set/reset operations (required by 479 R-049) SHALL also indicate when each annotation tag attached to the 480 current state of each I-D was set or reset and the identity of the 481 person or entity that set or reset each I-D status annotation tag. 482 (R-050) 484 The Datatracker SHALL allow more than one annotation tag to be set 485 or reset per log-on, and the Datatracker SHALL encourage the user to 486 input some text to explain why each annotation tag is being set or 487 reset. (R-051) 489 5.3. WG I-D Protocol Write-ups 491 The IESG currently requires a protocol write-up to be prepared for 492 every WG I-D before the I-D is submitted to the IESG for evaluation. 494 When a user (e.g. WG Chair, Document Shepherd) logs into the 495 Datatracker to input or upload a protocol write-up for an I-D, the 496 Datatracker SHOULD make it easy for the user to understand the 497 current status of the protocol write-up for every I-D that he/she is 498 responsible for. (R-052) The Datatracker SHOULD indicate at least 499 the date when the most recent protocol write-up was uploaded or 500 inputted for each I-D and the identity of the person or entity that 501 performed the upload or input operation. (R-053) 503 After displaying the information required by R-053, the Datatracker 504 SHALL provide the user with an interface to input or upload a 505 protocol write-up for the I-Ds that he/she is responsible for, and 506 to set or reset the "Doc Shepherd Follow-up Underway" annotation tag 507 for I-Ds. (R-054) The Datatracker SHALL encourage the user to set 508 or reset the "Document Shepherd Follow-Up Underway" annotation tag 509 before the end of each protocol write-up uploading or inputting 510 session and to input some descriptive text (for context) to be 511 stored in I-D's status change history log. (R-055) 513 Per Requirement R-100, the Datatracker will send an e-mail to the 514 author of a WG draft (and copy the WG Chairs and Delegates) when the 515 protocol write-up for the I-D is loaded into the Datatracker. A 516 copy of the e-mail SHALL also be sent to the Document Shepherd if 517 he/she is not the WG Chair (or Delegate) to confirm the protocol 518 write-up for the I-D was successfully loaded into the Datatracker. 519 (R-056) 521 Recall that WG Chairs and their Delegates shall be able to input a 522 protocol write-up for any of their WG drafts at any time per 523 Requirements R-024 and R-033. 525 If a Document Shepherd who is not a WG Chair or other Delegate 526 attempts to upload or input a protocol write-up for an I-D that is 527 not in the WG state called "WG Consensus: Waiting for Write-Up", the 528 Datatracker SHOULD warn the Document Shepherd that it may be too 529 early to input a write-up, and then direct the Document Shepherd to 530 contact one of the WG's Chairs for guidance. (R-057) The WG Chair 531 may decide to move the I-D into the "WG Consensus: Waiting for 532 Write-Up" state to enable the Document Shepherd to upload his/her 533 protocol write-up, or the WG Chair may upload the protocol write-up 534 as specified in Requirement R-024. 536 Requirement R-032 specifies that WG Chairs should be able to access 537 the Document Shepherd user-interface and call up a display of the 538 same WG document protocol write-up status information that the 539 Datatracker provides to each of a WG Chair's designated Document 540 Shepherds. This is to enable each WG Chair (or Delegate)_to be able 541 to mentor new Document Shepherds and to review the workload assigned 542 to each Document Shepherd. WG Chairs (and their Delegates) who are 543 logged into the Datatracker with their normal privileges SHALL be 544 able to access the Document Shepherd user-interface without having 545 to logout and log back into the Datatracker. (R-058) 547 6. Special Requirements for Some WG I-D States and Conditions 549 6.1. Call For Adoption By WG Issued 551 The "Call For Adoption By WG Issued" state may be used to describe a 552 draft that is being considered for adoption by an IETF WG. An I-D 553 in this state has not yet achieved consensus, preference or 554 selection in a working group. 556 This state may be used to describe an I-D that someone has asked a 557 WG to consider for adoption if the WG Chair has agreed with the 558 request. This state may also be used to identify an I-D that a WG 559 Chair asked an author to write specifically for consideration as a 560 candidate WG item, and/or an I-D that is listed as a 'candidate 561 draft' in the WG's charter. [WGDRAFTS] 563 The Datatracker SHALL allow a WG Chair or Delegate to move an I-D 564 into the "Call For Adoption By WG Issued" state in her or his WG if 565 the I-D is not currently being considered for adoption in any other 566 WG, is not yet adopted by any other WG, is not expired, and has not 567 been withdrawn; (R-059) an I-D can only be in the "Call For Adoption 568 By WG Issued" state in one WG at a time. 570 The Datatracker SHALL NOT change the WG status of an I-D that is in 571 the "Call For Adoption By WG Issued" state until the I-D expires, or 572 until the WG Chair (or Delegate) moves the I-D into a different 573 state or until it is decided that the WG will not adopt the I-D, 574 whichever comes first. (R-060) In case a WG decides not to adopt an 575 I-D that is in the "Call For Adoption By WG Issued" state, the 576 Datatracker SHALL allow the WG Chairs (and Delegates) to cancel 577 their interest in the I-D. (R-061) 579 The Datatracker SHALL transition the state of an I-D that expires or 580 is not adopted (per Requirement R-061) from the "Call For Adoption 581 By A WG" state into a "NULL" state with respect to the WG state 582 machine and then update the status change history log of the I-D 583 accordingly. (R-062) An I-D that is not adopted by a WG may revert 584 back to having no stream-specific state in the Datatracker. 586 If a different WG Chair (or Delegate) attempts to move an I-D into 587 the "Call For Adoption By WG Issued" state in while the I-D is 588 associated with another WG, the Datatracker will not allow the 589 attempted state change to occur because of Requirement R-059. In 590 this case, the Datatracker SHALL inform the WG Chair or Delegate in 591 real-time (via the user-interface that he/she is logged into) that 592 the I-D is currently associated with a different WG and that the 593 state change they requested cannot be made at this time. (R-063) 595 A WG Chair (or Delegate) who moves an I-D into the "Call For 596 Adoption By WG Issued" state SHALL be able to, but not required to, 597 specify a length of time the I-D may remain in this state. (R-064) 598 The maximum length of time SHALL be able to be specified as a 599 "number of weeks" however it MUST NOT be allowed to extend beyond 600 the expiry date of the I-D. (R-065) Other ways to specify this 601 length of time MAY optionally be provided. (R-066) 603 If an I-D is still in the "Call For Adoption By WG Issued" state 604 when the length of time specified in R-064 runs out, the Datatracker 605 SHALL send an e-mail to inform the WG Chairs and Delegates that the 606 time has run out and that the I-D is still in "Call For Adoption By 607 WG Issued" state. (R-067) The purpose of this message is to remind 608 the WG Chairs and Delegates that they had planned to make a decision 609 on adopting the I-D by now. 611 6.2. Adopted by a WG 613 The "Adopted by a WG" state describes an individual submission I-D 614 that an IETF WG has agreed to adopt as one of its WG drafts. 616 An individual I-D that is adopted by a WG may take weeks or months 617 to be resubmitted by the author as a new (version-00) WG draft. 619 WG Chairs who use this state will be able to clearly indicate when 620 their WG has adopted an individual I-D. This will facilitate the 621 Datatracker's ability to correctly capture "Replaces" information 622 for WG drafts and to capture correct "Replaced by" information for 623 the individual I-Ds that are replaced by WG drafts. 625 The Datatracker shall allow an individual submission I-D to be moved 626 into the "Adopted by a WG" state if the I-D is not expired and it 627 has not been withdrawn, been 'replaced by' another I-D, or been 628 adopted by another IETF WG. (R-068) When a WG Chair or Delegate 629 moves an I-D into the "Adopted by a WG" state, the Datatracker SHALL 630 confirm this state change via e-mail to the author of the I-D and to 631 the Chairs and Delegates or the WG that adopted the I-D (per 632 Requirement R-100). 634 Requirement R-009 specifies that changes to the WG status of an I-D 635 shall not overwrite any previously archived I-D status history 636 information for the I-D. All status change history information for 637 an I-D needs to be preserved, including when an I-D is revised and 638 subsequently approved for posting as a new version-00 "WG Document" 639 having a different filename (viz. a filename that includes the 640 string 'draft-ietf-' followed by a WG acronym). 642 6.3. WG Document 644 The "WG Document" state describes an I-D that has been adopted by an 645 IETF WG and is being actively developed. 647 WG Chairs and their Delegates SHALL be allowed to move an I-D that 648 is not associated with any other WG into the "WG Document" state in 649 their WG unless the I-D has expired or been withdrawn or 'replaced 650 by' another I-D or RFC. (R-069) 652 Alternatively, WG Chairs may rely on the functionality specified in 653 Requirement R-070 to automatically move a version-00 draft into the 654 "WG Document" state. 656 The Datatracker SHALL automatically place a new version-00 I-D into 657 the "WG Document" state if a WG Chair approves the submission of the 658 I-D for posting in the IETF document repository and if the filename 659 of the I-D includes the string 'draft-ietf-wgname-'. (R-070) 661 The Datatracker SHOULD encourage the WG Chair to input, confirm or 662 correct the filename of the individual submission I-D that is being 663 'replaced' (if any) by a new version-00 WG draft at the time that 664 the WG Chair approves the posting of the new I-D. (R-071) 666 The WG Chair (or Delegate) who approves or moves an I-D into the 667 "WG Document" state for the first time SHALL be encouraged to input 668 an "Intended Maturity Level" for the I-D as defined in Section 5 of 669 [WGDRAFTS] if the Datatracker cannot automatically determine this 670 information for some reason. (R-072) The Datatracker SHALL allow 671 the "Intended Maturity Level" to be changed after first being set, 672 and the Datatracker SHALL allow a WG Chair or Delegate to enter this 673 information at a later time if the "Intended Maturity Level" for an 674 I-D could not be identified when the I-D was initially moved into 675 the "WG Document" state. (R-073) 677 The Datatracker SHALL allow WG Chairs and their Delegates to move an 678 I-D into the "WG Document" state from any other WG I-D state (e.g. 679 per Sections 3.2 and 4.1 of [WGDRAFTS]) if the I-D has not expired, 680 been withdrawn or been 'replaced by' another I-D or RFC. (R-074) 681 Under normal conditions, it should not be possible for an I-D to be 682 in the "WG Document" state in more than one IETF WG at a time. The 683 Datatracker SHALL NOT allow a WG Chair or Delegate to move an I-D 684 into the "WG Document" state in their WG if the I-D is already in 685 some WG I-D state in a different WG. (R-075) 687 An I-D that is in the "WG Document" state may be transferred from 688 one WG to a different WG by a Responsible AD. The Datatracker SHALL 689 allow a Responsible Area Director to transfer an I-D from one WG to 690 a different WG and it SHALL encourage the AD to input some text for 691 the status change history log of the I-D to provide context for the 692 transfer. (R-076) If an AD transfers an I-D, the Datatracker SHALL 693 send an e-mail to the author of the I-D and copy the Chairs and 694 their Delegates and the Responsible ADs (for the WGs affected by the 695 transfer) to inform them that the I-D has been transferred. (R-077) 697 6.4. Parked WG Document 699 A "Parked WG Document" is an I-D that has lost its author or editor, 700 is waiting for another document to be written or for a review to be 701 completed, or cannot be progressed by the working group for some 702 other reason. 704 The Datatracker SHALL allow a Responsible AD to transfer a "Parked 705 WG Document" that is not expired from one WG to a different WG and 706 it SHALL encourage the AD to input some text for the status change 707 history log of the I-D to provide context for the transfer. (R-078) 709 If an AD transfers an I-D, the Datatracker SHALL send an e-mail to 710 author of the I-D, to the WG Chairs and their Delegates, and to the 711 Responsible ADs (of the WGs affected by the transfer of an I-D) to 712 inform them the I-D has been transferred to a different WG. (R-079) 714 6.5. Dead WG Document 716 A "Dead WG Document" is an I-D that has been abandoned. Note that 717 'Dead' is not always a final state for a WG I-D. If consensus is 718 subsequently achieved, a "Dead WG Document" may be resurrected, 719 however a "Dead WG Document" that is not resurrected will eventually 720 expire. 722 The Datatracker SHALL allow a Responsible AD to transfer an I-D that 723 is not expired from being in the "Dead WG Document" state in one WG 724 to a non-dead state in different WG, and the Datatracker SHALL 725 encourage the AD to input some text for the status change history 726 log of the I-D to provide context for the transfer. (R-080) 728 If an AD transfers an I-D under the conditions specified by 729 Requirement R-080, the Datatracker SHALL send an e-mail to author of 730 the I-D, the WG Chairs, Delegates and the Responsible ADs (for the 731 WGs affected by the transfer) to inform them that the I-D has been 732 transferred to a different WG. (R-081) 734 6.6. In WG Last Call 736 A document that is in the "In WG Last Call" state is an I-D for 737 which a Working Group Last Call (WGLC) has been issued, and is in 738 progress. Note that WG last calls are an optional part of the IETF 739 WG process, per Section 7.4 of RFC 2418 [RFC2418]. 741 A WG Chair who decides to conduct a WGLC on an I-D may use the "In 742 WG Last Call" state to track the progress of the WGLC. 744 A WG Chair (or Delegate) SHALL be able configure the Datatracker to 745 send a WGLC message to one or more mailing lists when he/she moves a 746 WG draft into the "In WG Last Call" state and be able to select a 747 different set of mailing lists for each I-D because some documents 748 may need coordination with other WGs. (R-082) 750 The Datatracker also needs to be able to send an e-mail after a 751 specified period of time to remind or 'nudge' a WG Chair to conclude 752 a WGLC and to determine a next state for the I-D. 754 The WG Chair (or Delegate) who moves an I-D into the "In WG Last 755 Call" state SHALL be required to specify a length of time for the 756 WGLC. (R-083) The amount of time SHALL be able to be expressed as a 757 "number of weeks" but it SHALL NOT be allowed to extend beyond the 758 expiry date of the I-D. (R-084) Other measures of time (e.g. "until 759 a specific date in the future") MAY optionally be supported. (R-085) 760 The amount of time MUST be able to be changed after first being set. 761 (R-086) 763 If an I-D is still in the "In WG Last Call" state when the amount of 764 time specified in R-084 or R-085 runs out, the Datatracker SHALL 765 send an e-mail to inform the WG Chairs and Delegates that the I-D is 766 still in the "In WG Last Call" state, and to remind them they had 767 planned to conclude the WGLC by now. (R-087) 769 Note that a WGLC may lead directly back into another WGLC for the 770 same document. For example, an I-D that completed a WGLC as an 771 "Informational" document may need another WGLC if a decision is 772 taken to convert the I-D into a standards track document. The 773 Datatracker MUST allow this to occur. (R-088) 775 6.7. WG Consensus: Waiting for Write-Up 777 A document in the "WG Consensus: Waiting for Write-Up" state has 778 essentially completed its development within the WG, and is nearly 779 ready to be sent to the IESG for publication. The last thing to be 780 done is the preparation of a protocol write-up by the Document 781 Shepherd. The IESG requires that a protocol write-up be completed 782 before publication of an I-D is requested. 784 An I-D in the "WG Consensus: Waiting for Write-Up" state SHALL 785 remain in this state until the WG Chair (or Delegate) moves the 786 document to a different state. (R-089) 788 The Datatracker SHOULD be configurable to send an e-mail to a WG's 789 Chairs and Delegates after a specified period of time to remind or 790 'nudge' them to check the status of the Document Shepherd's write-up 791 for an I-D. (R-090) This feature SHOULD look and feel similar to 792 the way that Requirements R-064 to R-067 inclusive are implemented. 793 (R-091) 795 6.8. Submitted to IESG for Publication 797 This state describes a WG document that has been submitted to the 798 IESG for publication and that has not been sent back to the WG for 799 revision. An I-D in this state may be under review by the IESG, or 800 it may have been approved and be in the RFC Editor's queue, or it 801 may have been published as an RFC. Other possibilities exist too. 802 The document may be "Dead" (in the IESG state machine) or in a "Do 803 Not Publish" state. 805 The Datatracker SHOULD look for the presence of WG I-D status 806 annotation tags when a WG draft is moved into this state. If there 807 are any tags that have not been cleared or reset, the Datatracker 808 SHOULD encourage the WG Chairs (or Delegates) in real-time to reset 809 or clear any extraneous annotation tags. (R-092) 811 6.9. Revised I-D Needed (annotation tag) 813 After an I-D is submitted to the IESG, it may be judged to need 814 revision before it can be published as an RFC. An AD or the IESG as 815 a whole may return a document to a WG for revision. 817 An I-D that needs revision may be identified when the Responsible AD 818 appends the "Revised I-D Needed" annotation tag to the IESG state of 819 the I-D. 821 If an AD or the IESG as a whole sends an I-D back to a WG for 822 revision (e.g. as described in Section 3.2 of [WGDRAFTS]), the WG's 823 Chairs may decide to change the WG state of the I-D from "Submitted 824 To IESG For Publication" to a different state and to append one or 825 more WG I-D status annotation tags to the I-D (e.g. per Sections 826 4.3.8 or 4.3.9 of [WGDRAFTS]). 828 The Datatracker SHALL allow, but not require, the WG Chair or 829 Delegate who attaches a "Revised I-D Needed" annotation tag to the 830 WG status of an I-D to indicate the number of weeks they expect it 831 will take for a revised document to be produced (R-093). The 832 Datatracker should also prompt the user to consider changing the WG 833 state of the I-D from "Submitted to IESG for Publication" to 834 something else (e.g. Parked WG Document, WG Document, Waiting for WG 835 Chair Go-Ahead). (R-094) 837 If a revised version of the I-D is not submitted to the WG before 838 the time specified in R-093 elapses, the Datatracker SHALL send an 839 e-mail to the WG's Chairs and Delegates to remind or 'nudge' them to 840 follow-up on the revisions to the document. (R-095) 842 The Datatracker SHALL automatically reset or clear the "Revised I-D 843 Needed" annotation tag attached to the WG status of an I-D when a 844 revised version of that I-D is posted. (R-096) 846 7. Automatic State Changes for I-Ds 848 To reduce the amount of information that WG Chairs and Delegates 849 need to input to the Datatracker, the tool must automatically 850 generate the following WG state transitions: 852 - The Datatracker will move a version-00 I-D into the "WG Document" 853 state when a WG Chair approves the posting of an I-D that includes 854 the string '-ietf-' in its filename (as specified in Requirement 855 R-070; and 857 - The Datatracker SHALL transition a draft into the WG state called 858 "Submitted To IESG For Publication" at the same time that the I-D 859 is moved into the "Publication Requested" state in the IESG state 860 machine by an AD or the IETF Secretariat. (R-097) 862 8. WG I-D Status Change Reporting Requirements 864 Everyone with 'write' access to WG I-D status information SHALL be 865 able to obtain a summary display of all status changes made to the 866 WG I-Ds that *they* are responsible for, from the present time 867 backwards, split by pages, after successfully logging-on to the 868 Datatracker. (R-098) 870 The Datatracker SHOULD provide a convenient way for WG Chairs to 871 obtain a summary of all WG I-D status changes made on their behalf 872 by their Delegates, from the present time backwards, and split by 873 pages. (R-099) 875 The Datatracker SHALL send an e-mail message to the authors of an 876 I-D and to the Chairs and Delegates of the WG the I-D is associated 877 with, whenever the WG status of the I-D is updated; the contents of 878 the e-mail SHALL provide details about the change in the WG status 879 of the document (e.g. the new state the I-D has been moved to and/or 880 the names of any newly set or reset I-D status annotation tags), the 881 date of the change in status, and an indication of who (or which 882 entity) caused the change to the WG status of the I-D. (R-100) 884 9. WG I-D Status Reporting Requirements 886 The Datatracker SHALL provide everyone with a convenient way to 887 query the status of every document in an IETF WG and to see a 888 display of the current status of some or all of the documents in the 889 WG, including the Document Shepherd protocol write-ups for I-Ds that 890 have been submitted to the IESG and the names of the Document 891 Shepherds. (R-101) 893 The Datatracker SHALL also provide everyone with the ability to 894 search for the status of documents written by a specific author, or 895 I-Ds in a specific WG I-D state or having a specific "Intended 896 Maturity Level", or having a specific annotation tag attached. 897 (R-102) 899 The Datatracker's existing I-D status display pages SHOULD be 900 modified to display at least the metadata and status information for 901 an I-D that is associated with a WG as shown in the following sample 902 page: (R-103) 904 ----------------------------------------------------------------- 906 Document stream: IETF 907 I-D availability status: Active / Expired / Withdrawn / RFC / 908 Replaces / Replaced by I-D or RFC (if 909 applicable) 910 Last updated: year-mm-dd (e.g. 2010-11-18) 911 IETF WG status: * Applicable WG state & name of WG or WGs 912 Intended RFC status: ** Informational / Experimental / etc. 913 Document shepherd: *** Name of Document Shepherd (if assigned) 914 IESG status: **** Name of applicable IESG state 915 Responsible AD: Name of the Responsible AD 917 ----------------------------------------------------------------- 919 * The "IETF WG status" SHALL display the current WG state of 920 the I-D and the WG that the I-D is associated with, and any 921 I-D status annotation tags that are currently set. (R-104) 923 ** The "Intended RFC status" for I-Ds in the WG state called 924 "Adopted for WG Info Only" SHOULD be displayed as "None". 925 (R-105) 927 ** The field called "Intended RFC status" SHOULD be renamed to 928 "RFC status" when the Datatracker displays the status of a 929 document that has been published as an RFC. (R-106) 931 *** This field SHOULD display the name of the person (or e-mail 932 address of the person) designated as the Document Shepherd 933 for the I-D, or be left blank if a Document Shepherd has 934 not yet been designated. (R-107) 936 **** This field SHALL display the current IESG status of the 937 document or the word "None" for documents that are not yet 938 being tracked by the IESG. (R-108) 940 10. Error Handling Requirements 942 Errors with respect to inputting or updating the status of a WG 943 document are possible. 945 Per Requirement R-009, the creation of new or updated status 946 information cannot erase, overwrite or cause the deletion of any 947 previously entered document status change history information. 949 Errors in data entry by a WG Chair or Delegate should be corrected 950 by a WG Chair or a Delegate taking action to update any erroneous 951 status information in the Datatracker with correct information, so 952 that the correct status of the I-D is displayed. For example, a 953 document that was accidentally placed into the wrong state can be 954 moved into the correct state by the WG Chair (or Delegate), and a 955 comment should be entered into the document's status change history 956 log to explain what happened. 958 11. Security Considerations 960 This document does not propose any new Internet mechanisms, and has 961 no security implications for the Internet. 963 This document does however contains specific requirements to add 964 features to the IETF Datatracker to make it possible for a greater 965 number of users to input and/or update status information about I-Ds 966 associated with IETF WGs. Enhancing the Datatracker may create an 967 opening for new denial-of-service (DoS) attacks and/or attempts by 968 malicious users to corrupt the information in the WG document status 969 database. 971 This document does not propose any specific requirements to mitigate 972 DoS attacks on the Datatracker. 974 12. IANA Considerations 976 This document does not require any new number assignments from IANA, 977 and does not define any new numbering spaces to be administered by 978 IANA. 980 RFC-Editor: Please remove this section before publication. 982 13. References 984 13.1. Normative References 986 [WGDRAFTS] Juskevicius, E., "Definition of WG Document States", 987 work in process, draft-ietf-proto-wgdocument-states-10, 988 October 2010. 990 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 991 Requirement Levels', RFC 2119, March 1997. 993 [RFC4858] Levkowetz, H., et al., "Document Shepherding from 994 Working Group Last Call to Publication", RFC 4858, 995 May 2007. 997 [RFC2418] Bradner, S., Ed., "IETF Working Group Guidelines and 998 Procedures", BCP 25, RFC 2418, September 1998. 1000 13.2. Informative References 1002 [IDTRACKER] "The IETF Datatracker tool", Web Application: 1003 https://datatracker.ietf.org/, September 30, 2010. 1005 [IESGIDSM] "Diagram of Main I-D States", Web Application: 1006 https://datatracker.ietf.org/images/state_diagram.gif, 1007 September 30, 2010. 1009 [TRCKREQTS] Levkowetz, H., and Mankin, A., "Requirements on I-D 1010 Tracker Extensions for Working Group Chairs", 1011 draft-ietf-proto-wgchair-tracker-ext-03, 1012 February 8, 2007. 1014 14. Acknowledgments 1016 The author would like to thank Henrik Levkowetz and Allison Mankin 1017 for writing the original I-D [TRCKREQTS] that contained many good 1018 ideas and served as a foundation for this document. 1020 The author would also like to thank Henrik Levkowetz, Alfred Hoenes, 1021 Paul Hoffman and Subramanian (SM) Moonesamy for their ongoing 1022 support during the writing of this document. Many of their comments 1023 and suggestions have been used by the author to revise and improve 1024 this document. 1026 The author also offers his gratitude to Russ Housley, Scott Bradner, 1027 Robert Sparks, Spencer Dawkins, and the WG Chairs and other IETF 1028 participants at the wgdtspec BOF at IETF 77 for their inputs, 1029 comments and suggestions, and Lars Eggert, Tim Polk, Robert Sparks, 1030 Ralph Droms, Adrian Farrel, Alexey Melnikov and Sean Turner for 1031 their comments, suggestions and DISCUSS points on the penultimate 1032 draft version of this document. 1034 This document was initially prepared using 2-Word-v2.0.template.dot. 1036 Author's Address 1038 Ed Juskevicius 1039 TrekAhead 1040 PO Box 491, Carp, ON 1041 CANADA 1043 Email: edj.etc@gmail.com