Definition of IETF Working Group Document States
draft-ietf-proto-wgdocument-states-10

Received changes through RFC Editor sync (changed abstract to 'The IETF Datatracker tool needs to be enhanced to make it possible for Working Group (WG) Chairs to provide IETF participants with more information about the status and progression of WG documents than is currently possible.

This document defines new states and status annotation tags that need to be added to the Datatracker to enable WG Chairs and their Delegates to track the status of Internet-Drafts (I-Ds) that are associated with their WGs. This document also describes the meaning of all previously implemented I-D states and substate annotation tags currently used by IETF Area Directors to indicate the status of I-Ds that have been sent to the IESG for evaluation and publication. This document is not an Internet Standards Track specification; it is published for informational purposes.')

[Ballot comment]
In section 3.1, the document state withdrawn is listed but is not defined and no reference is given.  Text was added that indicated this is self-explanatory, but I must be dense since I still don't know what it means,

I do not want to delay things further, though, and see no harm in moving forward with this text.

[Ballot comment]
The changes to the pre-wg-adoption handling of a document address my previous DISCUSS point on this document. Thanks for helping reflect what working groups currently do.

There is a lot of new text here. The phrase "IETF stream" has been added and I'm not sure its use is quite right yet - individual submission documents don't seem to be fully considered. In section 4.2, it calls out that non-IETF stream documents will be in a null state with respect to the WG states. Should it also call out IETF stream documents that did not go through a working group? In section 4.2.1, the sentence " An I-D that is not adopted as a WG draft will transition out the IETF stream into a non-stream state." is not clear - what are the possible non-stream states?

[Ballot comment]
Many thanks for taking on this important work. Just a few Comments
that you might consider as the I-D goes forward.



I feel there is some confusion between "state" and "status" (for
example, in the Abstract). This is handled in
draft-juskevicius-datatracker-wgdocstate-reqts which says:

  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.

I feel it would be helpful to use the same language in both documents.

---

Section 3.1.2

    An "Active" I-D is a document that is not expired.
                                                                       
In fact, an I-D that is an RFC, is not "Active". Ditto other states.

---

Some inconsistency of "WG" and "IETF WG" that implies a difference of
meaning that does not exst.

---

Section 3.2

Not quite sure of the purpose of this section.

It seems to me that "In Last Call"and "Waiting for AD Go-ahead" are
also key states for interaction with the document authors.

"AD is Watching" and "Dead" also seem to be pretty closely related to
the authors.

---

Figure 1

I know this is showing common transitions only, but I suspect you should
show the arrow between "Candidate WG Document" and "Not Adopted be a WG"
as double-headed.

[Ballot comment]
(a) In 3.3.1

OLD
      b) an I-D that the WG Chair asked an author to write;
NEW
      b) an I-D that the WG Chair asked an author to write specifically
      for consideration as a WG draft;


(b) I support Lars' discuss on section 3.3.5. Not Adopted by a WG

(c) Figure 1
There should be a line from WG LAST CALL to WG document.  A chair may decide that Last Call failed, and
send the document back to the working for extensive discussions.  As drawn, any document that goes into Last Call
has to go to the IESG before it can then be returned to the working group.

[Ballot discuss]
(a) Section 3.1

The document state withdrawn is listed but is not defined and no reference is given.  "Withdrawn" is not supported
in the old tracker, so I have no idea what is intended.

(b) 3.1.3. Replaced

I have seen a number of cases where a single document was replaced by three or four documents.  I suspect that
the reverse situation (where multiple documents are replaced by one) also exists. The text in this section implies
that the replacement is always one-for-one.

(c) This one is a discuss-discuss.  I am not requesting any change, but do want to see some discussion of this
concept

3.6. "Intended Maturity Level of WG Documents" suggest that every wg document should indicate the intended
maturity level.  This is a decision that the wg often makes at a later stage in the process (before or during WG LC).
Making the decision early may not be a good idea - the editor may regard that as a contract.  Was the idea of an
"undecided"maturity level considered?

[Ballot discuss]
Section 3.1

The document state withdrawn is listed but is not defined and no reference is given.  "Withdrawn" is not supported
in the old tracker, so I have no idea what is intended.

3.1.3. Replaced

I have seen a number of cases where a single document was replaced by three or four documents.  I suspect that
the reverse situation (where multiple documents are replaced by one) also exists. The text in this section implies
that the replacement is always one-for-one.

This one is a discuss-discuss.  I am not requesting any change, but do want to see some discussion of this
concept

3.6. "Intended Maturity Level of WG Documents" suggest that every wg document should indicate the intended
maturity level.  This is a decision that the wg often makes at a later stage in the process (before or during WG LC).
Making the decision early may not be a good idea - the editor may regard that as a contract.  Was the idea of an
"undecided"maturity level considered?

[Ballot discuss]
Section 3.1

The document state withdrawn is listed but is not defined and no reference is given.  "Withdrawn" is not supported
in the old tracker, so I have no idea what is intended.

3.1.3. Replaced

I have seen a number of cases where a single document was replaced by three or four documents.  I suspect that
the reverse situation (where multiple documents are replaced by one) also exists. The text in this section implies
that the replacement is always one-for-one.

