Tools team A. Rousskov Internet-Draft The Measurement Factory Expires: April 26, 2006 October 23, 2005 Requirements for Providing Information on IETF Internet-Drafts draft-ietf-tools-draft-info-03 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 April 26, 2006. Copyright Notice Copyright (C) The Internet Society (2005). 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 April 26, 2006 [Page 1] Internet-Draft Draft Information Requirements October 2005 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 . . . . . . . . . . . . . . . . . . . . . 6 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 . . . . . . . . . . . . . . . . . . . . . 9 8. Format information . . . . . . . . . . . . . . . . . . . . . . 9 8.1. Format metadata . . . . . . . . . . . . . . . . . . . . . 10 8.2. Format data . . . . . . . . . . . . . . . . . . . . . . . 10 9. Security Considerations . . . . . . . . . . . . . . . . . . . 10 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 11. Compliance . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Appendix A. Comparison with current procedures . . . . . . . . . 10 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . . 11 Appendix C. Change log . . . . . . . . . . . . . . . . . . . . . 11 12. Normative References . . . . . . . . . . . . . . . . . . . . . 12 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 13 Intellectual Property and Copyright Statements . . . . . . . . . . 14 Rousskov Expires April 26, 2006 [Page 2] Internet-Draft Draft Information Requirements October 2005 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 April 26, 2006 [Page 3] Internet-Draft Draft Information Requirements October 2005 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. primary draft format: The first available draft format from the following list: plain text, PDF, PostScript, or XML. WG draft: A draft for which identifier (a.k.a. filename) is known and starts with "draft-ietf-". [[XXX4: This definition may need to be changed. In fact, we may be able to simply refer to the "current IETF definition" here because this document does not care what are the IETF rules for determining WG drafts! If referring to the "current IETF definition" is a good idea, what document should we refer to? Do we have to refer to any specific document? --Alex]] 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 Rousskov Expires April 26, 2006 [Page 4] Internet-Draft Draft Information Requirements October 2005 is an incomplete list of resources providing draft information. Note that provided information outside of this draft scope is not mentioned here. 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) Addition information such as a link to the "IESG draft discussion" tracking page, may be available but is outside of this document scope. Rousskov Expires April 26, 2006 [Page 5] Internet-Draft Draft Information Requirements October 2005 [[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 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 published document information (for published drafts) o email address for draft discussion and comments o "obsoletes X", "renamed to X", or "replaced by X" statements where "X" is a draft, RFC, or another document. 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. Rousskov Expires April 26, 2006 [Page 6] Internet-Draft Draft Information Requirements October 2005 [[XXX3: Should we list any fields that are meant-to-be extractable from the latest draft version? For example: creation date, expiration date, IPR boilerplate, formal references, required sections, etc. --Alex]] 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 or expired 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 Rousskov Expires April 26, 2006 [Page 7] Internet-Draft Draft Information Requirements October 2005 event interface, but typical entries might include "new draft version available" and "WG last call issued" with such details as "event 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. Rousskov Expires April 26, 2006 [Page 8] Internet-Draft Draft Information Requirements October 2005 The difference between version number and version identifier is that 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. [[XXX7: Should nits contain information about the tool that was used to generate each(?) nit? Including the version of the tool? --Alex]] [[XXX8: Should we standardize nits reporting? At least to the level of distinguishing warnings from errors? --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 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. [[XXX10: Can formats be added or deleted after the draft is posted? That is, what does "available" mean here? --Alex]] 8. Format information Rousskov Expires April 26, 2006 [Page 9] Internet-Draft Draft Information Requirements October 2005 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 TBD. 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. Rousskov Expires April 26, 2006 [Page 10] Internet-Draft Draft Information Requirements October 2005 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. Internal WG revision control ID: $Id: draft-info.xml,v 1.7 2005/10/23 18:10:46 rousskov Exp $ 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 claimes 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 Henriks' sources (Henrik Levkowetz) * Applied Henrik Levkowetz' review comments. Rousskov Expires April 26, 2006 [Page 11] Internet-Draft Draft Information Requirements October 2005 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] [4] [5] [6] [7] Rousskov Expires April 26, 2006 [Page 12] Internet-Draft Draft Information Requirements October 2005 Author's Address Alex Rousskov The Measurement Factory Email: rousskov@measurement-factory.com URI: http://www.measurement-factory.com/ Rousskov Expires April 26, 2006 [Page 13] Internet-Draft Draft Information Requirements October 2005 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 (2005). 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 April 26, 2006 [Page 14]