On RFC Streams, Headers, and Boilerplates
draft-iab-streams-headers-boilerplates-08

Status of this Memo

This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and 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 October 25, 2009.

Copyright Notice

Copyright (c) 2009 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents in effect on the date of publication of this document (http://trustee.ietf.org/license-info). Please review these documents carefully, as they describe your rights and restrictions with respect to this document.

Abstract

RFC documents contain a number of fixed elements such as the title page header, standard boilerplates and copyright/IPR statements. This document describes them and introduces some updates to reflect current usage and requirements of RFC publication. In particular, this updated structure is intended to communicate clearly the source of RFC creation and review.

Table of Contents

1.  Introduction
2.  RFC Streams and Internet Standards
3.  RFC Structural Elements
    3.1.  The title page header
    3.2.  The Status of this Memo
        3.2.1.  Paragraph 1
        3.2.2.  Paragraph 2
        3.2.3.  Paragraph 3
        3.2.4.  Noteworthy
    3.3.  Additional Notes
    3.4.  Other structural information in RFCs
4.  Security considerations
5.  IANA considerations
6.  RFC Editor Considerations
7.  References
    7.1.  Normative References
    7.2.  Informative References
Appendix A.  Some Example 'Status of this Memo' boilerplates
    A.1.  IETF Standards Track
    A.2.  IETF Experimental, with Consensus Call
    A.3.  IETF Experimental, No Consensus Call
    A.4.  IAB Informational
    A.5.  IRTF Experimental
Appendix B.  IAB members at time of approval
Appendix C.  Acknowledgements
Appendix D.  Document Editing Details
    D.1.  version 00->01
    D.2.  version 01->02
    D.3.  version 02->03
    D.4.  version 03->04
    D.5.  version 04->05
    D.6.  version 05->06
    D.7.  version 06->07
    D.8.  version 07->08
§  Authors' Addresses

1.  Introduction

Previously RFCs (e.g. [RFC4844] (Daigle, L. and Internet Architecture Board, “The RFC Series and RFC Editor,” July 2007.)) contained a number of elements that were there for historical, practical, and legal reasons. They also contained boilerplate material to clearly indicate the status of the document and possibly contained "Notes" to indicate how the document interacts with IETF Standards-Track documents.

As the RFC Series has evolved over the years, there has been increasing concern over appropriate labelling of the publications to make clear the status of each RFC and the status of the work it describes. Chiefly, there is a requirement that RFCs published as part of the IETF's review process not be easily confused with RFCs that may have had a very different review and approval process. Various adjustments have been made over the years, including evolving text of "Notes" included in the published RFC.

With the definition of the different RFC streams [RFC4844] (Daigle, L. and Internet Architecture Board, “The RFC Series and RFC Editor,” July 2007.), it is appropriate to formalize the definition of the various pieces of standard RFC boilerplate and introduce some adjustments to ensure better clarity of expression of document status, aligned with the review and approval processes defined for each stream.

This memo identifies and describes the common elements of RFC boilerplate structure, and provides a comprehensive approach to updating and using those elements to communicate, with clarity, RFC document and content status. Most of the historical structure information is collected from [RFC2223] (Postel, J. and J. Reynolds, “Instructions to RFC Authors,” October 1997.).

The changes introduced by this memo should be implemented as soon as practically possible after the document has been approved for publication.

2.  RFC Streams and Internet Standards

Users of RFCs should be aware that while all Internet Standards-related documents are published as RFCs, not all RFCs are Internet Standards-related documents.

The IETF is responsible for maintaining the Internet Standards Process, which includes the requirements for developing, reviewing and approving Standards Track and BCP RFCs. These, and any other standards-related documents (Informational or Experimental) are reviewed by appropriate IETF bodies and published as part of the IETF Stream.

Documents published in streams other than the IETF Stream are not generally reviewed by the IETF for such things as security, congestion control, or inappropriate interaction with deployed protocols. They have also not been subject to approval by the Internet Engineering Steering Group (IESG), including an IETF-wide last call. Therefore, the IETF disclaims, for any of the non-IETF Stream documents, any knowledge of the fitness of those RFCs for any purpose.

Refer to [RFC2026] (Bradner, S., “The Internet Standards Process -- Revision 3,” October 1996.), [I‑D.housley‑iesg‑rfc3932bis] (Alvestrand, H. and R. Housley, “IESG Procedures for Handling of Independent and IRTF Stream Submissions,” November 2008.), and [RFC4844] (Daigle, L. and Internet Architecture Board, “The RFC Series and RFC Editor,” July 2007.) and their successors for current details of the IETF process and RFC streams.

3.  RFC Structural Elements

3.1.  The title page header

This section describes the elements that are commonly found in RFCs published today. For the sake of clarity, this document specifies the elements precisely as a specification. However, this is not intended to specify a single, static format. Details of formatting are decided by the RFC Editor. Substantive changes to the header and boilerplate structure and content may be undertaken in the future, and are subject to general oversight and review by the IAB.

An RFC title page header can be described as follows:

------------------------------------------------------------------------
<document source>                                          <author name>
Request for Comments: <RFC number>                [<author affiliation>]
[<subseries ID> <subseries number>]    [more author info as appropriate]
[<RFC relation>:<RFC number[s]>]
Category: <category>
                                                            <month year>

------------------------------------------------------------------------

For example, a sample earlier RFC header is as follows:

------------------------------------------------------------------------
Network Working Group                                          T. Dierks
Request for Comments: 4346                                   Independent
Obsoletes: 2246                                              E. Rescorla
Category: Standards Track                                     RTFM, Inc.
                                                              April 2006

------------------------------------------------------------------------

The right column contains author name and affiliation information as well as the RFC publication month. Conventions and restrictions for these elements are described in RFC style norms and some individual stream definitions.

This section is primarily concerned with the information in the left column:

<document source>

This describes the area where the work originates. Historically, all RFCs were labeled Network Working Group. "Network Working Group" refers to the original version of today's IETF when people from the original set of ARPANET sites and whomever else was interested -- the meetings were open -- got together to discuss, design and document proposed protocols [RFC0003] (Crocker, S., “Documentation conventions,” April 1969.). Here, we obsolete the term "Network Working Group" in order to indicate the originating stream.

The <document source> is the name of the RFC stream, as defined in [RFC4844] (Daigle, L. and Internet Architecture Board, “The RFC Series and RFC Editor,” July 2007.) and its successors. At the time of this publication, the streams, and therefore the possible entries are:

• Internet Engineering Task Force
• Internet Architecture Board
• Internet Research Task Force
• Independent

Request for Comments: <RFC number>

This indicates the RFC number, assigned by the RFC Editor upon publication of the document. This element is unchanged.

<subseries ID> <subseries number>

Some document categories are also labeled as a subseries of RFCs. These elements appear as appropriate for such categories, indicating the subseries and the documents number within that series. Currently, there are subseries for BCPs [RFC2026] (Bradner, S., “The Internet Standards Process -- Revision 3,” October 1996.), STDs [RFC1311] (Postel, J., “Introduction to the STD Notes,” March 1992.), and FYIs [RFC1150] (Malkin, G. and J. Reynolds, “FYI on FYI: Introduction to the FYI Notes,” March 1990.). These subseries numbers may appear in several RFCs. For example, when a new RFC obsoletes or updates an old one, the same subseries number is used. Also, several RFCs may be assigned the same subseries number: a single STD, for example, may be composed of several RFCs, each of which will bear the same STD number. This element is unchanged.

[<RFC relation>:<RFC number[s]>]

Some relations between RFCs in the series are explicitly noted in the RFC header. For example, a new RFC may update one or more earlier RFCs. Currently two relationships are defined: "Updates", and "Obsoletes" [RFC2223] (Postel, J. and J. Reynolds, “Instructions to RFC Authors,” October 1997.). Variants like "Obsoleted by" are also used (e.g in [RFC5143] (Malis, A., Brayley, J., Shirron, J., Martini, L., and S. Vogelsang, “Synchronous Optical Network/Synchronous Digital Hierarchy (SONET/SDH) Circuit Emulation Service over MPLS (CEM) Encapsulation,” February 2008.)). Other types of relationships may be defined by the RFC Editor and may appear in future RFCs.

Category: <category>

This indicates the initial RFC document category of the publication. These are defined in [RFC2026] (Bradner, S., “The Internet Standards Process -- Revision 3,” October 1996.). Currently, this is always one of: Standards Track, Best Current Practice, Experimental, Informational, or Historic. This element is unchanged.

3.2.  The Status of this Memo

The "Status of This Memo" describes the category of the RFC, including the distribution statement. This text is included irrespective of the source stream of the RFC.

The "Status of This Memo" will start with a single sentence describing the status. It will also include a statement describing the stream-specific review of the material (which is stream-dependent). This is an important component of status, insofar as it clarifies the breadth and depth of review, and gives the reader an understanding of how to consider its content.

3.2.1.  Paragraph 1

The first paragraph of the Status of this Memo section contains a single sentence, clearly standing out. It depends on the category of the document.

For 'Standards Track' documents:

"This is an Internet Standards Track document."

For 'Best Current Practices' documents:

"This memo documents an Internet Best Current Practice."

For other categories

"This document is not an Internet Standards Track specification; <it is published for other purposes>."

For Informational, Experimental, Historic and future categories of RFCs, the RFC editor will maintain an appropriate text for <it is published for other purposes>. Initial values are:

Informational:

"it is published for informational purposes."

Historic:

"it is published for the historical record."

Experimental:

"it is published for examination, experimental implementation, and evaluation."

3.2.2.  Paragraph 2

The second paragraph of the "Status of This Memo" will now include a paragraph describing the type of review and exposure the document has received. This is defined on a per-stream basis, subject to general review and oversight by the RFC Editor and IAB. There is a specific structure defined here to ensure there is clarity about review processes and document types. These paragraphs will need to be defined and maintained as part of RFC stream definitions. Initial text, for current streams, is provided below.

The paragraph may include some text that is specific to the initial document category, as follows: when a document is Experimental or Historic the second paragraph opens with:

Experimental:

"This document defines an Experimental Protocol for the Internet community."

Historic:

"This document defines a Historic Document for the Internet community."

The text that follows is stream dependent -- these are initial values and may be updated by stream definition document updates.

IETF Stream:

"This document is a product of the Internet Engineering Task Force (IETF)."

If there has been an IETF consensus call per IETF process, an additional sentence should be added: "It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG)." If there has not been such a consensus call then this simply reads: "It has been approved for publication by the Internet Engineering Steering Group (IESG)."

IAB Stream:

"This document is a product of the Internet Architecture Board (IAB), and represents information that the IAB has deemed valuable to provide for permanent record."

IRTF Stream:

"This document is a product of the Internet Research Task Force (IRTF). The IRTF publishes the results of Internet-related research and development activities. These results might not be suitable for deployment."

In addition a sentence indicating the consensus base within the IRTF may be added: "This RFC represents the consensus of the <insert_name> Research Group of the Internet Research Task Force (IRTF)." or alternatively "This RFC represents the individual opinion(s) of one or more members of the <insert_name> Research Group of the Internet Research Task Force (IRTF)".

Independent Stream:

"This is a contribution to the RFC Series, independently of any other RFC stream. The RFC Editor has chosen to publish this document at its discretion and makes no statement about its value for implementation or deployment.

For non-IETF stream documents a reference to Section 2 (RFC Streams and Internet Standards) of this RFC is added with the following sentence: "Documents approved for publication by the [stream approver -- currently, one of: "IAB", "IRSG", or "RFC Editor"] are not a candidate for any level of Internet Standard; see Section 2 (RFC Streams and Internet Standards) of RFC XXXX."

For IETF stream documents a similar reference is added: "Further information on [BCPs or Internet Standards] is available in Section 2 (RFC Streams and Internet Standards) of RFC XXXX." for BCP and Standard Track documents; "Not all documents approved by the IESG are candidate for any level of Internet Standards; see Section 2 (RFC Streams and Internet Standards) of RFC XXXX." for all other categories.

3.2.3.  Paragraph 3

The boilerplate ends with a reference to where further relevant information can be found. This information may include, subject to the RFC Editor's discretion, information whether the RFC has been updated or obsoleted, the RFC's origin, a listing of possible errata, information about how to provide feedback and suggestion, and information on how to submit errata as described in [I‑D.rfc‑editor‑errata‑process] (Ginoza, S., Hagens, A., and R. Braden, “RFC Editor Proposal for Handling RFC Errata,” May 2008.). The exact wording and URL is subject to change (at the RFC Editor's discretion), but current text is:

"Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/<static-path>/rfc<rfc-no>.html"

3.2.4.  Noteworthy

Note that the texts in paragraph 1 and 2 of the boilerplate indicate the initial status of a document. During their lifetime documents can change status to e.g. Historic. This cannot be reflected in the document itself and will need be reflected in the information refered to in Section 3.4 (Other structural information in RFCs).

3.3.  Additional Notes

Exceptionally, a review and publication process may prescribe additional notes that will appear as labelled notes after the "Status of This Memo".

While this has been a common feature of recent RFCs, it is the goal of this document to make the overall RFC structure adequately clear to remove the need for such notes, or at least make their usage truly exceptional.

3.4.  Other structural information in RFCs

RFCs contain other structural informational elements. The RFC Editor is responsible for the positioning and layout of these structural element. Note also that new elements may be introduced or obsoleted using a process consistent with [RFC4844] (Daigle, L. and Internet Architecture Board, “The RFC Series and RFC Editor,” July 2007.). These additions may or may not require documentation in an RFC.

Currently the following structural information is available or is being considered for inclusion in RFCs:

Copyright Notice

A copyright notice with a reference to BCP78 [BCP78] (Bradner, S., Ed. and J. Contreras, Ed., “Rights Contributors Provide to the IETF Trust,” November 2008.) and an Intellectual Property statement referring to BCP78 and BCP79 [BCP79] (Bradner, S., Ed. and T. Narten, Ed., “Intellectual Property Rights in IETF Technology,” April 2007.). The content of these statements are defined by those BCPs.

ISSN

The International Standard Serial Number [ISO3297] (Technical Committee ISO/TC 46, Information and documentation, Subcommittee SC 9, Identification and description., “Information and documentation - International standard serial number (ISSN),” 09 2007.): ISSN 2070-1721. The ISSN uniquely identifies the RFC series as title regardless of language or country in which it is published. The ISSN itself has no significance other than the unique identification of a serial publication.

4.  Security considerations

This document tries to clarify the descriptions of the status of an RFC. Misunderstanding the status of a memo could cause interoperability problems, hence security and stability problems.

5.  IANA considerations

None.

6.  RFC Editor Considerations

The RFC Editor is responsible for maintaining the consistency of the RFC series. To that end the RFC Editor maintains a style manual [RFC‑style] (RFC Editor, “RFC Style Guide,” .). In this memo we mention a few explicit structural elements that the RFC editor needs to maintain. The conventions for the content and use of all current and future elements are to be documented in the style manual.

Adding a reference to the stream in the header of RFCs is only one method for clarifying from which stream an RFC originated. The RFC editor is encouraged to add such indication in e.g. indices and interfaces.

[The rest of this section contains specific instructions towards editing this document and can be removed before publication]

The documents has two sections, including this one that need to be removed before publication as an RFC. This one and Appendix D (Document Editing Details).

This memo introduces a number of modifications that will have to be implemented in various tools, such as the xml2rfc tool, the nit tracker and the rfc-erratum portal.

The number "XXXX" is to be replaced with RFC number of this memo.

References [RFC‑style] (RFC Editor, “RFC Style Guide,” .), [BCP78] (Bradner, S., Ed. and J. Contreras, Ed., “Rights Contributors Provide to the IETF Trust,” November 2008.) and [BCP79] (Bradner, S., Ed. and T. Narten, Ed., “Intellectual Property Rights in IETF Technology,” April 2007.) have been constructed. Please bring these in line with RFC Editorial conventions.

In section Section 3.4 (Other structural information in RFCs): For the final publication, it should be warranted that the ISSN is *not* split by a line break, for clarity.

The URL in Appendix A (Some Example 'Status of this Memo' boilerplates) should be replaced with whatever the RFC Editor decides upon.

7.  References

7.1. Normative References

7.2. Informative References

Appendix A.  Some Example 'Status of this Memo' boilerplates

[Editor note: The URLs used in this example are examples.]

A.1.  IETF Standards Track

The boilerplate for a Standards Track document that (by definition) has been subject to an IETF consensus call.

------------------------------------------------------------------------
Status of this Memo

    This is an Internet Standards Track document.

    This document is a product of the Internet Engineering Task Force
    (IETF).  It represents a consensus of the IETF community.  It has
    received public review and has been approved for publication by
    the Internet Engineering Steering Group. Further information on
    the Internet Standards Track is available in Section 2 of RFC
    XXXX."

    Information about the current status of this document,  any
    errata, and how to provide feedback on it may be obtained at
    http://www.rfc-editor.org/status/rfc0000.html

------------------------------------------------------------------------

A.2.  IETF Experimental, with Consensus Call

The boilerplate for an Experimental document that has been subject to an IETF consensus call.

------------------------------------------------------------------------
Status of this Memo

    This document is not an Internet Standards Track specification; it
    has been published for Experimental purposes.

    This document defines an Experimental Protocol for the Internet
    community.  Discussion and suggestions for improvement are
    requested.  This document is a product of the Internet Engineering
    Task Force (IETF).  It represents a consensus of the IETF
    community.  It has received public review and has been approved
    for publication by the Internet Engineering Steering Group
    (IESG). Not all documents approved by the IESG are candidate for
    any level of Internet Standards see Section 2 of RFC XXXX.

    Information about the current status of this document,  any
    errata, and how to provide feedback on it may be obtained at
    http://www.rfc-editor.org/status/rfc0000.html
------------------------------------------------------------------------

A.3.  IETF Experimental, No Consensus Call

The boilerplate for an Experimental document that not has been subject to an IETF consensus call.

------------------------------------------------------------------------
Status of this Memo

    This document is not an Internet Standards Track specification; it
    has been published for Experimental purposes.

    This document defines an Experimental Protocol for the Internet
    community. This document is a product of the Internet Engineering
    Task Force (IETF). It has been approved for publication by the
    Internet Engineering Steering Group.  Not all documents approved
    by the IESG are candidate for any level of Internet Standards see
    Section 2 of RFC XXXX.

    Information about the current status of this document,  any
    errata, and how to provide feedback on it may be obtained at
    http://www.rfc-editor.org/status/rfc0000.html
------------------------------------------------------------------------

A.4.  IAB Informational

The boilerplate for an Informational IAB document.

------------------------------------------------------------------------
Status of this Memo

    This document is not an Internet Standards Track specification; it
    has been published for Informational purposes.

    This document is a product of the Internet Architecture Board
    (IAB), and represents information that the IAB has deemed valuable
    to provide for permanent record. Documents approved for
    publication by the IAB are not a candidate for any level of
    Internet Standard; see Section 2 of RFC XXXX."

    Information about the current status of this document,  any
    errata, and how to provide feedback on it may be obtained at
    http://www.rfc-editor.org/status/rfc0000.html
------------------------------------------------------------------------

A.5.  IRTF Experimental

The boilerplate for an Experimental document that has been produced by the IRTF and for which there was no RG consensus. This variation is the most verbose boilerplate in the current set.

------------------------------------------------------------------------
Status of this Memo

    This document is not an Internet Standards Track specification; it
    has been published for Experimental purposes.

    This document defines an Experimental Protocol for the Internet
    community. This document is a product of the Internet Research
    Task Force (IRTF).  The IRTF publishes the results of Internet-
    related research and development activities.  These results might
    not be suitable for deployment. This RFC represents the individual
    opinion(s) of one or more members of the BLAFOO Research Group of
    the Internet Research Task Force (IRTF).  Documents approved for
    publication by the IRTF are not a candidate for any level of
    Internet Standard; see Section 2 of RFC XXXX."

    Information about the current status of this document,  any
    errata, and how to provide feedback on it may be obtained at
    http://www.rfc-editor.org/status/rfc0000.html
------------------------------------------------------------------------

Appendix B.  IAB members at time of approval

The IAB members at the time this memo was approved were (in alphabetical order): Loa Andersson, Gonzalo Camarillo, Stuart Cheshire, Russ Housley, Olaf Kolkman, Gregory Lebovitz, Barry Leiba, Kurtis Lindqvist, Andrew Malis, Danny McPherson, David Oran, Dave Thaler, and Lixia Zhang. In addition, the IAB included two ex-officio members: Dow Street, who was serving as the IAB Executive Director, and Aaron Falk, who was serving as the IRTF Chair.

Appendix C.  Acknowledgements

Thanks to Bob Braden, Brian Carpenter, Steve Crocker, Sandy Ginoza, and John Klensin who provided background information and inspiration.

Various people have made suggestions that improved the document. Among them are: Lars Eggert, Alfred Hoenes, and Joe Touch.

This document was produced using the xml2rfc tool [RFC2629] (Rose, M., “Writing I-Ds and RFCs using XML,” June 1999.).

Appendix D.  Document Editing Details

[To Be Removed before publication]

$Id: headers-boilerplates.xml 83 2009-04-23 06:35:05Z olaf $

D.1.  version 00->01

Fixed the header so it appropriately shows that the document updates RFC 4844, 2223. And added a link to 3932-bis that should appear in tandem with this publication.

Introduced the "Other structural information in RFCs" section and moved the ISSN number from the front matter to this section. The "Other structural information in RFCs" intends to give very rough guidance providing the RFC editor with sufficient freedom to move pieces around and edit them to please the eye and mind.

Modified the last sentence 3rd paragraph of the Status of this memo section for the IRTF Stream in accordance to a suggestion by Aaron Falk; Indicating that review happened by the IRSG and not indicating that review did not happen by the IESG.

Introduced the square brackets around the <author affiliation> in the header. To highlight this is an optional element.

The definition of the "Clarifies" relation has been taken out. There are arguments that introducing the relation needs a bit more thought and is better done by a separate document.

Provided the RFC Editor with responsibility to maintain several text pieces.

In Section 3.2 (The Status of this Memo) some modifications were applied to the text.

The <description> contains the full name of the stream.

RFC2223 and 4844 moved to the informative reference section. Although I am not sure if those are not normative. Guidance!!!

D.2.  version 01->02

Fixed some editorial nits and missing references.

Clarified that the status and category are initial.

Added boilerplate text for documents that are initially published as Historic.

Added members of IAB, and removed those members from acknowledgements

Added References to BCP78 and BCP79. The exact formatting of those references may need to be done by the RFC editor.

Added text to recognize occurrences of variations of "Obsolete" and "Update"

D.3.  version 02->03

Stray language in the "IAB members at time of approval" section removed.

D.4.  version 03->04

Addressed the minor nit from Brian Carpenter.

Reference to style guide stet to styleguide.html

D.5.  version 04->05

References updated to reflect BCP78 being updated

Submitted under new boilerplate

Rewording of boilerplate material based on rfc-interest discussion starting with http://mailman.rfc-editor.org/pipermail/rfc-interest/2008-December/001078.html

Added examples in Appendix A

D.6.  version 05->06

Nits corrected

Fixede Boilerplate for IETF stream document without IETF consensus.

Corruption of examples due to XML bug corrected

D.7.  version 06->07

Nits corrected

Fixed inconsistency: Request for feedback only appeared in the Experimental category, moved this to the "Update to this memo section"

Changed the content of the 3rd paragraph of document status to be a static (per stream) pointer to finding more information about the document status, errata, and providing feedback. This was to address the concern of having dynamic (per-document) text in the boilerplate, if this "updates" section was document specific.

D.8.  version 07->08

Introduced language to clarify that the RFC Editor is responsible for details with respect to style and formatting.

Authors' Addresses