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

Network Working Group                                         P. Hoffman
Internet-Draft                                                     ICANN
Updates: 7990 (if approved)                              17 October 2023
Intended status: Informational                                          
Expires: 19 April 2024

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

Abstract

   This document updates RFC 7990 by changing the word "canonical" to
   "definitive" and defining what it means to the series.  It also
   updates RFC 7990 by defining the relationship of the publication
   formats to the series and the expectation of archiving both the
   definitive and publication formats of RFCs.  A policy governing how
   the RFCXML format changes is described.

   An open question for the RSWG is whether this document should be an
   update patch to RFC 7990 (which is the current form of the document)
   or a complete rewrite done to obsolete RFC 7990.

   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).  Issues can be raised there, but probably should be
   on the mailing list instead.

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 19 April 2024.

Hoffman                   Expires 19 April 2024                 [Page 1]
Internet-Draft              Format Framework                October 2023

Copyright Notice

   Copyright (c) 2023 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
   2.  Updated Definition of "Canonical Format" and "Archive"  . . .   3
   3.  Rationale . . . . . . . . . . . . . . . . . . . . . . . . . .   4
   4.  Syntax Change Policy  . . . . . . . . . . . . . . . . . . . .   5
     4.1.  Reasons for Updating the XML Files  . . . . . . . . . . .   5
   5.  Archived Documents  . . . . . . . . . . . . . . . . . . . . .   6
   6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   6
   7.  Security Considerations . . . . . . . . . . . . . . . . . . .   6
   8.  Acknowledgments . . . . . . . . . . . . . . . . . . . . . . .   6
   9.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   6
     9.1.  Normative References  . . . . . . . . . . . . . . . . . .   6
     9.2.  Informative References  . . . . . . . . . . . . . . . . .   7
   Appendix A.  Advice on Regenerating Publication Formats . . . . .   7
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   8

1.  Introduction

   [RFC7990] defines 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 talks about "the XML file"
   as if there will only be one XML file for an RFC because this was the
   expectation at the time [RFC7990] was published.  It also talks about
   "publication formats" as the versions of HTML, text, and PDF versions
   derived from the canonical format.

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

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

Hoffman                   Expires 19 April 2024                 [Page 2]
Internet-Draft              Format Framework                October 2023

   *  It changes the phrase "canonical format" to "definitive version"
      and defines the use of the definitive version in the series.

   *  It changes the phrase "publication format" to "publication
      versions" and defines the use of the publication versions in the
      series.

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

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

   This document explicitly does not update the other documents
   referenced in [RFC7990].

2.  Updated Definition of "Canonical Format" and "Archive"

   Section 3 of [RFC7990] defines the canonical format as:

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

   This paragraph in [RFC7990] is replaced with:

      Definitive version: the authorized, recognized, accepted, and most
      recent version of the document published by the RFC Editor

   Section 5 of [RFC7990] says:

      The final XML file produced by the RFC Editor will be considered
      the canonical format for RFCs; it is the lowest common denominator
      that holds all the information intended for an RFC.

   This wording does not take into account later changes to the
   definitive version.  As noted in Section 10.2 of [RFC7990],
   "publication formats may be republished as needed".  XML format
   errors, and better design choices, have been discovered by the
   community since the first RFCs were published using the RFCXML
   format.

   As the RFC XML format of a document changes, publication formats can
   change, even if this might not result in observable differences.
   Similarly, as production tools change, publication formats can be
   regenerated to ensure a consistent presentation across the series.

Hoffman                   Expires 19 April 2024                 [Page 3]
Internet-Draft              Format Framework                October 2023

   Publication formats and the contexts in which they are displayed can
   optionally provide additional details of the specific RFCXML version
   that they were generated from, or provide a means to discover
   alternative renderings.

   In order to allow the RFC Editor to publish new definitive versions
   and associated publication versions of RFCs, Section 5 of [RFC7990]
   is replaced with:

      The definitive version produced by the RFC Editor is the version
      that holds all the information intended for an RFC.  The RFC
      Editor may change the definitive version of an RFC over time to
      incorporate changes in the RFCXML format.

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

      This document does not specify how archives are maintained or how
      archived RFC might be located or identified.

   [[[ The paragraphs immediately above specifies policy for updating
   publication formats.  There is not yet consensus in the RSWG about
   whether that should or should not be policy. ]]]

3.  Rationale

   The format for published RFCs is RFCXML [RFC7990].  Historically, the
   published version of an RFC has been immutable.  Section 7.6 of
   [RFC9280] says "Once published, RFC Series documents are not
   changed."

   The RFCXML format [RFC7991] is not able to address use cases that
   were not originally anticipated during its design.  It might also be
   possible to improve the format to better capture meaning.

   Though it might be possible to evolve the format and only use the new
   format for the publication of new RFCs, this would mean that there
   would be no single format across the series.  Tools that seek to
   process RFCXML would need to understand all iterations of the format.

Hoffman                   Expires 19 April 2024                 [Page 4]
Internet-Draft              Format Framework                October 2023

