[Docs] [txt|pdf] [Tracker] [WG] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01 03 04

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]  <https://datatracker.ietf.org/public/idindex.cgi>

   [2]  <https://datatracker.ietf.org/public/pidtracker.cgi>

   [3]  <http://www.ietf.org/internet-drafts/all_id.txt>



Rousskov                Expires December 7, 2006               [Page 13]


Internet-Draft       Draft Information Requirements            June 2006


   [4]  <http://www.ietf.org/internet-drafts/1id-index.txt>

   [5]  <http://www.ietf.org/internet-drafts/1id-abstracts.txt>

   [6]  <http://tools.ietf.org/wg/>

   [7]  <http://www.potaroo.net/ietf/>












































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]


Html markup produced by rfcmarkup 1.127, available from https://tools.ietf.org/tools/rfcmarkup/