draft-ietf-proto-wgdocument-states-02

8/7/2019 draft-ietf-proto-wgdocument-states-02

1/18

Proto E. JuskeviciusInternet Draft TrekAheadIntended status: Informational March 2, 2010Expires: September 2, 2010

Definition of Working Group Document Statesdraft-ietf-proto-wgdocument-states-02.txt

Status of this Memo

This Internet-Draft is submitted to IETF in full conformance withthe provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet EngineeringTask Force (IETF), its areas, and its working groups. Note thatother groups may also distribute working documents as Internet-

Drafts.

Internet-Drafts are draft documents valid for a maximum of sixmonths and may be updated, replaced, or obsoleted by other documentsat any time. It is inappropriate to use Internet-Drafts asreference material or to cite them other than as "work in progress."

The list of current Internet-Drafts can be accessed athttp://www.ietf.org/ietf/1id-abstracts.txt

The list of Internet-Draft Shadow Directories can be accessed athttp://www.ietf.org/shadow.html

This Internet-Draft will expire on September 2, 2010.

Copyright Notice

Copyright (c) 2010 IETF Trust and the persons identified as thedocument authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's LegalProvisions Relating to IETF Documents(http://trustee.ietf.org/license-info) in effect on the date ofpublication of this document. Please review these documentscarefully, as they describe your rights and restrictions with

respect to this document. Code Components extracted from thisdocument must include Simplified BSD License text as described inSection 4.e of the Trust Legal Provisions and are provided withoutwarranty as described in the Simplified BSD License.

Juskevicius Expires September 2, 2010 [Page 1]


2/18

Internet-Draft Working Group Document States March 2010

Abstract

This document contains definitions for the different states that

documents (viz. Internet-Drafts) may experience while associatedwith an IETF working group. The first state occurs when an InternetDraft (I-D) is submitted for consideration as a working group item.The last state is either when the I-D is sent to the IESG forpublication, or declared as "dead".

The purpose of this Internet-Draft is to serve as a basis for thedefinition of requirements to extend the IETF Datatracker tool sothat the community may monitor the status and progression of I-Dsthrough IETF working groups.

For completeness, Appendix A has definitions for all of the I-D

states which are already coded into the Datatracker. These statesdescribe the progression and status of I-Ds after they have beensubmitted to the IESG for publication.

Table of Contents

1. Introduction...................................................32. Conventions used in this document..............................43. Definitions of Possible WG Document States.....................4

3.1. WG Document States........................................4

3.1.1. Candidate WG Document................................53.1.2. Active WG Document...................................53.1.3. Not a WG Document....................................53.1.4. Parked WG Document...................................53.1.5. In WG Last Call......................................53.1.6. WG Last Call Completed...............................53.1.7. Waiting for WG Document Shepherd Write-Up............63.1.8. Submitted to IESG for Publication....................63.1.9. Dead WG Document.....................................6

3.2. Straw Man WG Document State Diagram.......................63.3. WG Document Substates.....................................6

3.3.1. Awaiting Cross-Area Review...........................83.3.2. Awaiting MIB Doctor Review...........................83.3.3. Awaiting Security Review.............................83.3.4. Awaiting Other Review................................83.3.5. Awaiting Merge with Other Document...................93.3.6. Author or Editor Needed..............................93.3.7. Held due to Dependency on other Document.............93.3.8. Held due to IESG concerns on this Document...........9



3/18


3.3.9. Revised I-D Needed - based on WG consensus..........103.3.10. Revised I-D Needed - based on WG last call.........103.3.11. Doc Shepherd Follow-up.............................10

3.3.12. Other - see Comment Log............................103.4. Intended Maturity Level of WG Documents..................11

4. Security Considerations.......................................115. IANA Considerations...........................................116. References....................................................11

6.1. Normative References.....................................116.2. Informative References...................................12

7. Acknowledgments...............................................12Appendix A: "IESG Document" States...............................13

A.1. Definition of "IESG Document" States.....................13A.1.1. I-D Exists..........................................13A.1.2. Publication Requested...............................13

