Tools team A. Rousskov Internet-Draft The Measurement Factory Expires: December 7, 2006 June 5, 2006 Requirements for Providing Information on IETF Internet-Drafts draft-ietf-tools-draft-info-04 Status of this Memo By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on December 7, 2006. Copyright Notice Copyright (C) The Internet Society (2006). Abstract This document specifies what information IETF should provide about an IETF Internet-Draft. Information requirements cover submitted, posted, published, expired, and other personal or Working Group drafts. Rousskov Expires December 7, 2006 [Page 1] Internet-Draft Draft Information Requirements June 2006 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. State of this draft version . . . . . . . . . . . . . . . . . 3 3. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 4. Notation and Terminology . . . . . . . . . . . . . . . . . . . 4 5. Status quo . . . . . . . . . . . . . . . . . . . . . . . . . . 4 6. Draft information . . . . . . . . . . . . . . . . . . . . . . 5 6.1. Draft identifier . . . . . . . . . . . . . . . . . . . . . 5 6.2. Draft metadata . . . . . . . . . . . . . . . . . . . . . . 6 6.2.1. Status . . . . . . . . . . . . . . . . . . . . . . . . 7 6.3. Draft versions . . . . . . . . . . . . . . . . . . . . . . 7 6.4. Change history . . . . . . . . . . . . . . . . . . . . . . 7 6.5. Draft events . . . . . . . . . . . . . . . . . . . . . . . 7 7. Draft Version . . . . . . . . . . . . . . . . . . . . . . . . 8 7.1. Version identifier . . . . . . . . . . . . . . . . . . . . 8 7.2. Version metadata . . . . . . . . . . . . . . . . . . . . . 8 7.2.1. Version number . . . . . . . . . . . . . . . . . . . . 8 7.2.2. Posting date . . . . . . . . . . . . . . . . . . . . . 9 7.2.3. Nits . . . . . . . . . . . . . . . . . . . . . . . . . 9 7.3. Primary version format . . . . . . . . . . . . . . . . . . 9 7.4. Version formats . . . . . . . . . . . . . . . . . . . . . 10 8. Format information . . . . . . . . . . . . . . . . . . . . . . 10 8.1. Format metadata . . . . . . . . . . . . . . . . . . . . . 10 8.2. Format data . . . . . . . . . . . . . . . . . . . . . . . 10 9. Security Considerations . . . . . . . . . . . . . . . . . . . 10 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 11. Compliance . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Appendix A. Comparison with current procedures . . . . . . . . . 11 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . . 11 Appendix C. Change log . . . . . . . . . . . . . . . . . . . . . 11 12. Normative References . . . . . . . . . . . . . . . . . . . . . 13 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 15 Intellectual Property and Copyright Statements . . . . . . . . . . 16 Rousskov Expires December 7, 2006 [Page 2] Internet-Draft Draft Information Requirements June 2006 1. Introduction Public Internet-Drafts are primary means of structured communication within IETF. The information that IETF currently provides about any given draft is decentralized and often insufficient to facilitate on- going draft review and use by IETFers and 3rd parties. The IETF Tools team recommends creation of a single, authoritative, and comprehensive IETF source for draft information. This document specifies what information IETF should provide about a draft and, to a limited extent, how that information needs to be provided. Most, if not all, requirements in this document are inspired by existing sources of draft information, both on official IETF web sites and sites administered outside of IETF. 2. State of this draft version This draft version is meant to contain a complete list of draft information items. Some items need more documentation and supplementary sections are missing content. Tools team review has started, but this version may not represent Tools team consensus. The text has not been polished. Please review this draft. Did we miss any draft information items you want IETF to provide? Should we remove some of the items? We are also looking for additional pointers to resources providing useful draft information. Please post your comments on tools-discuss@ietf.org mailing list or email them directly to the author. RFC Editor Note: Please remove this section for the final publication of the document. It has been inspired by draft-rousskov-newtrk-id-state and related NEWTRK WG discussions. 3. Scope The document scope is a single Internet-Draft, including multiple versions and formats of the same draft. The requirements cover submitted, posted, published, expired, and unknown personal or Working Group drafts. The interfaces required to locate a draft or correlate information about multiple drafts are out of scope. Rousskov Expires December 7, 2006 [Page 3] Internet-Draft Draft Information Requirements June 2006 4. Notation and Terminology This sections provides definitions for terms which are frequently used in this document. posted draft: A draft accepted into the public IETF draft repository and, hence, publicly available on the IETF web site. draft version: A meant-to-be-public snapshot of an Internet-Draft with a meant-to-be-unique version number. Also known as a "draft revision". draft format: Any draft source or presentation format, including original and preprocessed XML, original or generated plain text as well as PDF, PostScript, and HTML formats. Also known as a "version format". primary format: The first available draft format from the following list: plain text, PDF, PostScript, or XML. WG draft: A draft under a working group control. This document does not specify how to identify WG drafts, but most WG drafts have identifier (a.k.a. filename) that starts with "draft-ietf-". individual draft: A draft other than a WG draft. Normative requirements in this document are English phrases ending with an "(Rnnn/s)" mark, where "nnn" is a unique requirement number, and "s" is a single letter code ("a", "b", or "c") specifying the implementation stage for the requirement. . [[XXX1: Normative requirements have not been identified yet. --Alex]] This document does not specify how the implementation must obtain necessary draft information and does not require specific information rendering techniques. However, implementation hints or examples are often useful. To avoid mix up with normative requirements, such hints and examples are marked with a "Hint:" prefix. Implementation hints do not carry any normative force, and a different implementation may be the best choice. 5. Status quo At the time of writing, all of the draft information pieces described in this document are already available in one form or another. Here is an incomplete list of resources providing draft information. Note that provided information outside of this draft scope is not mentioned here. Rousskov Expires December 7, 2006 [Page 4] Internet-Draft Draft Information Requirements June 2006 o IETF "Internet-Drafts Database Interface" [1]: Provides draft title, status, state, intended RFC category, RFC number, related documents, abstract, author names and emails. Format: HTML. o IETF "Internet-Drafts Tracker" [2]: Provides draft name, version, status, state, shepherding AD name, modification date, WG name, and IESG discussion details. Format: HTML. o IETF "list of current and expired drafts" [3]: Provides draft name, version, date, status. Format: tab-separated text. o IETF "index of active drafts" [4]: Provides title, authors, date, name and WG for active drafts. Format: Free-form text. o IETF "abstracts from active drafts" [5]: Provides title, authors, date, name, abstract and WG for active drafts. Format: Free-form text. o Henrik Levkowetz "Workgroup Status Pages" [6]: Provides draft name, date, all draft versions, diffs, nits, various draft formats, and last call information. Format: XHTML. o Potaroo Internet Drafts Repository [7]: Provides draft name, date, author names, WG name, abstract. Includes expired drafts. Format: HTML. 6. Draft information The following information must be available about a given draft: o draft identifier (Section 6.1) o draft meta-data (Section 6.2) o available draft versions (Section 6.3) o change history (Section 6.4) o events (Section 6.5) [[XXX5: We need A defined XML schema in some form (Relax-NG, by example, or whatever) in which the information defined here has to be provided. --Henrik]] 6.1. Draft identifier Draft identifier is a string that uniquely identifies any IETF draft Rousskov Expires December 7, 2006 [Page 5] Internet-Draft Draft Information Requirements June 2006 regardless of its version or status. At the time of writing, draft name can be used as an identifier, but implementations must not rely on that being the case. For example, future implementations may be able to keep the same identifier for a draft that changes ownership from individual to WG (assuming IETF decides that ownership changes do not create a new draft and, hence, a new internal identifier). 6.2. Draft metadata Draft metadata depends, in part, on draft status and includes the following items: o title o abstract o authors information o WG name o draft status (Section 6.2.1) o IESG states (for active and expired drafts) o IESG draft discussion information o published document information such as the publication date and version location(s) (for published drafts) o email address for draft discussion and comments o "obsoletes X", "updates X", "renamed to X", or "replaced by X" statements where "X" is a draft, RFC, or another document. o IPR category, including a "custom" category for IPR statements that are not defined by IETF. Draft metadata applies to the draft as a whole rather than a specific draft version. Nevertheless, it is based on the latest draft version and, hence, may change with draft revisions. For example, the title and the abstract may be extracted from the latest draft version. All draft metadata must be available in format(s) suitable for human consumption and in XML format. The following metadata is meant to be extracted, at some processing Rousskov Expires December 7, 2006 [Page 6] Internet-Draft Draft Information Requirements June 2006 stage, from the latest draft version: creation date, expiration date, IPR category. This list is not exhaustive. 6.2.1. Status A draft status is either "active", "expired", "published", "replaced", or "withdrawn". The status determines a subset of available draft metadata. The status also affects the availability of draft text and possibility of future text revisions. An active draft can be in one or more states related to IESG review activity. These states are not documented here, but implementations must provide this information using the current state list and state definitions maintained by IESG. Published document information (e.g., an RFC number) is provided for published drafts. Replacement information (e.g., new draft name) is provided for replaced drafts. [[XXX6: Should we define exactly what extra info is provided for published and replaced drafts? --Alex]] 6.3. Draft versions Each draft has at least one draft version associated with it. Draft information includes a list of all draft versions, including the expired ones. This index allows the user to assess draft revision activity and to access information specific to any version of a given draft (see Section 7). It also allows to determine the latest draft version. 6.4. Change history Change history provides information about the difference between any two versions of a given draft. That information includes the difference in draft version metadata and in draft version content. Change history may be precomputed or generated runtime, possibly depending on the versions being compared. For example, the implementation may assume that most users would be interested in changes between sequential versions and precomputed that while providing runtime-generated differences between arbitrary two versions. 6.5. Draft events Draft events information includes a list of all issued IETF events associated with the draft. This document does not define an IETF event interface, but typical entries might include "new draft version available" and "WG last call issued" with such details as "event Rousskov Expires December 7, 2006 [Page 7] Internet-Draft Draft Information Requirements June 2006 time", "event originator", and "informal event comments". 7. Draft Version For each available draft version, the following information should be provided: o version identifier (Section 7.1) o version meta-data (Section 7.2) o primary version format (Section 7.3) o all available version formats (Section 7.4) 7.1. Version identifier Draft version identifier is a non-negative integer number that uniquely identifies any draft version of a given draft. Version identifier values must increase by one with every new draft version posted. At the time of writing, draft version number can be used as an identifier, but implementations must not rely on that being the case. For example, future implementations may be able to keep incrementing version identifier when a draft changes ownership from individual to WG. 7.2. Version metadata Draft version metadata includes the following items: o version number (Section 7.2.1) o posting date (Section 7.2.2) o nits (Section 7.2.3) 7.2.1. Version number For a given draft filename, draft version numbers start with zero and increase by one with every new version. Single-digit draft version numbers are usually left-padded with "0" when rendered. The IETF infrastructure may have a limit on the number of draft versions, but that limit may change with time. The difference between version number and version identifier is that Rousskov Expires December 7, 2006 [Page 8] Internet-Draft Draft Information Requirements June 2006 the former is specific to a given draft filename. The version identifier may, in theory, span multiple draft filenames, tracking revisions of the "same" draft across ownership transfers and other events that may change the draft filename. 7.2.2. Posting date Draft version posting date reports the calendar date when the draft version was first accepted into the public IETF draft repository. The date may also contain the time-of-day of the posting. 7.2.3. Nits Draft version nits is a set of auto-detected violations of IETF policies related to draft content and format. Until nits reporting is standardized, only the number of auto-detected violations may be meaningful for automated processing; the meaning and perceived severity of auto-detected violations is meant for human consumption only. Nits are not expected to be human-editable. Errors in auto-detection should be handled by fixing nits-generating tools. Omissions may be handled by manually submitting comments on the draft. Nits must contain information about the tool(s) that were used to generate them, including the version and configuration of each tool. The intent is to make it straightforward for authors and others to rerun the nits check after an attempt to fix violations in a private copy. If the nits-generating tool distinguishes violation severity levels (e.g., errors versus warnings), and different level nits are included in metadata, then the severity distinction should be reflected in the metadata. [[XXX12: Nits are the result of applying external rules on the draft presentation format, and the external rules may change during the lifetime of a version. --Henrik]] [[XXX13: On the other hand, mentioning the version of the nits tool used and perhaps providing a user with a way to regenerate/refresh nits would be useful. We should make nits violations visible to encourage folks to fix violations. --Alex]] 7.3. Primary version format Primary draft version format is a format identifier (see Section 8.1) that specifies which of the version formats should be used by default when presenting the draft to the reader. For the vast majority of Rousskov Expires December 7, 2006 [Page 9] Internet-Draft Draft Information Requirements June 2006 IETF drafts, "TXT" will be the primary format. 7.4. Version formats A set of format identifiers (see Section 8.1) representing all available draft version formats. It is possible for the set of available formats for a given draft version to change (e.g., if IETF converts old plain text drafts into XML, making both formats available). If the set changes, the draft metadata must be updated as a part of the change. 8. Format information 8.1. Format metadata Draft version format metadata includes the following items: o format identifier (TXT, HTML, PDF, or PS) o format MIME type o format size o format-specific info (e.g., number of pages for text formats or PDF-specific nits) [[XXX9: Should we standardize format IDs or will they depend on the draft information encoding mechanism? For example, Atom draft event feeds may use format IDs different from those used by the IETF draft repository. --Alex]] 8.2. Format data Draft version format data is the content (a.k.a., "text") of the draft version, in the corresponding format. 9. Security Considerations Draft information covered in this document does not contain security- sensitive elements. However, drafts may have secret or private information associated with them (e.g., some IESG discussions and comments may be private). Implementors must be careful to protect such information from being exposed by public metadata renders. [[XXX14: Is this actually true? Can there be secret IESG notes or other protected information associated with a draft? --Alex]] Rousskov Expires December 7, 2006 [Page 10] Internet-Draft Draft Information Requirements June 2006 Draft information may be collected from many places. The process of information collection and formatting may be resource-consuming. Care must be taken to prevent this process from overloading the machines it uses, especially if some information is extracted and formatted dynamically (at the time of the request for that information). 10. IANA Considerations None. [[XXX11: If we standardize format IDs (see XXX9), will IANA have to register them? --Alex]] 11. Compliance TBD. Appendix A. Comparison with current procedures This section summarizes major differences between information currently provided by IETF and what is being proposed, including violations of the current IETF rules. o Currently, IETF provides only the latest draft version. This document requires providing all unexpired versions. This change allows to maintain a change history useful for draft review and discussion. The change does not seem to contradict written IETF rules and principles. If an experiment with providing unexpired but obsolete versions does not cause significant problems, the IETF rules might be modified to also provide all draft versions for unexpired drafts and, later, all draft versions ever posted. Appendix B. Acknowledgments The author gratefully acknowledges the contributions of Henrik Levkowetz. Special thanks to Marshall Rose for his xml2rfc tool. Appendix C. Change log RFC Editor Note: This section is to be removed during the final publication of the document. Rousskov Expires December 7, 2006 [Page 11] Internet-Draft Draft Information Requirements June 2006 Internal WG revision control ID: $Id: draft-info.xml,v 1.8 2006/06/05 16:58:42 rousskov Exp $ version 04 * Added two security threats to the Security Considerations section. * Added "IESG draft discussion information" to the draft meta- information list (Henrik Levkowetz). * Added "updates X" to the possible draft meta-data statements (Henrik Levkowetz). * Explicitly included draft publication date and draft location (e.g., document retrieval URL) in "draft publication information". * Explicitly listed metadata which is meant to be extracted (Henrik Levkowetz). * Do not imply that an expired draft may have an IESG review stage. Being under IESG consideration now prevents a draft from expiring (Henrik Levkowetz). * Polished draft [version] format definition. * Resolved XXX4: avoid giving a precise WG draft definition until one is needed. * Resolved XXX7: Nits must contain info about nit generation tool, for re-checking purposes (Henrik Levkowetz). * Resolved XXX8: If nit generation tool distinguishes errors from warnings, and both are included in metadata, then the distinction must be present in metadata as well. * Resolved XXX10: Acknowledged that available formats might change for a given draft version and required the metadata to be updated if they change. * Added XXX12: Discuss whether to include nits summary (Henrik Levkowetz and Alex). Rousskov Expires December 7, 2006 [Page 12] Internet-Draft Draft Information Requirements June 2006 version 03 * Wrote the "Version metadata" section. * Deleted the "Email interface" and "Implementation stages" sections as they were empty and may not be needed. * Updated IPR claims to match the RFC 3978 template. version 02 * Resolved XXX2: this document will have its own set of term definitions, even though some may duplicate definitions in other Tools documents. (Henrik Levkowetz) * Added more IETF draft information sources and updated Henrik's' sources (Henrik Levkowetz) * Applied Henrik Levkowetz' review comments. version 01 * Added missing draft information pieces and claimed that this version lists all pieces we want to provide. Many items still lack details. * Separated draft information pieces into draft/version/format layers. * Added "Status quo" section: Documented what draft information is currently available and listed a few sites providing that information. More popular sites needed. version 00 * Initial version. 12. Normative References [RFC3978] Bradner, S., "IETF Rights in Contributions", BCP 78, RFC 3978, March 2005. [1] [2] [3] Rousskov Expires December 7, 2006 [Page 13] Internet-Draft Draft Information Requirements June 2006 [4] [5] [6] [7] Rousskov Expires December 7, 2006 [Page 14] Internet-Draft Draft Information Requirements June 2006 Author's Address Alex Rousskov The Measurement Factory Email: rousskov@measurement-factory.com URI: http://www.measurement-factory.com/ Rousskov Expires December 7, 2006 [Page 15] Internet-Draft Draft Information Requirements June 2006 Intellectual Property Statement The IETF takes no position regarding the validity or scope of any Intellectual Property Rights 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; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79. Copies of IPR disclosures made to the IETF Secretariat 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 implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org. Disclaimer of Validity This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Copyright Statement Copyright (C) The Internet Society (2006). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights. Acknowledgment Funding for the RFC Editor function is currently provided by the Internet Society. Rousskov Expires December 7, 2006 [Page 16]