4.  Syntax Change Policy

   The RFC Series Working Group (RSWG), constituted by [RFC9280], acts
   as custodian for the RFCXML format.  If the RSWG reaches consensus,
   they can propose a revision to [RFC7991].

   The RSWG can publish RFCs in the Editorial stream that describe how
   the RFCXML format changes.  An updated XML format is used for the
   publication of new RFCs.  Some time after the publication of an
   update to [RFC7991] might be necessary to implement changes in tools
   and active documents.

   Existing RFCs can be updated to use the new format.  The RFC that
   describes format changes can also describe how the XML of existing
   RFCs could be updated.

   Updates to the RFCXML format 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 RFC XML document.

   This process does not require that updates to RFCXML avoid all risk
   of introducing semantic changes to existing RFCs.  Instead, it only
   requires that the RSWG carefully 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.

4.1.  Reasons for Updating the XML Files

   The XML file can be updated for the following limited reasons:

   *  The XML vocabulary, originally defined in [RFC7991], changes

   *  An error is discovered in the format XML for an RFC

   Existing RFCs can be updated to use the new format.  The RFC that
   describes format changes can also describe how the XML of existing
   RFCs will be updated.  The intent behind limiting changes to syntax
   and XML errors is that the goal is to preserve the semantic meaning
   encoded in the RFC XML document.

   [[[ The above sets a new policy.  Another option is to say that the
   policy will be set later. ]]]

   During the development of this document, many other reasons for
   updating the XML file were suggested.  Those reasons are not in scope
   for this document, and may be adopted later after the community has
   experience with the updating mechanisms described in this document.

Hoffman                   Expires 19 April 2024                 [Page 5]
Internet-Draft              Format Framework                October 2023

5.  Archived Documents

   When the RFC Editor 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 RFC XML might be located or identified.  The methods for
   storage and access will be determined by the RFC Editor in
   consultation with the technical community.

6.  IANA Considerations

   This document has no IANA considerations.

7.  Security Considerations

   This document has the same security considerations as [RFC7990].
   Those are:

      Changing the format for RFCs involves modifying a great number of
      components to publication.  Understanding those changes and the
      implications for the entire tool chain is critical so as to avoid
      unintended bugs that would allow unintended changes to text.
      Unintended changes to text could in turn corrupt a standard,
      practice, or critical piece of information about a protocol.

   The RSWG are responsible for managing the risk of semantic changes
   that would affect the interpretation of existing and future RFCs.
   Changes to content that has security implications would have
   security-relevant consequences.

8.  Acknowledgments

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

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

9.  References

9.1.  Normative References

Hoffman                   Expires 19 April 2024                 [Page 6]
Internet-Draft              Format Framework                October 2023

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

9.2.  Informative References

   [RFC8651]  Cheng, B., Wiggins, D., and L. Berger, Ed., "Dynamic Link
              Exchange Protocol (DLEP) Control-Plane-Based Pause
              Extension", RFC 8651, DOI 10.17487/RFC8651, October 2019,
              <https://www.rfc-editor.org/rfc/rfc8651>.

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

Appendix A.  Advice on Regenerating Publication Formats

   This document does not include specific guidance regarding the
   generation of publication formats from the RFCXML source for the
   definitive version of an RFC.  Decisions about how to maintain
   publication formats are not a matter governed by policy as specified
   in [RFC9280].  This appendix contains advice and considerations for
   the process of regeneration that came out of discussions of the
   policy changes in this document.

   Changes to the RFCXML for existing RFCs might result in changes to
   the documents rendered from that XML.  At the same time, the tools
   used to generate renderings are under active maintenance.  Making it
   possible for a fresh rendering to replace existing publication
   formats is a goal supported by the policy changes in this document.

   This creates a risk that a rerendered documents change in unexpected
   ways when they are regenerated.  This risk of unintentional change
   can be managed by implementing validation processes:

   *  Tools can be continuously checked by producing renderings for
      existing RFCs.  Any change in the rendered document can then be
      compared with previous outputs and validated.  This will ensure
      that changes in tooling are deliberate and understood.

   *  When a change to the XML format occurs, rendered documents can be
      regenerated and any change in the rendering can be validated.

Hoffman                   Expires 19 April 2024                 [Page 7]
Internet-Draft              Format Framework                October 2023

   Validation should be aided by automated tooling that is able to
   disregard inconsequential changes in renderings, like changes in
   timestamps and other annotations.  Validation of tooling can be
   continuous, for which automation is essential.

   The decision to make renderings available as the publication format
   for an RFC is a decision that can be made on a case-by-case basis.
   Making fresh renderings available more often could mean a greater
   risk that people seeking to read RFCs will obtain a copy that
   contains accidental errors.  However, errors in publication formats
   might persist if they are not replaced as tool quality and
   reliability improves.

   Old copies of replaced publication formats will be retained to
   provide the ability to isolate changes and understand the evolution
   of documents.

Author's Address

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

Hoffman                   Expires 19 April 2024                 [Page 8]