A.1.3. AD Evaluation.......................................13A.1.4. Expert Review.......................................13A.1.5. Last Call Requested.................................14A.1.6. In Last Call........................................14A.1.7. Waiting for Writeup.................................14A.1.8. Waiting for AD Go-Ahead.............................14A.1.9. IESG Evaluation.....................................14A.1.10. IESG Evaluation - Defer............................15A.1.11. Approved-announcement to be sent...................15A.1.12. Approved-announcement sent.........................15A.1.13. RFC Ed Queue.......................................15A.1.14. RFC Published......................................15A.1.15. DNP-waiting for AD note............................15

A.1.16. DNP-announcement to be sent........................15A.1.17. AD is Watching.....................................15A.1.18. Dead...............................................16

A.2. "IESG Document" Substates................................16A.2.1. Point Raised - writeup needed.......................16A.2.2. AD Followup.........................................16A.2.3. External Party......................................17A.2.4. Revised I-D Needed..................................17

Author's Address................................................ 17

1. Introduction

The IETF Datatracker is a web-based system for managing informationabout Internet-Drafts (I-Ds), RFCs and several other importantaspects of the IETF process [IDTRACKER]. A limitation of theDatatracker is that its database contains very little informationabout the status of Internet Drafts prior to the time they are



4/18


submitted to the IESG for publication. Only one non-IESG state iscurrently defined and coded into the tool: "I-D Exists".

Section 3 of this I-D proposes definitions for an additional set ofdocument states, namely every state that a document written forconsideration by an IETF Working Group (WG) may experience duringits progression though a WG.

The purpose of defining WG document states is to enable communitydiscussion on them and consensus on a state diagram to illustratethe state transitions preferred by most WGs to progress I-Ds.

A desired outcome of this initiative is to reach consensus on a setof requirements to extend the Datatracker so that WG Chairs andother members of the community could monitor the status of I-Ds as

they progress through IETF working groups.

2. Conventions used in this document

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT","SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in thisdocument are to be interpreted as described in RFC 2119 [RFC2119].

3. Definitions of Possible WG Document States

The IETF Datatracker tool has minimal information about the statusof I-Ds at the WG level today. Prior to someone asking that an I-SDbe published, the only state tracked by the tool is "I-D Exists".

The Datatracker has no other status information about any WGdocument.

In order for the Datatracker to be record WG document state, new WGdocument states and substates need to be defined, agreed and thencoded into the front-end of the tool.

Section 3.1 defines the possible states that could apply to I-Dsthat have been submitted to an IETF working group. Section 3.2illustrates the relationships between the states in diagram form.Section 3.3 defines additional terms which may be useful to flagvarious WG document substates. Section 3.4 lists the all of the"intended maturity levels" which could be applied to a WG document.

3.1. WG Document States

This subsection defines all of the different states that MAY applyto any I-D written as a contribution into an IETF working group.



5/18


3.1.1. Candidate WG Document

An I-D that is under consideration for becoming a working group

document as a "Candidate WG Document". A document being in thisstate does not imply any consensus, and does not imply anyprecedence or selection. The purpose of this state is simply toindicate that someone has asked for an existing I-D to beconsidered for acceptance as a working group document.

3.1.2. Active WG Document

An "Active WG Document" is an I-D that has been adopted by aworking group, and is being actively developed.

3.1.3. Not a WG Document

This document is not a WG Document. An I-D may be in this statefor a variety of reasons. Some examples are:

- the I-D was a "Candidate WG Document" but was rejected by theWG; or

- the I-D is an IAB or IRTF document, an individual submission,or an independent submission not intended to become a WGdocument.

3.1.4. Parked WG Document

A "Parked WG Document" is an I-D which has lost its author or

editor, is waiting for another document to be written or for areview to be completed, or cannot currently be progressed by theworking group for some other reason.

3.1.5. In WG Last Call

A document "In WG Last Call" is an I-D for which a WG last callhas been issued, and is in progress.

3.1.6. WG Last Call Completed

