New IETF Standards Track A. Rousskov Internet-Draft The Measurement Factory Expires: October 4, 2004 April 5, 2004 Declaring the State of an Internet Draft draft-rousskov-newtrk-id-state-00 Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http:// www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on October 4, 2004. Copyright Notice Copyright (C) The Internet Society (2004). All Rights Reserved. Abstract This memo describes a mechanism to relay the state(s) of an Internet Draft to the reader. This mechanism may be used, in part, to encourage or discourage review submission, test suite creation, and prototype implementation of the entire draft or its portions. The state of the draft is declared using a human-friendly notation suitable for automated extraction of standard states. Rousskov Expires October 4, 2004 [Page 1] Internet-Draft Declaring the State of an Internet Draft April 2004 Table of Contents 1. State of this Draft . . . . . . . . . . . . . . . . . . . . . 3 2. Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 4. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 5. Overall Operation . . . . . . . . . . . . . . . . . . . . . . 5 6. Declaration Format . . . . . . . . . . . . . . . . . . . . . . 6 7. Declaration Elements . . . . . . . . . . . . . . . . . . . . . 8 7.1 Boilerplate . . . . . . . . . . . . . . . . . . . . . . . . . 8 7.2 Draft-Name . . . . . . . . . . . . . . . . . . . . . . . . . . 8 7.3 Draft Parts . . . . . . . . . . . . . . . . . . . . . . . . . 9 7.4 Part States . . . . . . . . . . . . . . . . . . . . . . . . . 9 7.5 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 7.6 Trailer . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 8. Security Considerations . . . . . . . . . . . . . . . . . . . 11 9. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 9.1 Soliciting a review . . . . . . . . . . . . . . . . . . . . . 11 9.2 Testing a Feature . . . . . . . . . . . . . . . . . . . . . . 11 9.3 Combination of states . . . . . . . . . . . . . . . . . . . . 12 9.4 Discouraging feedback . . . . . . . . . . . . . . . . . . . . 12 9.5 Providing a hook for future use . . . . . . . . . . . . . . . 13 9.6 Minimum information . . . . . . . . . . . . . . . . . . . . . 13 A. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 13 Normative References . . . . . . . . . . . . . . . . . . . . . 13 Informative References . . . . . . . . . . . . . . . . . . . . 13 Author's Address . . . . . . . . . . . . . . . . . . . . . . . 14 Intellectual Property and Copyright Statements . . . . . . . . 15 Rousskov Expires October 4, 2004 [Page 2] Internet-Draft Declaring the State of an Internet Draft April 2004 1. State of this Draft This document complies with the Draft State specification[RFC XXXX]. Formal code following this paragraph provides the document version and describes the state of the document. More information about the document state may follow the code. If the actual version of this document does not match the encoded one, please disregard the entire state declaration as it is most likely stale. draft-rousskov-newtrk-id-state-00 state := { Draft :- Review Section "Security Considerations" :- Ignore } Please provide an early high-level review of this draft. Is an IETF-wide standard for documenting draft states needed? Is this draft a step in the right direction towards specifying such a standard? Should NEWTRK WG adopt this draft as a working group draft? The next revision of this draft is scheduled for 2004/04/15; reviews submitted prior to 2004/04/11 are likely to affect the next revision. Always check the latest published revision of this document for up-to-date information. 2. Motivation IETF publishes thousands of Internet Draft (ID) revisions per year. For a given ID, IETF versioning mechanism reflects the order of revision publications. While later revisions often correspond to more mature documents, it is generally impossible for the reader to know whether a particular revision of the draft is highly unstable, ready for thorough review, or suitable for a prototype implementation, etc. This uncertainty is even greater at the section of feature level of the draft because the state of one section or feature may be very different from another, even related section or feature. To make matters worse, it is common for working group drafts not to reflect working group opinion as a whole (until the draft is submitted for an archival publication). Usually, only draft authors and those closely following the draft have enough information to make statements about its state. This creates serious problems for others interested in the draft. For example, reviewers may not submit reviews assuming that the draft is too unstable or, vice versa, may submit a detailed review of the draft revision that is going to be hopelessly obsolete when the next revision is published the following morning. Rousskov Expires October 4, 2004 [Page 3] Internet-Draft Declaring the State of an Internet Draft April 2004 While it is sometimes easy to contact the draft authors for an advice, such a contact cannot be automated, often takes too much time, may not be possible for commercial secrecy reasons, or may be hindered by communication barriers. Moreover, authors or WG Chair opinion on the draft may not represent WG consensus, and contacting the entire WG may be an even less productive endeavor than contacting individuals. IETF RFCs solve a similar problem by using a set of RFC categories. Each category is well documented. While RFC categories have their own flaws (to be addressed by the New IETF Standards Track working group), they usually imply the state of an RFC with sufficient precision. Internet Drafts do not have similar categories. This document specifies a mechanism that explicitly tells the reader of an Internet Draft the state of that draft. The following effects are expected from wide use of the Draft State Declarations by IETF authors and groups: 1. Authors and WGs would think about and document the state of draft parts more often. This may prevent some of the late surprises in draft development and make it easier for new folks to contribute. 2. More draft readers will know what actions (e.g., review or prototyping) are appropriate. This may encourage review and testing. 3. Tools will be developed to facilitate the above changes. This may make it easy and quick to find drafts that are prime for review and allow for semi-automated monitoring of draft states by liaisons or technology users. That, in turn, may make early review solicitations more effective. 3. Scope The draft state declaration mechanism is designed for IETF Internet Drafts. The mechanism is applicable for both Working Group (WG) drafts and individual drafts. The mechanism is applicable to standards track and non-standards track drafts. The state declaration is removed when the draft becomes an archival document (XXX: why? do all archival documents have a sufficiently known state?). For WG drafts, published draft state declaration reflects WG rough consensus. Standard IETF rules apply to sensing or appealing such consensus. These rules and related caveats are beyond the scope of this draft. Similarly, for non-WG drafts, published draft state declaration reflects author(s) rough consensus. The ways to achieve Rousskov Expires October 4, 2004 [Page 4] Internet-Draft Declaring the State of an Internet Draft April 2004 or appeal such consensus are beyond the scope of this draft. Dealing with rogue or irresponsible authors or WGs is also beyond the scope of this draft. As any information in an Internet Draft, the state declaration does not require (but may receive) an IESG or other external review. As any ID publication, publication of an ID with the state declaration does not require an IESG or AD notification or approval. Other mechanisms that use draft state as a tool may require such reviews, notifications, approvals, etc. This document does not specify whether or how the state of the draft is communicated in the draft file name or in various draft indexes. 4. Terminology The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. When used with the normative meanings, these keywords will be all uppercase. Occurrences of these words in lowercase comprise normal prose usage, with no normative implications. The purpose of the remaining definitions is to simplify presentation by removing the necessity to distinguish individual drafts from WG drafts, single author from multiple authors, the entire draft from its parts, etc. The draft state declaration mechanism does not depend on those distinctions. author: ID author, authors, editor, or editors. WG: IETF working group or, in case of an individual ID, the author of the ID. draft part or portion: The entire Internet Draft or any, not necessarily sequential, portion of thereof. section: ID section, without regard to its nesting level (i.e., subsection, subsubsection, etc.). reader: Any draft reader or user, including internal and external reviewers, new WG participants, other WGs, IETF Area Director (AD), IESG, WG liaisons, and various automation tools. 5. Overall Operation When a WG reaches first rough consensus on a portion of the draft, Rousskov Expires October 4, 2004 [Page 5] Internet-Draft Declaring the State of an Internet Draft April 2004 the draft author SHOULD document that consensus in the draft. The author MAY use a dedicated section (XXX: which may cause section renumbering when the declaration is stripped from an RFC; should we address that?) or MAY place the declaration in an already existing section. The author MUST NOT create more than one state declarations per draft. The author submits the draft with the declaration for publication using the standard IETF submission procedure. For each revision of the draft that contains a draft state declaration, the author MUST validate the contents of the declaration against current WG rough consensus (WG consensus may change between publications). Replacing the outdated declaration content with a standard "unknown draft state" boilerplate is one way of keeping the declaration up to date. A reader of an Internet Draft familiar with the state declaration concept, searches for a reference to this specification or the boilerplate text. If found, the nearby formal record and informal comments relay WG opinion (at the draft submission time) on the draft state to the reader. Such opinion may, for example, encourage early review or discourage prototyping of certain features. The declaration trailer reminds the reader to look for the most recent revision of the draft. Internet Draft indexes and databases may extract and process formal records from draft state declarations to facilitate navigation through ID space or manage review solicitations. (XXX: add definition of full compliance elsewhere). 6. Declaration Format This section documents the draft state declaration format. Authors MUST use this format. Its trivial syntax allows for easy manual typesetting, for simple auto-processing of state declarations, and for reduction of stale declarations. The following template specifies format of the major draft state declaration parts, using the ABNF [RFC2234]. Rousskov Expires October 4, 2004 [Page 6] Internet-Draft Declaring the State of an Internet Draft April 2004 declaration = boilerplate [formal-record] [comments] trailer boilerplate = text formal-record = LF draft-name "state := {" LF states LF "}" comments = text trailer = text draft-name = token states = 1*part-state part-state = part ":-" state part = token state = token token = VCHAR *CHAR VCHAR ; subject to restrictions below phrase = 1*CHAR text = 1*phrase In addition to the explicit syntax rules defined by the above ABNF, the following rules apply: o Formal-record always follows "known state" boilerplate and never "unknown state" boilerplates (see Section 7.1 for boilerplates definitions. o Grammar elements can be surrounded by OPTIONAL whitespace. Besides traditional linear whitespace (LWSP), declaration whitespace includes draft headers, draft footers, and similar typesetting delimiters. o Tokens do not contain ":-", ":=", or LF. Draft formatting tools such as Marshall Rose's xml2rfc might eventually provide macros or dialogs to assist authors in declaring draft states. However, formatting tools MUST NOT insert or update the encoded draft revisions as it will defeat the mechanism for detecting stale declarations. (XXX: is this too formal? can we make it simpler but still allow for easy auto-extraction of draft name, revision, and states?) (XXX: is this too informal, especially the whitespace definition part? Will parsers be able to find/extract states without many hacks?) Rousskov Expires October 4, 2004 [Page 7] Internet-Draft Declaring the State of an Internet Draft April 2004 7. Declaration Elements This section describes major elements of a draft state declaration. 7.1 Boilerplate The following are the two boilerplate definitions, for known and unknown states. Authors MUST NOT use other boilerplates. known-state-boilerplate: This document complies with the Draft State specification[RFC XXXX]. Formal code following this paragraph provides the document version and describes the state of the document. More information about the document state may follow the code. If the actual version of this document does not match the encoded one, please disregard the entire state declaration as it is most likely stale. unknown-state-boilerplate: This document complies with the Draft State specification[RFC XXXX]. The state of this document is unknown. Later revisions of this document are likely to contain specific state information. Since not all WGs are aware or use draft state declarations, placing an unknown-state-boilerplate provides the reader with more information than simply omitting the section. It also makes it possible for IESG to require draft state declarations without requiring WGs to reach rough consensus on at least some part of each WG draft. 7.2 Draft-Name The author MUST replace the parameter in the formal-record element of the draft state declaration with the name and revision number of the draft being submitted for publication. This requirement is meant to help readers detect (and ignore) stale state information. (XXX: is there a better name/label for the draft-name element?) To obtain up-to-date published state information, human readers MUST find the most recent published draft and MUST check whether the in the declaration corresponds to that draft version. If the in draft state declaration does not match the actual draft name (including revision number), automated readers MUST NOT use or relay the state information in a way that implies the information is up-to-date. In other words, while it is OK to ignore (or warn about) mismatching draft-names, it is a violation of this specification to not check for the mismatch as failure to check will Rousskov Expires October 4, 2004 [Page 8] Internet-Draft Declaring the State of an Internet Draft April 2004 mislead human readers. 7.3 Draft Parts Standard part values are provided below along with their semantics. Authors MUST NOT provide descriptions for these standard parts in the comments section. This rule avoids misinterpretation of part semantics by readers, especially automated ones. Column characters (":") following part names below are formatting delimiters and are not part of the values. Draft: This part value refers to the entire document Section X: This part value refers to a specific section. The X parameter contains the number, title, or a similar visible section label that uniquely identifies the section within the document. Authors SHOULD NOT manually enter labels to avoid typos and inconsistencies with actual sections in the draft. When two overlapping parts are used with conflicting states, the state of the most specific part takes precedence for the overlapping region. For example, a review of the entire draft may be requested with an explicit instruction to ignore certain sections. When standard part values are not sufficient, authors MAY use other (extension) part values. 7.4 Part States Standard state values are provided below along with their semantics. Authors MUST NOT provide descriptions for these standard parts in the comments section. This rule avoids misinterpretation of state semantics by readers, especially automated ones. Column characters (":") following part names below are formatting delimiters and are not part of the values. Ignore: WG expects to rewrite the corresponding part in some major, profound way. While IETF peer reviews can be submitted at any time, reviewing this part is likely to be a waste of time. Review: WG solicits reviews of the corresponding part. Informal comments following the formal record may provide details about the review, including any deadlines. The WG expects to modify the corresponding part to address reviewer comments. Test: WG encourages early prototypes, experiments, and test suites to be developed for the corresponding part. The WG expects to modify the corresponding part to reflect early trials feedback. While Rousskov Expires October 4, 2004 [Page 9] Internet-Draft Declaring the State of an Internet Draft April 2004 IETF peer reviews can be submitted at any time, actual test results would be preferred to convince WG to change the corresponding part. Done: WG does not expect to modify the corresponding part in any way. WG expects the final version of the draft to be submitted with this part as it is written in this draft. Note that WG plans might change and that WG is not the only entity that can modify a draft. While IETF peer reviews can be submitted at any time, it would be difficult to convince WG to change the corresponding part. (XXX: should we add a standard "Help" state to indicate that the WG is looking for help writing the spec, not just review?) (XXX: should we add a standard "Consensus" state to indicate that the WG reached consensus for the specified part and implying that drafts without such state may not have WG consensus?) (XXX: should we add standard time/event conditions such as "frozen until YYYY/MM/DD"?) When standard state values are not sufficient, authors MAY use other (extension) state values. 7.5 Comments Authors MAY use the comment element to supply additional information related to some of the formally declared states. Comments become essential when non-standard part or state values are used, as their semantics would otherwise remain unknown. As already required above, authors must not redefine semantics of the standard parts and states using the comments element. 7.6 Trailer The following is the trailer text. The same trailer is used for known and unknown states. Authors MUST NOT use other trailers. trailer: Always check the latest published revision of this document for up-to-date information. The primary purpose of the trailer is to serve as a terminator of the draft state declaration, so that automated tools can extract or render the entire declaration. Without the trailer (e.g., if its information is moved to the boilerplates), it would be often impossible to auto-detect the presence of a comment or to find the end of a comment. RFC Editor may use this feature to automatically strip draft state declarations from Internet Drafts about to become Rousskov Expires October 4, 2004 [Page 10] Internet-Draft Declaring the State of an Internet Draft April 2004 RFCs. 8. Security Considerations None. 9. Examples This section contains informative examples of draft state declarations. 9.1 Soliciting a review This document complies with the Draft State specification[RFC XXXX]. Formal code following this paragraph provides the document version and describes the state of the document. More information about the document state may follow the code. If the actual version of this document does not match the encoded one, please disregard the entire state declaration as it is most likely stale. draft-ietf-opes-edge2edge-01 state := { Draft :- Review } Please provide an early review of this draft by 2004/04/30. Do not pay much attention to details. We are basically looking for architecture-level comments at this point. We are especially uncertain about Section 3.4 and the caching feature. Always check the latest published revision of this document for up-to-date information. 9.2 Testing a Feature This document complies with the Draft State specification[RFC XXXX]. Formal code following this paragraph provides the document version and describes the state of the document. More information about the document state may follow the code. If the actual version of this document does not match the encoded one, please disregard the entire state declaration as it is most likely stale. draft-ietf-tcp-proxy-04 state := { TCP splicing (IEEE:X.Zb) :- Test } While we received positive reviews, we are not sure that TCP splicing works, especially on pigeon networks. If you have resources, please test this feature, at least on the MUST level. Is it feasible to Rousskov Expires October 4, 2004 [Page 11] Internet-Draft Declaring the State of an Internet Draft April 2004 implement at all? Always check the latest published revision of this document for up-to-date information. 9.3 Combination of states This document complies with the Draft State specification[RFC XXXX]. Formal code following this paragraph provides the document version and describes the state of the document. More information about the document state may follow the code. If the actual version of this document does not match the encoded one, please disregard the entire state declaration as it is most likely stale. draft-ietf-cool-proto-11 state := { Draft :- Review Section 13.5 :- Ignore Section 13.6 :- Ignore client side rendering :- Test } Alan Smithee has reviewed client-side rendering rules (see Sections 3-5 and some bits in Section 10). It would be great to have a working compliance test suite _now_, before vendors rush this to market. If you review these and other sections, please try to send us feedback before the New Year. We plan to start working on the next generation server-side rules (sections 13.5 and 13.6) after that. Always check the latest published revision of this document for up-to-date information. 9.4 Discouraging feedback This document complies with the Draft State specification[RFC XXXX]. Formal code following this paragraph provides the document version and describes the state of the document. More information about the document state may follow the code. If the actual version of this document does not match the encoded one, please disregard the entire state declaration as it is most likely stale. draft-smithee-deadp-14 state := { Draft :- Done } I am going to submit this to RFC Editor for publication as an Informational RFC next week. There are already two implementations of this protocol. I am changing jobs and do not expect to work on this Rousskov Expires October 4, 2004 [Page 12] Internet-Draft Declaring the State of an Internet Draft April 2004 any more. IETF NG working group is going to work on the next generation of the protocol. Always check the latest published revision of this document for up-to-date information. 9.5 Providing a hook for future use This document complies with the Draft State specification[RFC XXXX]. The state of this document is unknown. Later revisions of this document are likely to contain specific state information. We expect to provide sate info after WG f2f meeting in May. Always check the latest published revision of this document for up-to-date information. 9.6 Minimum information This document complies with the Draft State specification[RFC XXXX]. The state of this document is unknown. Later revisions of this document are likely to contain specific state information.Always check the latest published revision of this document for up-to-date information. Appendix A. Acknowledgments The discussion about Working Group Snapshots [I-D.dawkins-newtrk-wgs] on the New IETF Standards Track (NEWTRK) WG mailing list inspired the creation of this document. Harald Tveit Alvestrand suggested adding formal descriptors to state declarations and reviewed an early version of this specification. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, November 1997. Informative References [I-D.dawkins-newtrk-wgs] Dawkins, S., "Working Group Snapshot (WGS)", draft-dawkins-newtrk-wgs-00 (work in progress), March 2004. Rousskov Expires October 4, 2004 [Page 13] Internet-Draft Declaring the State of an Internet Draft April 2004 Author's Address Alex Rousskov The Measurement Factory EMail: rousskov@measurement-factory.com URI: http://www.measurement-factory.com/ Rousskov Expires October 4, 2004 [Page 14] Internet-Draft Declaring the State of an Internet Draft April 2004 Intellectual Property Statement The IETF takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on the IETF's procedures with respect to rights in standards-track and standards-related documentation can be found in BCP-11. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementors or users of this specification can be obtained from the IETF Secretariat. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to practice this standard. Please address the information to the IETF Executive Director. Full Copyright Statement Copyright (C) The Internet Society (2004). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assignees. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION Rousskov Expires October 4, 2004 [Page 15] Internet-Draft Declaring the State of an Internet Draft April 2004 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Acknowledgment Funding for the RFC Editor function is currently provided by the Internet Society. Rousskov Expires October 4, 2004 [Page 16]