[Ballot comment]
In 3.3.1

OLD
      b) an I-D that the WG Chair asked an author to write;
NEW
      b) an I-D that the WG Chair asked an author to write specifically
      for consideration as a WG draft;

Figure 1
There should be a line from WG LAST CALL to WG document.  A chair may decide that Last Call failed, and
send the document back to the working for extensive discussions.  As drawn, any document that goes into Last Call
has to go to the IESG before it can then be returned to the working group.

[Ballot comment]
In 3.3.1

OLD
      b) an I-D that the WG Chair asked an author to write;
NEW
      b) an I-D that the WG Chair asked an author to write specifically
      for consideration as a WG draft;

[Ballot discuss]
The document state withdrawn is listed but is not defined and no reference is given.  "Withdrawn" is not supported
in the old tracker, so I have no idea what is intended.

[Ballot discuss]
I think the proposal for a process to track documents before WG adoption should be split
into a separate effort. This is coupled to a discuss point on the tracker requirements document
copied here for convenience:

  Where this document is capturing requirements to facilitate WG tracking using
  processes that WG chairs are already exercising I think it's on track. I believe
  it and it's companion state document are going going further than that in
  with the definition of the Candidate WG document and Not Adopted by a WG states
  and the behavior required not just of the tool but of the chairs by this document.
  Attempting to define a new process and codify it into a tool at the same time seems
  risky. I would prefer to see the requirements around tracking a document before WG
  adoption split into a separate effort, both in determining requirements and implementing
  the tool. (It would be even better if there was experience with the suggested process -
  an interested chair and cooperative AD could do this now with the comments field in the
  existing tracker.) Our initial effort should be scoped to helping WG chairs and other
  stakeholders track what they already do.

[Ballot comment]
Section 2., paragraph 1:
>    The phrase "working group document" is to be interpreted as being
>    synonymous with "working group I-D".  The same is true for the
>    plural case of each phrase.

  You probably want to add that a "working group I-D" is an I-D that has
  gotten consensus for adoption as a work item by a WG (compared to
  individual ones, that have not or not yet).


Section 3.1.3., paragraph 3:
>      - The filename of an individual I-D that is being considered for
>        adoption by an IETF WG will typically include the name of its
>        author (e.g. 'draft-author-wgname-topic-nn').  If the I-D is
>        adopted by a WG, its filename will change to 'draft-ietf-
>        wgname-topic-00', and the Datatracker will describe the older
>        individual I-D as having been "Replaced by" a newer WG I-D.

  It may be useful to add that "replacing" an ID in this form currently
  requires an explicit request by the WG chair. Without that request,
  the IDs will coexist and the individual one will eventually expire.


Section 3.2., paragraph 0:
> 3.2. IESG Document States

  The state definitions below are sightly different in wording than in
  [IESGSTAT] and in Appendix A. This is confusing.


Section 3.2.3., paragraph 0:
>  3.2.3. IESG Evaluation

  Suggest to swap the order of the two paragraphs.


Section 3.3., paragraph 0:
> 3.3. Working Group Document States

  It would be good to make this a new top-level section, because unlike
  Sections 3.1 and 3.2, which were replicated for information and not
  new, this *is* the new stuff.


Section 3.3., paragraph 1:
>    This section describes new states to be added to the Datatracker to
>    make it possible for IETF WG Chairs and/or their delegates to
>    indicate the status of I-Ds associated with their working groups.

  What delegates? Secretaries?


Section 3.3., paragraph 2:
>    WG Chairs will have the option to use some, all or none of these WG
>    document states to describe the status of some, all or none of the
>    I-Ds associated with their WGs.

  Don't we want to recommend that they should use them for all of their
  documents though?


Section 3.3.1., paragraph 6:
>      Note that a document author may "shop" an I-D to multiple working
>      groups hoping to get the I-D adopted somewhere.  In order to track
>      this, the Datatracker will be enhanced to enable an I-D to be in
>      the "Candidate WG Document" state in more than one WG at a time.

  This sounds like we want to encourage shopping. Shouldn't the focus
  here be on adding functions that alert us to cases where shopping
  happens?


Section 3.3.3., paragraph 3:
>      Every "WG Document" should have an "intended maturity level" (e.g.
>      Informational, Proposed Standard, Experimental) associated with it
>      as described in Section 3.6.  This information is often requested
>      by IETF participants and it is now required by the IESG for every
>      I-D that is submitted to the IESG for publication.

  Not relevant for the purposes of this document.


Section 3.3.6., paragraph 0:
>  3.3.6. Parked WG Document

  Not clear if we need this state. Also, what it exactly means is
  unclear - does "parking" prevent a document from becoming expired?


Section 3.3.7., paragraph 0:
>  3.3.7. Dead WG Document

  How is this different from a "WG Document" that is "Expired"?


Section 3.4., paragraph 0:
> 3.4. Working Group Document State Diagram

  This section/diagram should really come before the detailed state
  descriptions earlier in Section 3.


Section 3.6., paragraph 0:
> 3.6. Intended Maturity Level of WG Documents

  Sure, but this document is supposed to be on ID states.

