Updated RFC Format Framework
draft-rswg-rfc7990-updates-08

Network Working Group                                         P. Hoffman
Internet-Draft                                                     ICANN
Obsoletes: 7990 (if approved)                                H. Flanagan
Updates: 9280 (if approved)                     Spherical Cow Consulting
Intended status: Informational                             11 April 2024
Expires: 13 October 2024

                      Updated RFC Format Framework
                     draft-rswg-rfc7990-updates-08

Abstract

   In order to improve the readability of RFCs while supporting their
   archivability, the definitive version of the RFC Series transitioned
   from plain-text ASCII to XML using the RFCXML vocabulary; different
   publication versions are rendered from that base document.  This
   document is the framework that provides the problem statement, lays
   out a road map of the documents that capture the specific
   requirements, and describes how RFCs are published.

   This document obsoletes RFC 7990.  This document also updates the
   stability policy in RFC 9280.

   This draft is part of the RFC Series Working Group (RSWG); see
   https://datatracker.ietf.org/edwg/rswg/documents/
   (https://datatracker.ietf.org/edwg/rswg/documents/).  There is a
   repository for this draft at https://github.com/paulehoffman/draft-
   rswg-rfc7990-updates (https://github.com/paulehoffman/draft-rswg-
   rfc7990-updates).

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   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."

   This Internet-Draft will expire on 13 October 2024.

Hoffman & Flanagan       Expires 13 October 2024                [Page 1]
Internet-Draft              Format Framework                  April 2024

Copyright Notice

   Copyright (c) 2024 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 (https://trustee.ietf.org/
   license-info) in effect on the date of publication of this document.
   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
     1.1.  Changes to RFC 7990 . . . . . . . . . . . . . . . . . . .   3
     1.2.  Changes to RFC 9280 . . . . . . . . . . . . . . . . . . .   4
     1.3.  Key Changes from the Earlier RFC Process  . . . . . . . .   5
   2.  Definitive Version of an RFC  . . . . . . . . . . . . . . . .   5
     2.1.  Updating the Definitive Version of an RFC . . . . . . . .   6
     2.2.  Expected Updates to RFCXML  . . . . . . . . . . . . . . .   6
   3.  Publication Versions  . . . . . . . . . . . . . . . . . . . .   6
   4.  Archived Documents  . . . . . . . . . . . . . . . . . . . . .   7
   5.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   7
   6.  Security Considerations . . . . . . . . . . . . . . . . . . .   7
   7.  Acknowledgments . . . . . . . . . . . . . . . . . . . . . . .   7
   8.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   7
     8.1.  Normative References  . . . . . . . . . . . . . . . . . .   8
     8.2.  Informative References  . . . . . . . . . . . . . . . . .   8
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .   8

1.  Introduction

   "RFC Series Format Requirements and Future Development" [RFC6949]
   discussed the need to improve the display of items such as author
   names and artwork in RFCs as well as the need to improve the ability
   of RFCs to be displayed properly on various devices.  Based on the
   discussions with communities of interest, such as the IETF, the RFC
   Series Editor decided to explore a change to the format of the
   Series.  [RFC7990] was the culmination of that exploration.  This
   document serves as the framework that describes the problems that
   were solved and summarizes the documents created to date that capture
   the specific requirements for each aspect of the change in format.

Hoffman & Flanagan       Expires 13 October 2024                [Page 2]
Internet-Draft              Format Framework                  April 2024

   This document is concerned with the production of RFCs, focusing on
   the published documents.  It does not address any changes to the
   processes each stream uses to develop and review their submissions
   (specifically, how Internet-Drafts will be developed).  While I-Ds
   have a similar set of issues and concerns, directly addressing those
   issues for I-Ds will be discussed within each document stream.

   The details described in this document are expected to continue to
   change over time as the community and the RFC Production Center (RPC)
   gains further experience with the components of the framework.

   Implementors of those components are advised to avoid assuming that
   all such changes will be backwards-compatible.

1.1.  Changes to RFC 7990

   [RFC7990] defined a framework for how RFCs would be published after
   that document was published, including new formats and a new
   "canonical format" for archiving RFCs.  It talked about "the XML
   file" as if there would only be one XML file for an RFC because that
   was the expectation at the time [RFC7990] was published.  It also
   talked about "publication formats" as the versions of HTML, text, and
   PDF derived from the "canonical format".

   After extensive experience with publishing RFCs in the RFCXML format
   [RFC7991], it has been decided that an RFC's XML file can be updated
   for narrowly limited purposes.  This document changes [RFC7990] in
   significant ways:

   *  It defines four terms that replace the use of the term "canonical"
      and clarifies "format":

      -  The "definitive format", which is RFCXML

      -  The "definitive version", which is a published RFC in the
         definitive format

      -  A "publication format", which is currently one of PDF, plain
         text, or HTML

      -  A "publication version", which is a published RFC in one of the
         publication formats

   *  It defines a policy governing how the RFCXML format changes.

   *  It defines a policy for when the definitive version of an RFC can
      be updated and older versions archived.

Hoffman & Flanagan       Expires 13 October 2024                [Page 3]
Internet-Draft              Format Framework                  April 2024

   *  It defines a policy for when the publication versions of an RFC
      can be updated and older versions archived.

   When using the new terminology, it is important to note that
   [RFC7990] used the term "canonical format" to mean two very different
   things.  Quoting from RFC 7990:

      Canonical format: the authorized, recognized, accepted, and
      archived version of the document

   and

      At the highest level, the changes being made to the RFC format
      involve breaking away from solely ASCII plain text and moving to a
      canonical format that includes all the information required for
      rendering a document into a wide variety of publication formats.

   This document uses two terms, "definitive version" and "definitive
   format", for the earlier term "canonical format".

   Other terminology changes made by this document are the following: -
   It changes the phrase "xml2rfc version 3" to "RFCXML". - It changes
   the name of the body that publishes RFCs from "RFC Editor" to "RFC
   Production Center (RPC)".

   Historical text from [RFC7990] such as Section 2 ("Problem
   Statement"), Section 4 ("Overview of the Decision-Making Process"),
   and Section 10 ("Transition Plan") are not copied to this document.

1.2.  Changes to RFC 9280

   Section 7.6 of [RFC9280] currently says:

      Once published, RFC Series documents are not changed.

   This document replaces that sentence with:

      Once published, RFC Series documents may be re-issued, but the
      semantic content of published documents shall be preserved to the
      greatest extent possible.

   This document also creates a new policy that would exist in Section 7
   of [RFC9280]:

      7.8.  Consistency

Hoffman & Flanagan       Expires 13 October 2024                [Page 4]
Internet-Draft              Format Framework                  April 2024

      The series as a whole is consistently presented.  RFCs are
      copyedited, formatted, published, and may be reissued to maintain
      a consistent presentation.

   Section 2.1 and Section 3 in this document are based on this updated
   policy in [RFC9280].

1.3.  Key Changes from the Earlier RFC Process

   The first RFC to be published following the guidance of the group of
   RFCs described in [RFC7990] was [RFC8650], published in November
   2019.  In the time since then, all published RFCs have followed the
   general plan from [RFC7990].

   At the highest level, the changes that [RFC7990] made to the RFC
   format involved breaking away from solely ASCII ([RFC20]) plain text
   and moving to a definitive format that includes all the information
   required for rendering a document into a wide variety of publication
   formats.  The RPC became responsible for more than just the plain-
   text file and a PDF rendering that was created from the plain text at
   the time of publication; the RPC now creates the definitive version
   and three publication versions of the RFC in order to meet the
   diverse requirements of the community.

   The final RFCXML file produced by the RPC is the definitive version
   for RFCs; it holds all the information intended for an RFC.
   Additional publication versions (HTML, PDF, and plain text) are also
   published by the RPC.  The publication formats are described in
   Section 3 and fully specified in other RFCs.

2.  Definitive Version of an RFC

   The definitive version produced by the RPC is the version that holds
   all the information intended for an RFC.  The RPC may change the
   definitive version of an RFC over time (that is, change the XML
   file), as described in Section 2.1.  See [RFC7991] for the original
   complete description of the RFCXML syntax and semantics.

   The XML may contain SVG line art, as originally described in
   [RFC7996].  That SVG will also appear in the HTML publication
   versions.  The XML may contain non-ASCII characters, as originally
   described in [RFC7997].  These characters will appear in all the
   publication versions.

   The published XML file must contain all information necessary to
   render the specified publication versions; any question about what
   was intended in the publication will be answered from this file.  It
   is self-contained with all the information known at publication time.

Hoffman & Flanagan       Expires 13 October 2024                [Page 5]
Internet-Draft              Format Framework                  April 2024

   For instance, all features that reference externally defined input
   are expanded.  It does not contain src attributes for <artwork> or
   <sourcecode> elements.  It does not contain comments or processing
   instructions.

2.1.  Updating the Definitive Version of an RFC

   RFCs may be re-issued, as described in Section 1.2.  Such changes
   will seek to preserve the semantics expressed in the original RFC.
   Reasons for such changes include updates to the RFCXML schema, errors
   discovered in the XML, and changes to the tooling used to generate
   the publication versions of the definitive XML version of the RFC.
   The RPC will keep a public record of when it re-issues any RFC, and
   give a short description of its reasoning for each change.

2.2.  Expected Updates to RFCXML

   It is anticipated that the syntax and semantics in [RFC7991] will be
   updated.  Updates to the RFCXML specification that are applied to
   existing RFCs should preserve to the greatest extent possible the
   semantics expressed in the original RFC.  The goal of limiting
   changes only to syntax is to preserve the semantic meaning encoded in
   the published document.

   This policy does not require that updates to RFCXML avoid all risk of
   introducing semantic changes to existing RFCs.  Instead, it only
   requires that such updates consider the potential for semantic
   changes, take steps to understand the risk of a semantic change
   (either deliberate or inadvertent), and to limit those risks.

3.  Publication Versions

   The RPC is permitted but not required to re-issue publication
   versions of an RFC, as described in Section 1.2.  In deciding whether
   to update the publication versions of an RFC, the RPC will take into
   account both the risk of semantic changes and consistency of the
   series.

   XML format errors and better design choices have been discovered by
   the community since the first RFCs were published using the RFCXML
   format.  When the XML in a definitive version changes, the
   publication versions may change, even if this might not result in
   observable differences.  Similarly, as production tools change,
   publication versions may be regenerated to ensure a consistent
   presentation.

Hoffman & Flanagan       Expires 13 October 2024                [Page 6]
Internet-Draft              Format Framework                  April 2024

4.  Archived Documents

   The RPC will keep an archived set of all definitive versions of RFCs
   as well as archived sets of the publication versions for an RFC that
   were previously published.  These archived sets must be available
   using the same access methods as for the XML and the published
   publication versions.  Every archived set shall record the date that
   a document was created or revised.

   When the RPC archives documents, it does so in a manner that allows
   them to be found by people who want the historical (as compared to
   current) versions of those files.

   This document does not specify how archives are maintained or how
   archived documents might be located or identified.  The methods for
   storage and access will be determined by the RPC in consultation with
   the technical community.

5.  IANA Considerations

   This document has no IANA considerations.

6.  Security Considerations

   Allowing changes to the definitive versions and publication versions
   of RFCs introduces risks.  A significant risk is that unintended
   changes could occur in either the definitive version or publication
   versions of an RFC as a result of an editing error, or may be
   introduced into a publication version when it is regenerated from the
   definitive version.  This may result in the corruption of a standard,
   practice, or critical piece of information about a protocol, and harm
   to the reputation of the RFC series.

   The RPC is expected to identify, track, and actively mitigate risks
   introduced by this new policy.

7.  Acknowledgments

   Martin Thomson wrote a great deal of the significant text here as
   part of draft-thomson-rswg-syntax-change.

   This document has greatly benefited from the input of the RSWG.  In
   particular, Alexis Rossi, Brian Carpenter, Eliot Lear, Jay Daley,
   Jean Mahoney, John Levine, and Pete Resnick, gave significant input
   on the early drafts of this document.

8.  References

Hoffman & Flanagan       Expires 13 October 2024                [Page 7]
Internet-Draft              Format Framework                  April 2024

8.1.  Normative References

   [RFC7990]  Flanagan, H., "RFC Format Framework", RFC 7990,
              DOI 10.17487/RFC7990, December 2016,
              <https://www.rfc-editor.org/rfc/rfc7990>.

   [RFC7991]  Hoffman, P., "The "xml2rfc" Version 3 Vocabulary",
              RFC 7991, DOI 10.17487/RFC7991, December 2016,
              <https://www.rfc-editor.org/rfc/rfc7991>.

   [RFC7996]  Brownlee, N., "SVG Drawings for RFCs: SVG 1.2 RFC",
              RFC 7996, DOI 10.17487/RFC7996, December 2016,
              <https://www.rfc-editor.org/rfc/rfc7996>.

   [RFC7997]  Flanagan, H., Ed., "The Use of Non-ASCII Characters in
              RFCs", RFC 7997, DOI 10.17487/RFC7997, December 2016,
              <https://www.rfc-editor.org/rfc/rfc7997>.

8.2.  Informative References

   [RFC20]    Cerf, V., "ASCII format for network interchange", STD 80,
              RFC 20, DOI 10.17487/RFC0020, October 1969,
              <https://www.rfc-editor.org/rfc/rfc20>.

   [RFC6949]  Flanagan, H. and N. Brownlee, "RFC Series Format
              Requirements and Future Development", RFC 6949,
              DOI 10.17487/RFC6949, May 2013,
              <https://www.rfc-editor.org/rfc/rfc6949>.

   [RFC8650]  Voit, E., Rahman, R., Nilsen-Nygaard, E., Clemm, A., and
              A. Bierman, "Dynamic Subscription to YANG Events and
              Datastores over RESTCONF", RFC 8650, DOI 10.17487/RFC8650,
              November 2019, <https://www.rfc-editor.org/rfc/rfc8650>.

   [RFC9280]  Saint-Andre, P., Ed., "RFC Editor Model (Version 3)",
              RFC 9280, DOI 10.17487/RFC9280, June 2022,
              <https://www.rfc-editor.org/rfc/rfc9280>.

Authors' Addresses

   Paul Hoffman
   ICANN
   Email: paul.hoffman@icann.org

   Heather Flanagan
   Spherical Cow Consulting
   Email: hlf@sphericalcowconsulting.com

Hoffman & Flanagan       Expires 13 October 2024                [Page 8]