[Docs] [txt|pdf] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01 02 03 04 05 06 07 08 RFC 6175

Proto                                                    E. Juskevicius
Internet Draft                                                TrekAhead
Intended status: Informational                           August 4, 2010
Expires: February 4, 2011


     Requirements to Extend the Datatracker for WG Chairs and Authors
           draft-juskevicius-datatracker-wgdocstate-reqts-05.txt


Abstract

   This document specifies requirements for new functionality to be
   added to the Datatracker tool to make it possible for IETF Working
   Group (WG) Chairs and their delegates to input and update the status
   of WG documents. After this functionality is implemented, WG Chairs,
   document authors and everyone else will have more visibility into
   the status and history of IETF stream documents from their earliest
   stages.

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).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   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."

   This Internet-Draft will expire on February 4, 2011.

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 February 4, 2011                [Page 1]

Internet-Draft       WG Datatracker Requirements            August 2010


Table of Contents

   1. Introduction...................................................2
   2. Conventions used in this document..............................3
   3. General requirements...........................................4
   4. Privilege and Access Control requirements......................5
      4.1. For everyone..............................................5
      4.2. For IETF Working Group Chairs.............................6
      4.3. For Delegates of IETF WG Chairs...........................7
      4.4. For IETF WG Document Shepherds............................7
      4.5. For the Responsible Area Director.........................8
      4.6. Role of the IETF Secretariat in granting permissions......8
   5. Inputting and updating WG document status information..........9
      5.1. WG Document States........................................9
      5.2. WG Document Status Annotation Tags........................9
      5.3. WG Document Protocol Write-ups...........................10
   6. Special requirements for some WG I-D states and conditions....11
      6.1. Candidate WG Document....................................11
      6.2. Adopted by a WG..........................................15
      6.3. Not Adopted by a WG......................................15
      6.4. WG Document..............................................16
      6.5. In WG Last Call..........................................17
      6.6. WG Consensus: Waiting for Write-Up.......................18
      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.19
   8. WG document status change reporting requirements..............20
   9. WG document status reporting requirements.....................20
   10. Error handling requirements..................................21
   11. Security Considerations......................................22
   12. IANA Considerations..........................................22
   13. References...................................................22
      13.1. Normative References....................................22
      13.2. Informative References..................................23
   14. Acknowledgments..............................................23



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 currently 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]


Juskevicius            Expires February 4, 2011                [Page 2]

Internet-Draft       WG Datatracker Requirements            August 2010


   Document authors and others have asked for more visibility into the
   status and progression of IETF Working Group (WG) documents.

   This document specifies requirements to extend the Datatracker to
   make it possible for IETF WG Chairs and their delegates to describe
   the WG status of I-Ds associated with their WGs.  After these
   requirements are implemented, the Datatracker will be able to track
   and display more information about the WG status, history and
   progression of I-Ds associated with IETF WGs.

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 two types of Internet-Drafts:

  - I-Ds that have been accepted as IETF WG documents; and

  - I-Ds that are being considered for adoption by one or more WGs.

   An I-D having a filename that contains the string "draft-ietf-"
   followed by a WG acronym is almost always an IETF WG document and is
   to be interpreted as being an "I-D associated with an IETF WG" for
   the purposes of this document.

   An I-D having a filename that includes the author's name and a WG
   acronym but not the string "-ietf-" may be a candidate for adoption
   by a WG and is also to be interpreted as being an "I-D associated
   with an IETF WG" for the purposes of this document.

   The phrase "WG document" is used as a synonym for "WG I-D" in this
   document.  This phrase should not be interpreted as referring to 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 as "WG documents" in the context of
   this document.

   The phase "WG status of an I-D" is to be interpreted as referring to
   the WG document state that an I-D is in, as defined in Section 3.3
   of [WGDRAFTS].  This phrase does not refer to an I-D's availability
   status (e.g. "Expired", "Active") as described in Section 3.1 of
   [WGDRAFTS], or the IESG state used by IETF Area Directors (ADs) to
   describe the status of an I-D they may be 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"


Juskevicius            Expires February 4, 2011                [Page 3]