After a WG last call is completed, any comments received SHOULD beevaluated before the I-D is progressed. During the evaluationperiod, the I-D is in a "WG Last Call Completed" state. After theevaluation, the document MAY return to being an "Active WGDocument" again (i.e. to be refined or rewritten) or be "Parked"for a variety of reasons, or be progressed into "Waiting forDocument Shepherd Write-Up".



6/18


Many members of the community desire additional information whenthe result of a WG Last Call is "Revised I-D Needed". See section3.3 for "annotation tags" which may be used to provide such

additional information.

3.1.7. Waiting for WG Document Shepherd Write-Up

The working group last call has been completed and the document isawaiting the document shepherd to submit his/her write-up.

3.1.8. Submitted to IESG for Publication

The document has been submitted to the IESG for publication (andhas not returned to the WG for further action). The document maybe under consideration by the IESG, it may have been approved and

be in the RFC Editor's queue, or it may have been published as anRFC; this state does not distinguish between different states thatmay occur after the document has left the working group.

3.1.9. Dead WG Document

A "Dead WG Document" is an I-D that used to a WG document, but hasbeen abandoned. Note that this is not always a final state. Ifconsensus is subsequently achieved in the working group, a "DeadWG Document" can be resurrected.

3.2. Straw Man WG Document State Diagram

Figure 1 illustrates all of the different states defined in section3.1, and most of the state transitions that an I-D MAY experienceduring its tenure as a WG Document.

State transitions which are rare (e.g. an I-D going from "Parked" to"Dead") are not illustrated in the diagram, however the lack of anexplicit path between two states in the diagram does not mean thatsuch a transition is impossible.

3.3. WG Document Substates

In addition to identifying the state that every WG Document is in,it would be informative for the Datatrack to record associatedsubstates or conditions which may affect each WG Document atdifferent time. The substates do not change the state of WGdocuments, but they can be used, for example, to help the communityunderstand why a document is in the state it is in, and/or toindicate the next action needed for the document.



7/18


+------------------------------------------------------------------+ I-D

Exists v CANDIDATE WG DOCUMENT v DEAD WG ACTIVE WG PARKED WG

DOCUMENT . -> DOCUMENT DOCUMENT . . ^ ^ . . + - < - - + . . v ^ ' IN WG ^ LAST CALL ^ ^ ' ^

v ^ WG LAST CALL - - - + ' COMPLETED - - - - - - - - - + ^ +---------------------+ ' . v . . SUBMITTED WAITING FOR < - - (to IESG)


8/18


Each of the substates defined herein may be appropriate to indicatethe substate of a WG Document at different times.

3.3.1. Awaiting Cross-Area Review

This is a valid substate for "Active" and "Parked" WG Documents.It means that someone (e.g. an author or editor of the document,or a WG Chair) has initiated a cross-area review of the document,and the review has not (yet) been completed.

Documents tagged with this annotation SHOULD remain in thissubstate until the review is complete and possibly until theissues raised in the review are addressed.

3.3.2. Awaiting MIB Doctor Review

This is a valid substate for "Active" and "Parked" WG Documents.It means that someone (e.g. an author or editor of the document,or the a WG Chair) has initiated a review of the document by a MIBDoctor, and the review has not (yet) been completed.


3.3.3. Awaiting Security Review

This is a valid substate for "Active" and "Parked" WG Documents.

It means that someone (e.g. an author or editor of the document,or a WG Chair) has initiated a review of security considerationsin the document, and the review has not (yet) been completed.


3.3.4. Awaiting Other Review

This is a valid substate for "Active" and "Parked" WG Documents.It means that someone (e.g. an author or editor of the document,or a WG Chair) has initiated some other review of the document(e.g. sent it to another Standards Development Organization (SDO)for comments via a formal or informal liaison process [MPLSTPDP])and the review has not (yet) been completed.



9/18



3.3.5. Awaiting Merge with Other Document

