Proto E. Juskevicius Internet Draft TrekAhead Intended status: Informational June 15, 2010 Expires: December 15, 2010 Requirements to Extend the Datatracker for WG Chairs and Authors draft-juskevicius-datatracker-wgdocstate-reqts-04.txt Status of this Memo This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html This Internet-Draft will expire on December 15, 2010. Copyright Notice Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Juskevicius Expires December 15, 2010 [Page 1] Internet-Draft WG Datatracker Requirements June 2010 Abstract This document specifies requirements for new functionality to be added to the IETF Datatracker tool to make it possible for Working Group (WG) Chairs and their delegates to input and update the status of WG documents. After the functionality is implemented, WG Chairs, WG document authors and all other IETF participants will have access to more information about the WG status history, current state, and progression of IETF WG documents from their earliest stages. Table of Contents 1. Introduction...................................................3 2. Conventions used in this document..............................3 3. General requirements...........................................4 4. Privilege and Access Control requirements......................6 4.1. For everyone..............................................6 4.2. For IETF Working Group Chairs.............................6 4.3. For Delegates of IETF WG Chairs...........................7 4.4. For WG Document Shepherds.................................7 4.5. For the Responsible Area Director.........................9 4.6. Role of the IETF Secretariat in granting permissions......9 5. Inputting and updating WG document status information..........9 5.1. WG Document States........................................9 5.2. WG Document Status Annotation Tags.......................10 5.3. WG document Protocol Write-ups...........................11 6. Special requirements for some WG I-D states and conditions....11 6.1. Candidate WG Document....................................11 6.2. Adopted by a WG..........................................14 6.3. Not Adopted by a WG......................................15 6.4. WG Document..............................................16 6.5. In WG Last Call..........................................16 6.6. WG Consensus: Waiting for Write-Up.......................17 6.7. Submitted to IESG for Publication........................18 6.8. Revised I-D Needed (annotation tag)......................18 7. WG Status of I-Ds that are not updated by Chairs or Delegates.18 8. WG document status change reporting requirements..............19 9. WG document status reporting requirements.....................20 10. Error handling requirements..................................20 11. Security Considerations......................................20 12. IANA Considerations..........................................21 13. References...................................................21 13.1. Normative References....................................21 13.2. Informative References..................................21 14. Acknowledgments..............................................21 Juskevicius Expires December 15, 2010 [Page 2] Internet-Draft WG Datatracker Requirements June 2010 1. Introduction The IETF Datatracker is a web-based system for managing information about Internet-Drafts (I-Ds), RFCs, IPR disclosures, and several other important aspects of the IETF process. [IDTRACKER] The Datatracker can be used to obtain a lot of information about the status of any I-D that has been sent to the IESG for evaluation. In contrast, the tool can only report on the availability status (e.g., Expired, Active, Replaced, Withdrawn, published as an RFC) of an I-D that has not been sent to the IESG. [WGDRAFTS] Document authors and other IETF participants have asked for more visibility into the status and progression of WG I-Ds. This document specifies requirements to extend the Datatracker to make it possible for IETF WG Chairs and their delegates to indicate the status of documents adopted by their WGs with more precision than is currently possible. After the requirements are implemented, the Datatracker will be able to track and display more information about the status, history and progression of every I-D associated with an IETF WG. 2. Conventions used in this document The phrase "I-D associated with an IETF WG" is used throughout this document. It is intended to describe all of the I-Ds that have been adopted by an IETF WG and every I-D which is being considered for adoption by a WG. An I-D having a filename that contains the string "draft-ietf-" followed by a WG acronym is almost always a WG document, however this file naming convention is not always followed by document authors. An individual submission I-D that is being considered for adoption by a WG may have a filename that includes the author's name and the WG acronym. Both are to be considered as being "associated with an IETF WG" for the purposes of this document. The phrase "WG document" is used as a synonym for a "WG I-D" in the context of this document. As such, this phrase does not include any other document that may be reviewed, discussed, or produced by an IETF WG. Working Group meeting materials such as Blue Sheets, agendas, jabber logs, scribe's notes, minutes, and presentation slides are not to be considered to be "WG documents" in the context of this document. The phase "WG status of an I-D" is to be interpreted as referring to the document state that an I-D is in as defined in Section 3.3 of [WGDRAFTS]. This phrase is not to be interpreted to include the I-D availability states described in Section 3.1 of [WGDRAFTS], or any Juskevicius Expires December 15, 2010 [Page 3] Internet-Draft WG Datatracker Requirements June 2010 of the document states used to by the IESG to describe the status of I-Ds that they are evaluating. The requirements specified in this document use English phrases ending with "(R-nnn)", where "nnn" is a unique requirement number. When used in the context of the requirements in this document, the key words "MUST", "SHALL", "SHALL NOT", "SHOULD", and "SHOULD NOT" are to be interpreted as described in RFC 2119 [RFC2119]. RFC 2119 defines the use of these key words to help make the intent of standards track documents as clear as possible. The same key words are used in this document to make the meaning of the requirements specified herein as clear as possible. 3. General requirements The Datatracker SHALL be enhanced to provide IETF WG Chairs and the people they designate to act as their delegates with the flexibility to input and update the WG status of some, all, or none of the I-Ds associated with their WGs using all of the WG document states defined in [WGDRAFTS] or a subset of those states. (R-001) The following two examples clarify Requirement R-001: - the Chairs (and their delegates) of a newly chartered IETF WG may choose to input and track the changes to the status of every WG I-D to provide maximum transparency to the IETF community and to manage the progression of the I-Ds in their WG; - the Chairs of a WG that has almost finished its charter milestones may decide to do otherwise. The Datatracker SHALL NOT permit users other than a working group's Chairs (such as for instance other WG Chairs) to update information about the status of a WG's documents through the regular Datatracker interface, unless the privileges to do so have been explicitly delegated to them by one of the WG's Chairs. (R-002) The WG status of an I-D SHALL be tracked using the WG document states, WG document status annotation tags, and intended document maturity levels specified in [WGDRAFTS]. (R-003) The implementation of Requirement R-003 SHALL NOT impair the ability of the Datatracker to track and display the availability state of any I-D (viz. Active, Expired, Replaced, Withdrawn, published as an RFC). (R-004) I-D availability states are described in Section 3.1 of [WGDRAFTS]. Juskevicius Expires December 15, 2010 [Page 4] Internet-Draft WG Datatracker Requirements June 2010 The user-interface to be created to input WG I-D status information into the Datatracker SHOULD have a look and feel that is similar to the interface used by IETF ADs to identify the status of documents under formal evaluation by the IESG. (R-005) Any new pages created to display the WG status of I-Ds to IETF participants SHOULD be designed to have a look and feel that is similar to the pages currently used by the Datatracker to display the status of documents under formal evaluation by the IESG. (R-006) Requirement R-001 provides WG Chairs with the flexibility to input a lot of information into the Datatracker about the WG status of I-Ds associated with their WGs. R-001 also allows WG Chairs to decide *not* to do this. If the Chairs of a WG decide not to input the status of some or all of the I-Ds associated with their WG, the Datatracker will be able to automatically identify I-Ds that have been adopted and have become WG documents in that WG. The tool will also identify I-Ds from that WG that are sent to the IESG for evaluation. The requirements for this feature are specified in Section 7 of this document. The Datatracker SHOULD date and timestamp every update to the WG status of an I-D and use that information when asked to display the WG status change history of an I-D. (R-007) The WG status change history for each I-D SHOULD also identify the person or entity that updated the WG status of the I-D (e.g. one of the WG's Chairs, a delegate, an AD, the System, the IETF Secretariat) and describe the change in the WG status of the I-D (e.g. "WG State changed from 'a' to 'b'", "Document Annotation Tag 'x' Set (or Reset)", "Document Availability changed from 'j' to 'k'"). (R-008) The inputting or updating of the WG status of an I-D SHALL NOT overwrite any previously archived status change history information for the I-D; every update to the WG status of an I-D MUST be added to the status change history log for the I-D. (R-009) WG document status tracking SHOULD be implemented using a new WG state machine that is separate from Datatracker's existing IESG document status tracking state machine. (R-010) The state that a WG I-D is in, in each state machine, MUST be able to be independently updated by the authorized users of each state machine. (R-011) Juskevicius Expires December 15, 2010 [Page 5] Internet-Draft WG Datatracker Requirements June 2010 4. Privilege and Access Control requirements 4.1. For everyone Every IETF participant must be allowed to view information about the WG status of an I-D without logging on to the Datatracker; everyone SHALL have 'read' access to WG document status information. (R-012) People who need to input, modify or update the WG status of an I-D need 'write' privileges; these users SHALL be required to log-on to the Datatracker using a personal user-id and password (e.g. an IETF tools password) in order to gain 'write' access. (R-013) 4.2. For IETF Working Group Chairs When an IETF WG Chair needs to input or update the WG status of an I-D in one of his or her WGs, the WG Chair SHALL be required to log- on to the Datatracker using a personal user-id and password (e.g., an IETF tools password) in order to gain 'write' access. (R-014) After successfully logging on to the Datatracker, IETF WG Chairs: - SHALL be given full 'read' and 'write' privileges to input and update WG status information for all of the I-Ds associated with their WGs; (R-015) - SHALL be able to use all of the WG document states and status annotation tags defined in [WGDRAFTS] to describe the status of the I-Ds associated with their WGs; (R-016) - SHALL be given the option to select a subset of the WG document states defined in [WGDRAFTS] to be used in their WGs if they do not want to use of all of the predefined WG document states; (R-017) - SHALL NOT be able to create ad hoc WG document states or state names; (R-018) - SHALL NOT be allowed to update or modify information which is not related to the WG status of an I-D (e.g., IANA status, RFC-Editor status, IESG status; (R-019) - SHALL be able to designate one or more people to act as delegates to input and update the WG status of the I-Ds associated with their WGs; (R-020) The identifier for each delegate should be the person's e-mail address; (R-021) - SHALL be able to designate different people to act as delegates for them in a different WG when the same WG Chair is also responsible for the different IETF WG; (R-022) Juskevicius Expires December 15, 2010 [Page 6] Internet-Draft WG Datatracker Requirements June 2010 - SHALL be able to assign a person to be the Document Shepherd for one or more WG I-Ds if this role will not be performed by a WG Chair or a designated delegate; (R-023) The identifier for the Document Shepherd should be the person's e-mail address. (R-024) - SHALL be able to input, upload and edit Document Shepherd protocol write-ups for the I-Ds in their WGs; (R-025) - SHALL be able to review and change their designated delegates and Document Shepherds for the I-Ds in their WGs, one WG at a time. (R-026) 4.3. For Delegates of IETF WG Chairs After successfully logging on to the Datatracker, the delegate of an IETF WG Chair SHALL have the same privileges as the WG Chair to input and update WG document status information, as specified in R-015 to R-019 inclusive, plus R-023 and R-025. (R-027) Per Requirement R-013, every person designated to be the delegate of an IETF WG Chair needs to have their own user-id and password to log-on to the Datatracker. The Datatracker SHOULD alert the WG Chairs, the IETF Secretariat, and the newly designated delegate via e-mail if a person who is newly designated to be a delegate of a WG Chair does not have a personal user-id and password to log-on to the Datatracker. (R-028) The purpose of the e-mail is to alert the WG Chairs that the delegate needs to take action to obtain a personal user-id and password, and to inform the delegate that he/she needs to take action (e.g., to contact the IETF Secretariat) to obtain their own user-id and password for the Datatracker. 4.4. For WG Document Shepherds The IETF document shepherding process and the role of an IETF WG Document Shepherd is described in RFC 4858 [RFC4858]. The requirements in this Section describe the access privileges to be granted to a WG Document Shepherd who is not a WG Chair or a delegate of a WG Chair with the privileges described in Section 4.3. Per Requirement R-013, each person designated to be a Document Shepherd for a WG draft needs to have their own personal user-id and password to log-on to the Datatracker. A Document Shepherd who does not have a personal user-id and password for the Datatracker will need to obtain one (e.g., by contacting the IETF Secretariat). Juskevicius Expires December 15, 2010 [Page 7] Internet-Draft WG Datatracker Requirements June 2010 The Datatracker SHOULD alert the WG Chairs, the IETF Secretariat, and the newly designated Document Shepherd (e.g., via e-mail) when a person newly designated to be a Document Shepherd does not have a personal user-id and password to log-on to the Datatracker. (R-029) The purpose of the e-mail is to alert the Chairs that the Document Shepherd needs to take action to obtain a personal user-id and password, and to inform the Document Shepherd that he/she needs to take action (e.g., to contact the IETF Secretariat) to obtain a personal user-id and password for the Datatracker. Document Shepherds need to be able to upload or input protocol write-ups into the Datatracker for the WG I-Ds assigned to them. They also need to be able to set and reset the WG document status annotation tag called "Doc Shepherd Follow-up Underway" as defined in Section 3.5.12 of [WGDRAFTS] for I-Ds in the "WG Consensus: Waiting for Write-Up" state and, in some cases, for I-Ds in the "WG Document" state. After successfully logging on to the Datatracker, Document Shepherds SHALL have restricted 'write' privileges to upload, input and edit protocol write-ups for the WG I-Ds assigned to them. (R-030) In IETF WGs that use the "WG Consensus: Waiting for Write-Up" state, the Document Shepherds SHALL be allowed to input, upload and edit the protocol write-ups for a documents assigned to them once their I-Ds have progressed into this state. (R-031) In WGs that do not use the "WG Consensus: Waiting for Write-Up" state, the Document Shepherds SHALL be allowed to input, upload and edit the protocol write-ups for documents assigned to them when the I-Ds have progressed into the "Waiting for WG Chair Go-Ahead" state (in WGs that use this state) or for I-Ds in the "WG Document" state (in all other WGs). (R-032) Document Shepherds SHALL also have the ability to set and reset the document status annotation tag called "Doc Shepherd Follow-Up Underway" as defined in Section 3.5.12 of [WGDRAFTS]. (R-033) The "Doc Shepherd Follow-Up Underway" annotation tag will be set to indicate when the Document Shepherd has started work on a write-up for the document. The absence or resetting of this annotation tag may indicate the protocol write-up has not yet been started, or has been put on-hold for some reason, or has been completed. The log of set and reset operations performed on this annotation tag and will indicate the status of the protocol write-up for each WG I-D. Section 5.3 contains additional requirements about how Document Shepherds may enter, upload and edit the protocol write-ups for their WG I-Ds in the Datatracker. Juskevicius Expires December 15, 2010 [Page 8] Internet-Draft WG Datatracker Requirements June 2010 4.5. For the Responsible Area Director After successfully logging on to the Datatracker, IETF ADs SHALL have the same privileges as IETF WG Chairs to input and update WG document status information, to designate delegates, and to assign Document Shepherds. (R-034) IETF ADs must also retain their normal privileges to input and update the IESG status of I-Ds they are responsible for. Each IETF AD SHALL have privileges specified in Requirement R-034 for every WG in his or her Area. (R-035) 4.6. Role of the IETF Secretariat in granting permissions Before granting permissions to update WG document status settings to a person who does not have them, the IETF Secretariat should verify that the person requesting the permissions is a WG Chair or an AD and has been delegated the authority to update WG document status information by one of the Chairs of the WG or an AD. In order to update the status of WG I-Ds, a user will need to be granted the permissions to perform WG document status changes in general, and be authorized (e.g. delegated) to update the WG status of the I-Ds in an IETF WG by one of the WG's Chairs or an AD. 5. Inputting and updating WG document status information 5.1. WG Document States Requirement R-003 specifies that the WG state of an I-D must be described using the document states defined in Section 3.3 of [WGDRAFTS]. When a WG Chair or delegate logs-on to the Datatracker to input or change the WG state of an I-D, the Datatracker should display the current state of the I-D, the length of time the document has been in its current state, the amount of time the I-D may continue to remain in its current state (if this information is available), and the most likely next state (or states) for the I-D. (R-036) The Datatracker SHALL use the WG document state machine illustrated in Section 3.4 of [WGDRAFTS] to identify the 'most likely next state' (or states) for an I-D that is associated with an IETF WG. (R-037) If the Chairs of a WG have specified that only a subset of the WG document states may be used to describe the status of I-Ds in their WGs (per Requirement R-017), the Datatracker SHALL update its WG document state machine for that WG accordingly, and use the updated state machine to identify the 'most likely next state' (or states) needed to comply with Requirement R-037 for that WG. (R-038) Juskevicius Expires December 15, 2010 [Page 9] Internet-Draft WG Datatracker Requirements June 2010 After displaying the information specified by R-036 (and R-038 if applicable), the Datatracker SHALL prompt the WG Chair or delegate to select a next state for the I-D and to enter some text to explain the state change for the I-D's status change history. (R-039) As a general principle, the Datatracker SHOULD always prompt the person who updates the WG status of an I-D to input some text to be archived in the status change history log of every I-D. (R-040) 5.2. WG Document Status Annotation Tags WG I-D status annotation tags may be used to describe conditions that affect a document (e.g., why a document is in the state it is in) or to indicate actions needed to progress the document. Annotation tags do not change the state of WG documents. WG document status annotation tags may be used one at a time or in combination to provide information about the status of a WG I-D in any state, if it makes sense to do so. Section 3.5 of [WGDRAFTS] describes all of the WG document status annotation tags to be added to the Datatracker. The Datatracker SHALL allow WG Chairs and their delegates to set and reset all of the WG I-D status annotation tags defined in Section 3.5 of [WGDRAFTS] for every I-D associated with their WGs. (R-041) When a WG Chair, Delegate or Document Shepherd logs into the Datatracker to set or reset one or more WG document status annotation tags, the Datatracker SHOULD display a summary of all annotation tag set/reset operations to date, per document, from the present time backwards, split by pages, and then guide the user to select one (or more) annotation tags to be set or reset. (R-042) Note that WG Document Shepherds may only set and reset the "Doc Shepherd Follow-up Underway" annotation tag as specified by Requirement R-033. The summary of annotation tag set/reset operations (required by R-042) SHOULD include the date when each annotation tag was set or reset, the identity of the person or entity that set or reset each tag, and any text (e.g., from the document's status change history log) that was input when each tag was set or reset. (R-043) The Datatracker SHOULD allow more than one annotation tag to be set or reset per log-on, and the Datatracker SHOULD prompt the user to input some text to explain why each annotation tag is being set or reset. (R-044) Juskevicius Expires December 15, 2010 [Page 10] Internet-Draft WG Datatracker Requirements June 2010 5.3. WG document Protocol Write-ups The IESG requires a protocol write-up to be prepared for a WG I-D before the I-D may be sent to the IESG for evaluation. Requirements R-031 and R-032 identify the WG state than an I-D must be in before a Document Shepherd may begin to input, upload and/or edit a protocol write-up for a WG I-D into the Datatracker. When a Document Shepherd logs into the Datatracker to upload, input or edit the protocol write-up for a WG I-D assigned to him or her, the Datatracker SHOULD display a list of every WG I-D that the Document Shepherd is responsible for and a summary of the current status and history of changes made to the protocol write-up for each I-D, from the present time backwards, split by pages, and split by WGs (if the same person is a Document Shepherd in more than one WG). (R-045) After displaying the information required by R-045, the Datatracker must allow Document Shepherds to upload, input or edit protocol write-ups for their I-Ds if the conditions specified in Requirements R-031 and R-032 are met. The tool SHALL provide each Document Shepherds with a user-interface to capture their protocol write-ups for the I-Ds they are responsible for, and to facilitate setting and resetting the "Doc Shepherd Follow-up Underway" annotation tag for those I-Ds. (R-046) WG Chairs SHOULD be able to access the Document Shepherd user- interface and call-up a display of the same WG I-D protocol write-up status information that the Datatracker gives to each of a WG Chair's designated Document Shepherds. (R-047) This will enable WG Chairs to mentor new Document Shepherds and it will enable WG Chairs to review the workload assigned to each Document Shepherd. WG Chairs and delegates may designate themselves to act as Document Shepherds for some or all of the I-Ds in their own WGs. In the WGs where this happens, the Datatracker SHOULD ask the WG Chairs and/or delegates which role they are playing when the log in, in order to display the most appropriate user-interface for that role. (R-048) 6. Special requirements for some WG I-D states and conditions 6.1. Candidate WG Document The "Candidate WG Document" state may be used to describe an I-D that is being considered for adoption by an IETF WG. An I-D in this state has not yet achieved consensus, preference or selection in a working group. Juskevicius Expires December 15, 2010 [Page 11] Internet-Draft WG Datatracker Requirements June 2010 This state may be used to describe: - an I-D that someone has asked to be considered by a WG, if the WG Chair has agreed with the request; - an I-D that the WG Chair asked an author to write; or - an I-D listed as a 'candidate draft' in the WG charter. The Datatracker SHALL allow an IETF WG Chair or delegate to identify an I-D as a "Candidate WG Document" for her or his WG if the I-D has not yet been adopted by any IETF WG, is not expired and has not been withdrawn or replaced by another I-D. (R-049) The Datatracker should not allow a document that is expired, withdrawn, replaced or already adopted by an IETF WG to be moved into the "Candidate WG Document" state. It is not uncommon for an author to 'shop' a document to multiple WGs hoping to get the draft adopted somewhere. The Datatracker SHALL allow a document to be in the "Candidate WG Document" state for more than one WG at a time if the conditions specified in R-049 are met. (R-050) Requirements R-051 to R-064 inclusive are intended to minimize the time needed by WG Chairs and/or their delegates to manage documents placed into the "Candidate WG Document" state. The objectives are as follows: - a WG Chair (or delegate) should be able to identify an I-D as a candidate for adoption in her or his WG if Requirement R-049 is met; - a WG Chair (or delegate) should not have to update the status of a candidate document again unless he/she decides to adopt the I-D as a WG document; and - a second (or third, or fourth) WG Chair or delegate who takes an interest in the same candidate document should not create a problem or a coordination headache for any other WG Chair or delegate. The code to be written to track documents in the "Candidate WG Document" State should be designed to operate as follows: - the first WG Chair (or delegate) to move an I-D into the candidate state shall specify the maximum length of time the I-D may be in the candidate state; - the second (or third or fourth ...) WG Chair or delegate to identify the same document as a candidate in his or her WG will be Juskevicius Expires December 15, 2010 [Page 12] Internet-Draft WG Datatracker Requirements June 2010 informed of the current status of the document, and will be given an opportunity to extend the period of time that the I-D may remain in the candidate state; and - the Datatracker will automatically change the state of the document to "Not Adopted by a WG" when time runs out, unless someone logs-on to the Datatracker and moves the document into some other state first. Requirements R-051 to R-064 provide detailed specifications for the implementation of this functionality. The first WG Chair (or delegate) to move an I-D into the "Candidate WG Document" state SHALL be required to specify a length of time that the I-D may remain in this state. (R-051) The maximum length of time that an I-D may remain in the "Candidate WG Document" state SHOULD be specified as a number of weeks. (R-052) Before a different WG Chair (or delegate) is allowed to identify the same document as a candidate for adoption in his or her (different) WG, the Datatracker SHALL indicate that the document is already a candidate in another IETF WG and display the name of the other WG and the amount of time remaining that the document may remain in the candidate state. (R-053) If, after reviewing this information, the different WG Chair (or delegate) decides to proceed, the Datatracker SHALL allow the WG Chair (or delegate) to identify the I-D as a "Candidate WG Document" for their working group, and to extend the number of weeks that the document may remain in the candidate state if more time is required. (R-054) - If the different WG Chair tries to extend the time beyond the expiry date of the I-D, the Datatracker SHALL adjust the time to coincide with the expiry date of the I-D and then inform the WG Chair that the time that an I-D may remain in the "Candidate WG Document" state may not be allowed to extend beyond the date the document "Expires" (as specified the cover page of the I-D). (R-055) - After the new date is entered and confirmed, the Datatracker SHALL send an e-mail to the WG Chairs and delegates of every other WG (in which the document is already a candidate) to inform them the document has become a candidate in another WG and that the time the I-D may remain as a candidate has been extended to a new date of (whatever the new date is). (R-056) - If the time remaining is not extended by the different WG Chair or delegate, the (already running) timer SHALL continue to count-down without interruption. (R-057) In this case, the Datatracker SHALL send an e-mail to the WG Chairs and delegates of every other WG (in Juskevicius Expires December 15, 2010 [Page 13] Internet-Draft WG Datatracker Requirements June 2010 which the document is already a candidate) to inform them the document has become a candidate in yet another WG and to confirm that the amount of time the I-D may remain as a candidate has not been changed. (R-058) One week before expiry of the timer, the Datatracker SHALL send a nudge via e-mail to every WG Chair and delegate in which the I-D is a "Candidate WG Document". (R-059) The e-mail will alert everyone the I-D is still in the candidate state, and inform everyone that the Datatracker will automatically move the I-D into the "Not Adopted by a WG" state when time expires unless someone moves it to a different state first. (R-060) If a "Candidate WG Document" is adopted by a WG before the timer expires (e.g., if the state of the document is changed to "Adopted by a WG"), the Datatracker SHALL cancel the timer and send an e-mail to the author of the I-D and to every WG Chair and delegate who had an interest in the document to inform them that the I-D has been adopted by the (insert name of the WG here) WG. (R-061) If a document is not adopted by any WG when time expires, the I-D will still be in the "Candidate WG Document" state. In this case, the Datatracker SHALL automatically move the document into the "Not Adopted by a WG" state and send an e-mail to every WG Chair and delegate who was interested in the document to announce the document was not adopted and that its state has been changed automatically. (R-062) If a document is a "Candidate WG Document" in only one WG, the Datatracker shall allow the Chairs of that WG to change the state of the candidate I-D to "Not Adopted by a WG" at any time. (R-063) The Datatracker SHALL NOT allow a document that is a candidate in more than one WG to be moved into the "Not Adopted by a WG" state before the timer specified in R-051 and R-052 expires. (R-064) 6.2. Adopted by a WG The "Adopted by a WG" state should be used to identify an individual submission I-D that an IETF WG has agreed to adopt as one of its WG documents. The purpose of this state is to provide a clear indication of when an individual submission I-D is adopted by a WG, and to help capture correct "Replaced by" information for the status change history log of the individual submission I-D. This state is needed because the Datatracker uses the filename of an I-D as a key to access its archive of status change history information for each I-D; the filename of an I-D that is adopted by a WG will typically be changed Juskevicius Expires December 15, 2010 [Page 14] Internet-Draft WG Datatracker Requirements June 2010 after the document is adopted but before the I-D submitted as a new version-00 I-D and approved for posting as a "WG Document". The Datatracker shall allow an individual submission I-D to be moved into the "Adopted by a WG" state if the I-D is not expired and it has not been withdrawn, been replaced by another I-D, or been adopted by another IETG WG. (R-065) If a WG Chair or delegate moves an I-D into the "Adopted by a WG" state, the Datatracker shall announce the state change via e-mail as specified by R-061. 6.3. Not Adopted by a WG The purpose of the "Not Adopted by a WG" state is to identify an I-D that was considered for adoption by one or more IETG WGs but was not adopted by any WG. Requirements R-059, R-060 and R-062 specify that the Datatracker shall automatically transition an I-D from the "Candidate WG Document" state into the "Not Adopted by a WG" state when it is clear that no IETF WG has adopted the I-D. Per Requirements R-007 and R-008, the Datatracker must update the document change status history log of an I-D that is transitioned into the "Not Adopted by a WG" state. The status information to be written into the I-D's history log SHALL include the date the I-D was determined to be "not adopted", and the name of each IETF WG that the I-D was a candidate for and that did not adopt the I-D. (R-066) Notwithstanding the aforementioned, a different IETF WG may decide to adopt an I-D after it has entered the "Not Adopted by a WG" state. The Datatracker SHALL allow a WG Chair or delegate to move an I-D that is in the "Not Adopted by a WG" state into the "Adopted by a WG" state if the I-D has not expired, been withdrawn, or been replaced by another I-D. (R-067) The status information to be written into the history log in this case SHALL include the date the I-D was adopted, the name of the IETF WG that adopted the I-D. (R-068) Requirement R-009 specifies that updates to the WG status of an I-D shall not overwrite previously archived document status history information for the I-D. This means that the adoption of an I-D that was previously not adopted by one or more different WGs will not be deleted from the status history log of the I-D. All document status change history information for the I-D will be preserved, even when the I-D is revised and subsequently approved for posting as a new version -00 WG I-D with a new filename (viz. a filename including the string "draft-IETF-" followed by a WG acronym). Juskevicius Expires December 15, 2010 [Page 15] Internet-Draft WG Datatracker Requirements June 2010 6.4. WG Document The "WG Document" state describes an I-D that has been adopted by an IETF WG and is being actively developed by the WG. The Datatracker SHALL automatically place a new version-00 I-D into the "WG Document" state if a WG Chair approves the submission of the I-D for posting in the IETF document repository and if the filename of the I-D includes the string "draft-ietf-wgname-". (R-069) The Datatracker SHOULD also prompt the WG Chair to input, confirm or correct the filename of the I-D being replaced (if any) by each new version-00 WG I-D when the Chair approves the posting of the new I-D. (R-070) The Datatracker SHALL allow WG Chairs and their delegates to move an I-D into the "WG Document" state from a different document state as defined in Section 3.3 of [WGDRAFTS] if the I-D has not expired, been withdrawn or replaced by another I-D. (R-071) Under normal conditions, it should not be possible for an I-D to be in the "WG Document" state in more than one IETF WG at a time. The Datatracker SHALL NOT allow a WG Chair or delegate to move an I-D into the "WG Document" state in their WG if the I-D is already in this state in a different WG. (R-072) The WG Chair (or delegate) who moves or approves an I-D to be in the "WG Document" state for the first time SHALL be required to indicate the "Intended Maturity Level" for the document, as defined in Section 3.6 of [WGDRAFTS] if the Datatracker cannot automatically determine this information for some reason. (R-073) The Datatracker SHALL allow the "Intended Maturity Level" to be changed after first being set. (R-074) A WG document may be transferred from one WG to another WG by a Responsible Area Director. The Datatracker SHALL allow an IETF Area Directors to transfer an I-D from one IETF WG to a different WG. (R-075) 6.5. In WG Last Call A document "In WG Last Call" is an I-D for which a Working Group Last Call (WGLC) has been issued, and is in progress. Note that WG last calls are an optional part of the IETF WG process, per Section 7.4 of RFC 2418 [RFC2418]. If a WG Chair decides to conduct a WGLC on an I-D, he/she may use the "In WG Last Call" state to track the progress of the WGLC. The Chair SHOULD be able configure the Datatracker to send a WGLC Juskevicius Expires December 15, 2010 [Page 16] Internet-Draft WG Datatracker Requirements June 2010 message to one or more mailing lists when an I-D in moved into this state. (R-076) The WG Chair should be able to select a different set of mailing lists for each document because some documents may need coordination with other WGs. (R-077) The WG Chair (or delegate) who moves an I-D into the "In WG Last Call" state SHALL be required to specify the number of weeks that the document may remain in this state. (R-078) The number of weeks SHALL be able to be changed after first being set. (R-079) A document that is in the "In WG Last Call" state SHALL remain in this state until a WG Chair or delegate moves the I-D into a different WG state. (R-080) WG Chairs and their delegates SHALL be able to configure the Datatracker to send an e-mail after the number of weeks specified by R-078 to remind or 'nudge' them to conclude the WGLC and to determine a next state for the I-D. (R-081) It is possible that a WGLC may lead directly back into another WGLC for the same document. For example, an I-D that completed a WGLC as an "Informational" document may need another WGLC if a decision is taken to convert the I-D into a standards track document. The Datatracker SHOULD allow this to occur. (R-082) 6.6. WG Consensus: Waiting for Write-Up A document in the "WG Consensus: Waiting for Write-Up" state has essentially completed its development within the WG, and is nearly ready to be sent to the IESG for publication. The last thing to be done is the preparation of a protocol write-up by the Document Shepherd. The IESG requires that a protocol write-up be completed before publication of the I-D is requested. A document in this state SHOULD remain in this state until the WG Chair (or delegate) moves the document to a different state. (R-083) The Datatracker SHOULD be configurable to send an e-mail to the WG Chair after a specified period of time to remind or 'nudge' the WG Chair to look into the status of the Document Shepherd's write-up. (R-084) The Document Shepherd for an I-D that is moved into this state SHALL be alerted of the state change via e-mail. (R-085) The e-mail will 'nudge' the Shepherd to develop a protocol write-up for the I-D. If a timer was configured per R-083, the Datatracker shall send an e- mail message to the Document Shepherd one week before expiry of the timer to nudge the Document Shepherd and warn that a WG Chair may be calling in a week's time if a write-up is completed for the I-D by that time. Juskevicius Expires December 15, 2010 [Page 17] Internet-Draft WG Datatracker Requirements June 2010 The Datatracker shall send a message to the Chairs and delegates of a WG when a Document Shepherd enters a protocol write-up for a WG I- D into the Datatracker, and when the Document Shepherd indicates that he/she is satisfied with the write-up. (R-086) 6.7. Submitted to IESG for Publication This state describes a WG document that has been submitted to the IESG for publication and that has not been sent back to the WG for revision. Under normal conditions, an I-D that has reached this state will have finished it tenure as a WG document. The Datatracker SHOULD look for the presence of annotation tags when a WG document is moved into this state. If there are any tags that have not been cleared or reset, the Datatracker SHOULD send an e- mail to the WG Chairs (and delegates) to suggest they clear any extraneous annotation tags. (R-087) 6.8. Revised I-D Needed (annotation tag) After an I-D is submitted to the IESG, it may be judged to need revision before it can be published as an RFC. An AD or the IESG as a whole may return a document to a WG for revision. A document that needs revision may be identified when the WG Chair, delegate, or the Responsible AD logs-on to the Datatracker to append one of the "Issue Raised - Revision Needed" annotation tags to the status of the document. The Datatracker SHALL require the person who attaches one of these annotation tags to a document to indicate the number of weeks that it should take for the revised document to be produced (R-088). The Datatracker should also prompt the user to consider changing the WG state of the I-D from "Submitted to IESG for Publication" to something else (e.g., Parked WG Document, WG Document, Waiting for WG Chair Go-Ahead). (R-089) The Datatracker should be programmed to send an e-mail to the WG's Chairs and delegates after the number of weeks specified in R-087 to remind or 'nudge' the WG Chairs and delegates to follow-up on the revisions to the document, unless a revised document is submitted before the time elapses. (R-090) 7. WG Status of I-Ds that are not updated by Chairs or Delegates Requirement R-001 provides each IETF WG Chair with the freedom to decide to use all or just some of the WG document states defined in [WGDRAFTS] to indicate the status and progression of documents in his or her working group. The same requirement also allows each IETF WG Chair to decide to *not* log-on to the Datatracker to manually input or update the status of drafts in her/his WG. Juskevicius Expires December 15, 2010 [Page 18] Internet-Draft WG Datatracker Requirements June 2010 The Datatracker must allow for the possibility that some WG Chairs will not manually input or update the status of some WG drafts. To provide some visibility into the status of WG documents that are not manually tracked by a WG Chair or delegate, the Datatracker must generate the following state transitions automatically for all I-Ds associated with an IETG WG: - Per R-069, the Datatracker will automatically transition version-00 I-Ds into the "WG Document" state when a WG Chair approves the posting of an I-Ds; - Per R-004, The Datatracker will indicate the availability status of an I-D that has not been withdrawn or replaced and that is in the "WG Document" state to be "Expired" if the document is more than six months old, and "Active" if the document is less than six months old; - The Datatracker SHALL NOT automatically transition an I-D from the "WG Document" state to any other state in the WG state machine unless the I-D is placed into the "Publication Requested" state in the IESG state machine by an AD or the IETF Secretariat. (R-091) - The Datatracker SHALL automatically transition a WG I-D into the "Submitted to IESG for Publication" state (in the WG state machine) if the I-D is in some other WG state and if the I-D is moved into the "Publication Requested" state in the IESG state machine. (R-092) 8. WG document status change reporting requirements Everyone with 'write' access to WG document status information SHOULD be able to obtain a summary display of all status changes made to the WG documents they are responsible for, from the present time backwards, split by pages, after successfully logging-on to the Datatracker. (R-093) The Datatracker SHOULD provide a convenient way for WG Chairs to obtain a summary of all WG document status changes made on their behalf by their delegates, from the present time backwards, split by pages, after successfully logging-on to the Datatracker. (R-094) The Datatracker SHOULD send an e-mail message to the authors of an I-D whenever the WG status of their I-D is updated. The contents of the e-mail SHOULD provide details about the change in the status of the document (e.g. the new state the I-D has been moved to and/or the names of any newly set or reset document status annotation tags), the date of the status change, and an indication of who (or which entity) caused the change in WG status. (R-095) Juskevicius Expires December 15, 2010 [Page 19] Internet-Draft WG Datatracker Requirements June 2010 9. WG document status reporting requirements The Datatracker SHALL provide everyone with a convenient way to query the status of every document in an IETF WG and to see a display of the current status of some or all of the documents in the WG, including the Document Shepherd protocol write-ups for I-Ds that have been submitted to the IESG and the names of the Document Shepherds. (R-096) For WGs in which the WG Chairs have decided to only use a subset of the predefined WG document states (per R-017), the Datatracker SHALL indicate which WG document states are being used by that WG. (R-097) The Datatracker SHALL also provide everyone with the ability to search for the status of documents written by a specific author, or I-Ds in a specific WG document state or having a specific 'intended maturity level', or having a specific annotation tag attached. (R-098) 10. Error handling requirements Errors with respect to inputting or updating the status of a WG document are possible. Per Requirement R-009, the creation of new or updated status information cannot erase, overwrite or cause the deletion of any previously entered document status change history information. Errors in data entry by a WG Chair or delegate should be corrected by a WG Chair or a delegate taking action to update any erroneous status information in the Datatracker with correct information, so that the correct status of the I-D is displayed. For example, a document that was accidentally placed into the wrong state can be moved into the correct state by the WG Chair (or delegate), and a comment should be entered into the document's status change history log to explain what happened. 11. Security Considerations This document does not propose any new Internet mechanisms, and has no security implications for the Internet. This document does however contains specific requirements to add features to the IETF Datatracker to make it possible for a greater number of users to input and/or update status information about I-Ds associated with IETF WGs. Enhancing the Datatracker may create an opening for new denial-of-service (DoS) attacks and/or attempts by malicious users to corrupt the information in the WG document status database. Juskevicius Expires December 15, 2010 [Page 20] Internet-Draft WG Datatracker Requirements June 2010 This document does not propose any specific requirements to mitigate DoS attacks on the Datatracker. 12. IANA Considerations This document does not require any new number assignments from IANA, and does not define any new numbering spaces to be administered by IANA. RFC-Editor: Please remove this section before publication. 13. References 13.1. Normative References [WGDRAFTS] Juskevicius, E., "Definition of WG Document States", work in process, draft-ietf-proto-wgdocument-states-07, June 2010. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels', RFC 2119, March 1997. [RFC4858] Levkowetz, H., et al., "Document Shepherding from Working Group Last Call to Publication", RFC 4858, May 2007. [RFC2418] Bradner, S., Ed., "IETF Working Group Guidelines and Procedures", BCP 25, RFC 2418, September 1998. 13.2. Informative References [IDTRACKER] "The IETF Datatracker tool", Web Application: https://datatracker.ietf.org/, June 15, 2010. [TRCKREQTS] Levkowetz, H., and Mankin, A., "Requirements on I-D Tracker Extensions for Working Group Chairs", draft-ietf-proto-wgchair-tracker-ext-03, February 8, 2007. 14. Acknowledgments The author would like to thank Henrik Levkowetz and Allison Mankin for writing the original I-D [TRCKREQTS] that contained many good ideas and served as a foundation for this document. The author would also like to thank Henrik Levkowetz and Alfred Hoenes for their ongoing support during the writing of this document. Many of their detailed comments and suggestions have been used by the author to revise and improve this document. Juskevicius Expires December 15, 2010 [Page 21] Internet-Draft WG Datatracker Requirements June 2010 The author also offers his gratitude to Russ Housley, Scott Bradner, Robert Sparks, Spencer Dawkins, Paul Hoffman, and the WG Chairs and other IETF participants at the wgdtspec BOF at IETF 77 for their inputs, comments and suggestions. This document was initially prepared using 2-Word-v2.0.template.dot. Author's Address Ed Juskevicius TrekAhead PO Box 491, Carp, ON CANADA Email: edj.etc@gmail.com Juskevicius Expires December 15, 2010 [Page 22]