Internet-Draft       WG Datatracker Requirements            August 2010


   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 the WG document states and status
   annotation tags defined in [WGDRAFTS]. (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 the WG status of all of the I-Ds associated with
    their WG to provide maximum transparency to the IETF community and
    to manage the progression of the I-Ds;

  - the Chairs (and delegates) of a mature WG (e.g. a WG that is
    nearing the completion of its charter milestones) may decide not to
    manually input the status of their WG I-Ds into the Datatracker.

   The Datatracker SHALL NOT permit users other than a Working Group's
   Chairs (e.g. other WG Chairs) to update the 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 every IETF Stream 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].

   The user-interface to be created for WG Chairs and their delegates
   to use 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 SHOULD be
   designed to have a look and feel that is similar to the pages


Juskevicius            Expires February 4, 2011                [Page 4]

Internet-Draft       WG Datatracker Requirements            August 2010


   currently used by the Datatracker to display the status of I-Ds
   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 the
   I-Ds associated with their WGs.  R-001 also allows WG Chairs to
   decide *not* to do this.

   In order to provide more information about the WG status of every
   IETF stream I-D, the Datatracker needs to be able to automatically
   generate some WG state transitions for every I-D (viz. into the "WG
   Document" state and into the "Submitted to IESG for Publication"
   state).  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 IETF Stream I-D and use that information when it needs
   to display the WG status change history of that 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 status 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 of 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)

   WG document status tracking SHOULD be implemented per-document, not
   per-WG. (R-012)

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-013)




Juskevicius            Expires February 4, 2011                [Page 5]

Internet-Draft       WG Datatracker Requirements            August 2010


   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-014)

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-015)

   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, one WG at a time; (R-016)

  - SHALL be given the flexibility to use any 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-017)

  - SHALL NOT be allowed 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 different WGs when the WG Chairs are also responsible for
    the different IETF WGs; (R-022)

  - SHALL be able to review and change their designated delegates, one
    WG at a time; (R-023)

  - SHALL be able to assign people to be Document Shepherds for one or
    more WG I-Ds if this role will not be performed by a WG Chair or a
    designated delegate; (R-024)  The identifier for each Document
    Shepherd should be the person's e-mail address. (R-025)

  - SHALL be able to input, upload and edit Document Shepherd protocol
    write-ups for the I-Ds in their WGs; (R-026)



Juskevicius            Expires February 4, 2011                [Page 6]

Internet-Draft       WG Datatracker Requirements            August 2010


  - SHALL be able to review and change the people assigned to be
    Document Shepherds in their WGs, one WG at a time. (R-027)

4.3. For Delegates of IETF WG Chairs

   After successfully logging on to the Datatracker, the delegates of
   IETF WG Chairs SHALL have the same privileges as the WG Chairs to
   input and update WG document status information, as specified in
   R-016 to R-019 inclusive, plus R-024, R-026 and R-027. (R-028)

   Per Requirement R-014, delegates of IETF WG Chairs need to have
   their own user-ids and passwords 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-029)
   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 IETF 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-014, 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).

   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-030)
   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.




Juskevicius            Expires February 4, 2011                [Page 7]

Internet-Draft       WG Datatracker Requirements            August 2010


   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.

   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 once the I-Ds
   have entered the "WG Consensus: Waiting for Write-Up" state. (R-031)

   Document Shepherds SHALL also be given 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-032)

   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
   provide some insight into the status of the protocol write-up for
   each WG I-D.

   Section 5.3 describes how Document Shepherds may input, edit or
   upload protocol write-ups for their WG I-Ds into the Datatracker.

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; each IETF AD SHALL have the privileges specified
   in Requirement R-033 for every WG in his or her Area (R-033)

   IETF ADs must also retain their normal privileges to input and
   update the IESG status of I-Ds they are responsible for. (R-034)

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 or
   has been delegated the authority to update WG document status
   information by one of the WG's Chairs or a Responsible 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



Juskevicius            Expires February 4, 2011                [Page 8]

Internet-Draft       WG Datatracker Requirements            August 2010


   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-035)  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-036)

   After displaying the information required by R-036, 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-037)  The Datatracker SHOULD always prompt
   the person who updates or changes the WG state of an I-D to input
   some text for the I-D's status change history. (R-038)

   The Datatracker SHALL allow WG Chairs and their delegates to select
   the next state for an I-D from one of the 'most likely' next states
   described in Requirement R-035, or from any of the other WG document
   states (per Requirement R-017) if needed. (R-039)

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-040)


Juskevicius            Expires February 4, 2011                [Page 9]