This is a valid substate for "Active" and "Parked" WG Documents.It means that a decision has been made by someone (e.g. thedocument's authors, editors, or the WG Chairs) to have the I-Dmerged with one or more other I-Ds from the same (or other) WG.

If the result of the "merge" operation is a brand new I-D having adifferent title, then the old I-D may be declared as being "Dead".In this case the substate annotation should be changed from"Awaiting Merge with Other Document" to "Other - see Comment Log"

and a description of what happened should be entered in the logfor posterity.

If the result of the "merge" operation is a revision to the I-D,then this substate should be cleared as soon as the the revised I-D is submitted to the IETF by its authors or editors.

3.3.6. Author or Editor Needed

This substate is applicable to "Parked", "Dead" and (sometimes)"Active" WG Documents. It means the I-D has lost a primary authoror editor, and that further work on the I-D can not continue in aneffective or efficient manner without a new author or editor being

found.

3.3.7. Held due to Dependency on other Document

This substate is most often associated with "Parked" WG Documents.It means that work to complete the I-D is on-hold because of oneor more dependencies on other documents. A typical example iswhere an I-D includes normative references to other IETFdocuments, but all of other documents have not (yet) beenpublished as RFCs.

3.3.8. Held due to IESG concerns on this Document

This is a valid substate for "Active" and "Parked" WG Documents,and I-Ds which are in the "WG Last Call Completed" state. Thisannotation is an indicator that one or more IESG members haveexpressed concerns about the document (e.g. during discussionsleading up to a WG Last Call, or during the WG Last Call), and



10/18


that the document MUST NOT be submitted to the IESG forpublication until the concerns are addressed.

Once in this substate, WG Documents SHOULD continue to be taggedwith this indicator until the IESG concerns are resolved, even ifthe main state of the I-D changes (e.g. from "Active" to "Parked"(or "Dead") or vice-versa).

3.3.9. Revised I-D Needed - based on WG consensus

This is a valid substate for "Active", "Parked", and "Dead" WGDocuments. This annotation means that rough consensus wasdeveloped in the working group that the I-D needs to be revised ifit is to be progressed. This annotation can also indicate when anI-D is already in the process of being revised. This substate

SHOULD be reset when the revised version of the I-D is submittedto the WG.

3.3.10. Revised I-D Needed - based on WG last call

This is a valid substate for "WG Last Call Completed", "Active","Parked", and/or "Dead" WG Documents. This annotation means theI-D was sent for WG Last Call and the consensus after the LastCall is that the WG Document MUST be revised before it mayprogress any further.

3.3.11. Doc Shepherd Follow-up

This substate annotation indicates when a shepherd for the WGDocument is actually working on the write-up required to submitthe document (to the IESG) for publication. It is often the casethat too many I-Ds can arrive in a Shepherd's queue in too short atime, and the Shepherd can not create write-ups for all of themsimultaneously. This substate tag SHOULD be used to distinguishbetween I-Ds waiting for write-up (i.e. I-Ds for which the write-ups have not yet been started), and I-Ds for which the write-upsare already underway.

3.3.12. Other - see Comment Log

This annotation tag is a catch-all to indicate that someone (e.g.an author or editor of the document, the WG Chair, an AD) hasentered one or more comments about the current state of the I-Dinto the IETF Datatracker.



11/18


3.4. Intended Maturity Level of WG Documents

In addition to the substate annotation tags defined in section 3.3,the intended maturity level of every WG Document SHOULD also betracked. The definition of the maturity levels are as in sections 4and 5 of RFC 2026 [RFC2026]. They are:

* "Experimental"* "Informational"* "Best Current Practice"* "Proposed Standard"* "Draft Standard"* "Full Standard"* "Historic"

4. Security Considerations

This document does not propose any new internet mechanisms, and hasno security implications for the internet.

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

6. References

6.1. Normative References

[RFC2119] Bradner, S., "Key words for use in RFCs to IndicateRequirement Levels", BCP 14, RFC 2119, March 1997.

[RFC2026] Bradner, S., "The Internet Standards Process: Revision3", BCP 9, RFC 2026, October 1996.



12/18


6.2. Informative References

[IDTRACKER] "The IETF Datatracker tool", Web Application:

https://datatracker.ietf.org/, March 1, 2010.

[IDSTATES] "Main I-D States", Web Application:https://datatracker.ietf.org/idtracker/help/state/,March 1, 2010.

[RFC2418] Bradner, S., "IETF Working Group Guidelines andProcedures", BCP 25, RFC 2418, September 2008.

[MPLSTPDP] Farrel, A., et al, "IETF Multi-Protocol Label Switching(MPLS) Transport Profile (MPLS-tp) Document Process",

draft-IETF-MPLS-tp-process-05.txt, Section 2.3,January 24, 2010.

[PROTO] Levkowetz, H., and Mankin, A., "Requirements on I-DTracker Extensions for Working Group Chairs",draft-ietf-proto-wgchair-tracker-ext-03,February 8, 2007.

7. Acknowledgments

The author would like to thank Henrik Levkowetz and Allison Mankinfor writing the original I-Ds [PROTO] that provided copious amounts

of text and the basic structure of this document.

The author would also like to thank Henrik Levkowetz, Alfred Hoenes,John Klensin, Pasi Eronen, Mary Barnes, Glenn Parsons, SpencerDawkins, Russ Housley, Marc Blanchet, Andy Malis and other WG chairsfor useful discussions, comments and suggestions.

This document was initially prepared using 2-Word-v2.0.template.dot.



13/18


Appendix A: "IESG Document" States

This Appendix describes the status information currently stored in

the IETF Datatracker tool for every I-D submitted to the IESG forpublication. The terms and definitions herein are as in [IDSTATES].

It must be noted that I-Ds sent to the IESG for publication (termed"IESG Documents" in the Appendix) do not stay with the IESG untilthey day they are published as RFCs. After evaluation, the IESG maydeclare that some I-Ds deserve a "Do Not Publish" label, whileothers should be "Dead". Some I-Ds get sent back to theiroriginators (WGs or otherwise), and the rest go into the RFC Editorqueue.

A.1. Definition of "IESG Document" States

A.1.1. I-D Exists

This is the initial (default) state for all Internet-Drafts. Suchdocuments are not tracked by the IESG as no request has been made ofthe IESG to do anything with an I-D in this state.

A.1.2. Publication Requested

A formal request has been made to advance/publish the document,following the procedures in Section 7.5 of RFC 2418 [RFC2418]; therequest could be from a WG Chair, from an individual through the RFCEditor, etc. Note: the Secretariat ([email protected]) is

copied on these requests to ensure that the request makes it intothe Datatracker. A document in this state has not (yet) beenreviewed by an Area Director (AD) nor has any official action beentaken on it yet (other than to note that its publication has beenrequested).

A.1.3. AD Evaluation

A specific AD (e.g. the "Area Advisor" for the WG) has begun his/herreview of the document to verify that it is ready for advancement.The shepherding AD is responsible for doing any necessary reviewbefore starting an IETF Last Call or sending the document directlyto the IESG as a whole.

A.1.4. Expert Review

An AD sometimes asks for an external review by an outside party aspart of evaluating whether a document is ready for advancement.MIBs, for example, are reviewed by the "MIB doctors". Other types



14/18


of reviews may also be requested (e.g., security, operationsimpacts, etc.). Documents remain in this state until the review iscompleted and possibly until the issues raised in the review are

addressed. Specific details on the nature of the review may befound in the "note" field associated with this state (i.e. withinthe Datatracker).

A.1.5. Last Call Requested

The AD has requested that the Secretariat start an IETF Last Call,but the actual Last Call message has not been sent yet.

A.1.6. In Last Call

The document is currently waiting for IETF Last Call to complete.

Last Calls for WG documents typically last 2 weeks, and those forindividual submissions last 4 weeks.

A.1.7. Waiting for Writeup

Before a standards-track or BCP document is formally considered bythe entire IESG, the AD must write-up a protocol action. Theprotocol action is included in the approval message that theSecretariat sends out when the document is approved for publicationas an RFC.

A.1.8. Waiting for AD Go-Ahead

As a result of the IETF Last Call, comments may need to be respondedto and a revision of the I-D may be needed as well. The AD isresponsible for verifying that all Last Call comments have beenadequately addressed and that the (possibly revised) document is inthe I-D directory and ready for consideration by the IESG as awhole.

A.1.9. IESG Evaluation

The document is now (finally!) being formally reviewed by the entireIESG. Documents are discussed in email or during a bi-weekly IESGtelechat. In this phase, each AD reviews the document and airs anyissues she/he may have. Unresolvable issues are documented as"discuss" comments that can be forwarded to the authors/WG. See thedescription of substates in Section A.2 for additional details aboutthe current state of the IESG discussion.



15/18


A.1.10. IESG Evaluation - Defer

During a telechat, one or more ADs requested an additional 2 weeks

to review the document. A defer is designed to be an exceptionmechanism, and can only be invoked once, the first time the documentcomes up for discussion during a telechat.

A.1.11. Approved-announcement to be sent

The IESG has approved the document for publication, but theSecretariat has not yet sent out an official approval message.

A.1.12. Approved-announcement sent

The IESG has approved the document for publication, and the

Secretariat has sent out the official approval message to the RFCeditor.

A.1.13. RFC Ed Queue

The document is in the RFC editor Queue (as confirmed byhttp://www.rfc-editor.org/queue.html)

A.1.14. RFC Published

The I-D has been published as an RFC.

A.1.15. DNP-waiting for AD note

Do Not Publish: The IESG recommends against publishing the document,but the writeup explaining its reasoning has not yet been produced.DNPs apply primarily to individual submissions received through theRFC editor. More information on who has the action item should berecorded in the "note" field associated with this state (i.e. withinthe Datatracker).

A.1.16. DNP-announcement to be sent

The IESG recommends against publishing the document. A writeupexplaining the IESG's reasoning has been produced, but theSecretariat has not yet sent out the official "do not publish"recommendation message.

A.1.17. AD is Watching

An AD is aware of the document and has chosen to place the documentin a separate state in order to keep a closer eye on it (for



16/18


whatever reason). Documents in this state are still not beingactively tracked in the sense that no formal request has been madeto publish or advance the document. The sole difference between

this state and "I-D Exists" is that an AD has chosen to put it in aseparate state, to make it easier to keep track of (for his or herown reasons).

A.1.18. Dead

The document is "dead" and is no longer being tracked (e.g., it hasbeen replaced by another document having a different name, it hasbeen withdrawn, etc.).

A.2. "IESG Document" Substates

A.2.1. Point Raised - writeup needed

IESG discussions on the document have raised some issues that needto be brought to the attention of the authors/WG, but those issueshave not been written down yet. (It is common for discussions duringa telechat to result in such situations. An AD may raise a possibleissue during a telechat and only decide as a result of thatdiscussion whether the issue is worth formally writing up andbringing to the attention of the authors/WG). A document stays inthe "Point Raised - writeup needed" state until *ALL* IESG commentsthat have been raised have been documented.

A.2.2. AD Followup

"AD Followup" is a generic substate indicating that the shepherdingAD has the action to determine appropriate next steps. Inparticular, the appropriate steps (and the corresponding next stateor substate) depend entirely on the nature of the issues that wereraised and can only be decided with active involvement of theshepherding AD.

Examples include:

- if another AD raises an issue, the shepherding AD may firstiterate with the other AD to get a better understanding of the exactissue. Or, the shepherding AD may attempt to argue that the issueis not serious enough to bring to the attention of the authors/WG.

- if a documented issue is forwarded to a WG, some further iterationmay be needed before it can be determined whether a new revision isneeded or whether the WG response to an issue clarifies the issuesufficiently.



17/18


- when a new revision appears, the shepherding AD will first look atthe changes to determine whether they believe all outstanding issueshave been raised satisfactorily, prior to asking the ADs who raised

the original issues to verify the changes.

A.2.3. External Party

The document is awaiting review or input from an external party(i.e, someone other than the shepherding AD, the authors, or theWG). See the "note" field for more details on who has the action.

A.2.4. Revised I-D Needed

An updated I-D is needed to address the issues that have beenraised.

Author's Address

Ed JuskeviciusTrekAheadPO Box 491, Carp, ONCANADA

Email: [email protected]



18/18