[Ballot discuss]
DISCUSS-DISCUSS: The title and abstract claim this document describes
  datatracker states. Reading the text, it's clear that the document
  also describes transitions between states, and this is where my rub is
  with the document: it's neither complete in describing these
  transitions, nor does it IMO necessarily characterize the possible or
  even typical transitions very accurately. (For example, starting
  Section 3.2.3 by saying that "IESG Evaluation is another state that
  may cause an I-D to be  sent back to an IETF WG for revision" really
  paints an incorrect picture of the common case.)


  DISCUSS: It seems that the model here is that three state machines
  exist: one for document availability (active/expired/replaced), one
  for the IESG, and one for the WG. The result is that a given document
  is in a specific state in all of these three state machines. This is
  not at all clearly explained in the document, it talks about the
  states of all three state machines interchangeably, which is really
  confusing. A clear overview with some diagrams would help a lot.
  (Section 3.4 has some of this, but much too late.)


Section 3.3.1., paragraph 4:
>        b) an I-D that the WG Chair asked an author to write;

  DISCUSS: I disagree that this makes an ID a candidate WG document.


Section 3.3.2., paragraph 0:
>  3.3.2. Adopted by a WG

  DISCUSS: We don't need this state. It's equivalent to applying "WG
  Document" to an individual ID.


Section 3.3.4., paragraph 0:
>  3.3.4. Adopted for WG Info Only

  DISCUSS: I don't think we need this state, it's equivalent to "WG
  Document" that never progress (or eventually progress to "Withdrawn".)


Section 3.3.5., paragraph 0:
>  3.3.5. Not Adopted by a WG

  DISCUSS: What purpose does this state serve other than to shame
  authors?


Section 3.5.4., paragraph 0:
>  3.5.4. Awaiting External Review / Resolution of Issues Raised

  DISCUSS: Because "external" really means "external to the WG", this
  state subsumes states 3.5.1, 3.5.2 and 3.5.3. Review-team specific
  states are not a good idea; for example, you'd immediately need to add
  "MIME Types Review", "URL Team Review", "TSV Directorate Review", etc.
  etc.


Appendix A:, paragraph 1:
>    This Appendix describes the status information currently stored in
>    the IETF Datatracker tool for every I-D submitted to the IESG for
>    publication.  Most of the terms and definitions herein are as in
>    [IESGSTAT].

  DISCUSS: These definitions should be identical to [IESGSTAT], because
  it is not the purpose of this document to redefine what those states
  mean. If the descriptions in [IESGSTAT] can be improved, let's make
  the changes there, please.

[Ballot comment]
I am in favor of publishing this document, as it would help to be transparent in WG processes.

I am agreeing with Sean's comments. Additionally, I have some comments of my own:

1) 3.3.3. WG Document

    Every "WG Document" should have an "intended maturity level" (e.g.
    Informational, Proposed Standard, Experimental) associated with it
    as described in Section 3.6.  This information is often requested
    by IETF participants and it is now required by the IESG for every
    I-D that is submitted to the IESG for publication.

I would like to point out that frequently the "intended maturity level" is decided quite late in the WG process. So I want to make sure that this information is not required early on.

2)  3.3.8. In WG Last Call

    A document in this state should remain "In WG Last Call" until the
    WG Chair moves it to another state.  The WG Chair may configure
    the Datatracker to send an e-mail after a specified period of time
    to remind or 'nudge' the Chair to conclude the WGLC and to
    determine the next state for the document.

Personally I prefer the way how IETF LCs work: IETF LC lasts for a specified period of time, after which the document automatically moves to "Waiting for AD Go-Ahead" state. I think the same should happen to documents in WGLCs.

3)  3.3.10. WG Consensus: Waiting for Write-Up

    A document in the "WG Consensus: Waiting for Write-Up" state has
    essentially completed its development within the working group,
    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
    a document shepherd.  The IESG requires that a document shepherd
    write-up be completed before publication of the I-D is requested.

This might be an abuse of process, but I don't think write-up is always required when publication is requested. I sent several documents to IETF LC without a write-up, I think this should be allowed.

4) 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]; the
  request could be from a WG Chair, or from an individual.  Note: the
  Secretariat (iesg-secretary@ietf.org) is copied on these requests to
  ensure that the request makes it into the Datatracker.

I don't think sending this to Secretariat is a requirement. All documents I've sponsored I entered into datatracker myself. So I suggest inserting the word "typically" before "copied".

  A document
  in this state has not (yet) been reviewed by an Area Director nor
  has any official action been taken yet, other than to note that its
  publication has been requested.

[Ballot comment]
#1) Sec 3.3.7 and Figure 1: If a document is dead to the WG, then can the author take it to another WG and begin the shopping process all over again?

#2) Sec 3.5: Should we add "Awaiting Media-Type Review / Resolution of Issues Raised" or more generally "Awaiting Expert Review" for any I-D that affects an IANA registry?

#3) Sec 3.6: Is it "Standard" or "Internet Standard"?  The title of section 4.1.3 of 2026 is the later.  2026 also uses the phrase when describing STDXXX.