Internet-Draft       WG Datatracker Requirements            August 2010


   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-041)
   Note that WG Document Shepherds may only set and reset the "Doc
   Shepherd Follow-up Underway" annotation tag as specified by
   Requirement R-032.

   The summary of annotation tag set/reset operations (required by
   R-041) 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-042)

   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-043)

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.

   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 of the protocol write-up for each I-D from the present time
   backwards, split by pages (if necessary), and split by WGs (if the
   same person is a Document Shepherd for I-Ds in more than one IETF
   WG). (R-044)

   The protocol write-up status summary (required by R-044) SHOULD
   include the date when each upload, input or edit operation was
   performed, the identity of the person who performed the work, and
   whatever descriptive text was input by the person who performed work
   on the protocol write-up. (R-045)

   After displaying the information required by R-044 and R-045, the
   Datatracker SHALL provide Document Shepherds with a user-interface
   to upload, input or edit 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 each of those I-Ds.
   (R-046)




Juskevicius            Expires February 4, 2011               [Page 10]

Internet-Draft       WG Datatracker Requirements            August 2010


   The user-interface SHOULD allow a Document Shepherd to save a
   partially completed protocol write-up and to resume inputting or
   editing the protocol write-up in a future editing session. (R-047)

   The user-interface SHOULD also prompt the Document Shepherd to set
   or reset the "Document Shepherd Follow-Up Underway" status
   annotation tag, as appropriate, before the end of each protocol
   write-up uploading, inputting or editing session. (R-048)

   The Datatracker SHALL send an e-mail to the WG Chairs and delegates
   whenever one of their designated Document Shepherds indicates that a
   completed protocol write-up for one of their WG I-D's is in the
   Datatracker. (R-049)

   If a Document Shepherd declares that he or she has finished
   uploading, inputting or editing the protocol write-up for a WG I-D
   that is not yet in the "WG Consensus: Waiting for Write-Up" state,
   the Datatracker SHOULD warn the Document Shepherd that it may be too
   early to finish work on the write-up, and then suggest the Document
   Shepherd contact one of the WG's Chairs or delegates. (R-050)  The
   Datatracker SHALL allow a WG Chair or delegate to input a protocol
   write-up for a WG document (or to declare that the protocol write-up
   entered by a Document Shepherd is completed) regardless of the WG
   state that the I-D is in. (R-051)

   Each IETF WG Chair (and delegate) SHOULD be able to access the
   Document Shepherd user-interface and call-up a display of the same
   WG document protocol write-up status information the Datatracker
   gives each of the WG's designated Document Shepherds. (R-052)  This
   is to enable each WG Chair (or delegate) to mentor a new Document
   Shepherd and to facilitate review of the workload assigned to each
   Document Shepherd.

   IETF WG Chairs and delegates may designate themselves to act as the
   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 delegates which role they are playing when the log in, in order
   to display the most appropriate user-interface for that role.
   (R-053)

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 a document
   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 February 4, 2011               [Page 11]

Internet-Draft       WG Datatracker Requirements            August 2010


   The "Candidate WG Document" 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" in 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-054)  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 identified as being in the "Candidate
   WG Document" state in multiple WGs if the conditions specified in
   Requirement R-054 are met. (R-055)  Requirements R-058, R-061, and
   R-072 specify how the Datatracker should display the WG status of an
   I-D that is being shopped to multiple IETF WGs.

   Requirements R-056 to R-072 inclusive are intended to minimize the
   effort needed by WG Chairs and their delegates to manage the status
   of the I-Ds they identify as being candidates for adoption by their
   WGs.  The objectives of the Requirements are as follows:

  - any WG Chair or delegate should be able to identify an I-D as a
    candidate for adoption if Requirement R-054 is met; and

  - a different WG Chair or delegate should also be able to identify
    the same I-D as a candidate for adoption in a their IETF WG without
    creating a problem or coordination headache for any other WG Chair
    or delegate.

  The code to be written to track the status of I-Ds that are moved
  into the "Candidate WG Document" state should operate as follows:

  - the first WG Chair (or delegate) to move an I-D into the "Candidate
    WG Document" state shall be required to input a maximum length of
    time that the I-D may remain in the candidate state;

  - the second (and third and fourth ...) WG Chair or delegate to
    identify the same document as a candidate for adoption in their WG
    shall be informed of the current status of the document, and then



Juskevicius            Expires February 4, 2011               [Page 12]

Internet-Draft       WG Datatracker Requirements            August 2010


    be given an opportunity to extend the period of time the I-D may be
    in the candidate state;

  - the Datatracker shall always display a current list of the names of
    the IETF WGs in which the I-D is being considered for adoption;

  - the Datatracker shall describe the WG status of the document as
    "Candidate WG Document" until one of the WG Chairs (or delegates)
    adopts the document or until every WG Chair (or delegate) does not
    adopt the I-D or until time runs out; and

  - the Datatracker shall automatically change the WG status of the I-D
    to "Not Adopted by a WG" if the document is still in the "Candidate
    WG Document" state when time runs out.

   Requirements R-056 to R-072 are the 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 the maximum length
   of time that the I-D may remain in this state. (R-056)  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-057)

   When Requirements R-056 and R-057 are met, the Datatracker SHALL
   display the WG status of the I-D as follows: "Candidate WG Document
   in (name of IETF WG)". (R-058)

   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-059)  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-060)

   The Datatracker SHALL add the names of second (and third and ...)
   IETF WGs in which the I-D has also become a candidate to the WG
   status information it previously displayed for the document per
   Requirement R-058. (R-061)

   If a WG Chair (or delegate) inputs a number of weeks that would
   extend beyond the expiry date of the I-D, the Datatracker SHALL
   adjust its timer to coincide with the expiry date of the I-D and
   then inform the WG Chair (or delegate) that the I-D cannot be in the


Juskevicius            Expires February 4, 2011               [Page 13]

Internet-Draft       WG Datatracker Requirements            August 2010


   "Candidate WG Document" state after the date that the I-D "Expires"
   (as specified the cover page of the I-D). (R-062)

  If a 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 then in the "Candidate WG Document" state) to inform them
  the document has become a candidate in another WG and that the time
  the I-D may remain in the "Candidate WG Document" state has been
  extended to a new date of (whatever the new date is). (R-063)

  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-064)  In this case, the Datatracker SHALL
  send an e-mail to the WG Chairs and delegates of every other WG (in
  which the document is then in the "Candidate WG Document" state) to
  inform them the document has become a candidate in another IETF WG
  and to inform them that the amount of time the I-D may remain as a
  candidate has not been changed. (R-065)

   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
   in the "Candidate WG Document" state. (R-066)  The e-mail will alert
   everyone the I-D is still in the candidate state, and it will inform
   everyone the Datatracker will automatically move the I-D into the
   "Not Adopted by a WG" state when time expires unless one of the WG
   Chairs (or delegates) moves the I-D into a different state first.
   (R-067)

   If a "Candidate WG Document" is adopted by a WG before the timer
   expires, the Datatracker SHALL cancel the timer and send an e-mail
   to the authors of the I-D and to every WG Chair and delegate still
   having an interest in the document to inform them the I-D has been
   adopted by the (insert name of the WG here) WG. (R-068)

   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 still having an interested in the document to announce the
   document was not adopted by any IETF WG and that its state has been
   changed automatically to "Not Adopted by a WG". (R-069)

   Some WG Chairs may decide not to adopt an I-D after the document has
   become a candidate for adoption in one or more other WGs.  The
   Datatracker SHALL allow IETF WG Chairs and delegates to cancel their
   interest in a "Candidate WG Document" by allowing them to indicate
   the I-D has been "Not Adopted" by their WG. (R-070)




Juskevicius            Expires February 4, 2011               [Page 14]

Internet-Draft       WG Datatracker Requirements            August 2010


   If a WG Chair (or delegate) cancels their interest in the adoption
   of an I-D (per Requirement R-070), the Datatracker SHALL update the
   status change history log for the I-D accordingly. (R-071)

   The Datatracker SHALL also remove the name of the IETF WG from its
   WG status display (of other WGs (per Requirement R-061) in which the
   I-D is still being considered for adoption), and remove the Chairs
   (and delegates) of the WG from the distribution list for the e-mails
   that may be generated per Requirements R-063, and R-065 to R-069
   inclusive. (R-072)

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
   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-073)  If a WG Chair or delegate moves
   an I-D into the "Adopted by a WG" state, the Datatracker will
   confirm this state change via e-mail as specified in R-068.

6.3. Not Adopted by a WG

   The "Not Adopted by a WG" state describes an I-D that was considered
   for adoption by one or more IETF WGs but was not adopted by any WG.

   Requirement R-069 specifies 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


Juskevicius            Expires February 4, 2011               [Page 15]

Internet-Draft       WG Datatracker Requirements            August 2010


   that the I-D was a candidate for and that did not adopt the I-D.
   (R-074)

   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-075)  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-076)

   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 shall 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).

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-077)

   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-078)

   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-079)

   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-080)



Juskevicius            Expires February 4, 2011               [Page 16]

Internet-Draft       WG Datatracker Requirements            August 2010


   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-081)  The Datatracker
   SHALL allow the "Intended Maturity Level" to be changed after first
   being set. (R-082)

   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-083)

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
   message to one or more mailing lists when an I-D in moved into this
   state. (R-084)  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-085)

   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-086)  The number of weeks
   SHALL be able to be changed after first being set. (R-087)

   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-088)  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-086 to remind or 'nudge' them to conclude
   the WGLC and to determine a next state for the I-D. (R-089)

   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-090)






Juskevicius            Expires February 4, 2011               [Page 17]

Internet-Draft       WG Datatracker Requirements            August 2010


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-091)
   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-092)

   The Document Shepherd for an I-D that is moved into this state SHALL
   be alerted of the state change via e-mail. (R-093)  The e-mail will
   'nudge' the Shepherd to develop a protocol write-up for the I-D.  If
   a timer was configured per R-092, 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.

   The Datatracker shall send an e-mail message to the WG Chairs and
   delegates when a Document Shepherd signals that he/she has finished
   inputting the protocol write-up for a WG I-D into the Datatracker.
   (R-094)

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-095)

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.



Juskevicius            Expires February 4, 2011               [Page 18]

Internet-Draft       WG Datatracker Requirements            August 2010


   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-096).  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-097)

   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-098)

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.

   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-077, 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-099)



Juskevicius            Expires February 4, 2011               [Page 19]

Internet-Draft       WG Datatracker Requirements            August 2010


  - 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-100)

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-101)

   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-102)

   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-103)

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-104)

   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-105)

   The Datatracker's document status display page SHOULD be modified to
   display the metadata and status of an I-D associated with an IETF WG
   as shown in the following sample page: (R-106)






Juskevicius            Expires February 4, 2011               [Page 20]

Internet-Draft       WG Datatracker Requirements            August 2010


     --------------------------------------------------------------

     Document stream:          IETF
     I-D availability status:  Active / Expired / Withdrawn / RFC
                               Replaces / Replaced I-D or RFC (if
                               applicable)
     Last updated:             year-mm-dd (e.g. 2010-07-25)
     IETF WG status: *         Applicable WG state & name of WG or WGs
     Intended RFC status: **   Informational / Experimental / etc.
     Document shepherd: ***    Name of Document Shepherd (if assigned)
     IESG status:  ****        Name of applicable IESG state
     Responsible AD:           Name of the Responsible AD

     --------------------------------------------------------------

    *    The "IETF WG status" SHALL display the current IETF WG
          state of the I-D and WG that the I-D is associated with.
          An I-D in the "Candidate WG Document" state may be
          associated with more than one IETF WG at the same time I-D.
          For I-Ds in this WG state, the Datatracker SHOULD display
          the acronym of every IETF WG that the I-D is currently
          associated with. (R-107)

    **   The "Intended RFC status" for I-Ds in the WG state called
          "Adopted for WG Info Only" SHOULD be displayed as "None".
          (R-108)

    **   The field called "Intended RFC status" SHOULD be renamed to
          "RFC status" when the Datatracker displays the status of a
          document that has been published as an RFC. (R-109)

    ***  This field SHOULD display the name of the person (or e-mail
          address of the person) assigned to be the Document Shepherd
          for the I-D, or be left blank if a Document Shepherd has
          not yet been assigned. (R-110)

    ****  This field SHALL display the current IESG status of the
          document or the word "Null" for documents that are not yet
          being tracked by the IESG. (R-111)



10. Error handling requirements

   Errors with respect to inputting or updating the status of a WG
   document are possible.





Juskevicius            Expires February 4, 2011               [Page 21]

Internet-Draft       WG Datatracker Requirements            August 2010


   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.

   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-08,
               July 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


Juskevicius            Expires February 4, 2011               [Page 22]

Internet-Draft       WG Datatracker Requirements            August 2010


               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/, July 25, 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, Alfred Hoenes,
   Paul Hoffman and SM 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.

   The author also offers his gratitude to Russ Housley, Scott Bradner,
   Robert Sparks, Spencer Dawkins, 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 February 4, 2011               [Page 23]


Html markup produced by rfcmarkup 1.109, available from https://tools.ietf.org/tools/rfcmarkup/