[Docs] [txt|pdf] [Tracker] [Email] [Nits]

Versions: 00

Network Working Group                                           A. Roach
Internet-Draft                                                   Mozilla
Intended status: Best Current Practice                      May 07, 2019
Expires: November 8, 2019


       Process for Handling Non-Major Revisions to Existing RFCs
                      draft-roach-bis-documents-00

Abstract

   This document discusses mechanisms the IETF has historically used for
   updating RFCs subsequent to their publication, and outlines an
   updated procedure for publishing newer versions (colloquially known
   as "bis versions") that is appropriate in certain circumstances.
   This procedure is expected to be easier for both authors and
   consumers of RFCs.

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 http://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 November 8, 2019.

Copyright Notice

   Copyright (c) 2019 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
   (http://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.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of




Roach                   Expires November 8, 2019                [Page 1]


Internet-Draft         Minor -bis Document Process              May 2019


   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   3
   3.  Processing for Revised Documents  . . . . . . . . . . . . . .   4
     3.1.  Basic Qualifications  . . . . . . . . . . . . . . . . . .   4
     3.2.  Document Evaluation Process . . . . . . . . . . . . . . .   5
     3.3.  Deprecated Technology . . . . . . . . . . . . . . . . . .   5
   4.  Implications for Other Documents  . . . . . . . . . . . . . .   6
   5.  To-Do . . . . . . . . . . . . . . . . . . . . . . . . . . . .   6
   6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   6
   7.  Security Considerations . . . . . . . . . . . . . . . . . . .   7
   8.  Acknowledgments . . . . . . . . . . . . . . . . . . . . . . .   7
   9.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   7
     9.1.  Normative References  . . . . . . . . . . . . . . . . . .   7
     9.2.  Informative References  . . . . . . . . . . . . . . . . .   7
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   8

1.  Introduction

   [RFC2026] defines the Internet Standards Process, largely focusing on
   the handling of the RFC publication process.  Part of this process as
   originally envisioned includes republication of documents under a
   number of circumstances, such as when a document is progressed
   towards Internet Standard status.  The circumstances that
   necessitated republication originally also included various fixes to
   the contents of the documents; for example, RFC 2026 specifies:

      [A]n important typographical error, or a technical error that does
      not represent a change in overall function of the specification,
      may need to be corrected immediately.  In such cases, the IESG or
      RFC Editor may be asked to republish the RFC (with a new number)
      with corrections...

   In the intervening years since the publication of RFC 2026, various
   additional mechanisms have emerged to deal with minor updates to
   existing, published RFCs.  The RFC Editor maintains a set of errata
   associated with published documents.  These errata are intended for
   use when the intention of the document can be deduced, but the
   expression of the intention is imperfect (e.g., it contains a
   typographical error or is ambiguous in its phrasing).  Notably,
   errata cannot be used to change the intended meaning of a document
   from that which was originally intended.





Roach                   Expires November 8, 2019                [Page 2]


Internet-Draft         Minor -bis Document Process              May 2019


   Additionally, it is increasingly common to publish new, relatively
   small RFCs whose sole purpose is to update the functioning of an
   existing RFC.  Such documents are frequently formatted in a way that
   specifies an original text block that is to be replaced with a new
   text block.  In some cases, such as [RFC8035], these documents
   contain a single straightforward update.  In others, such as
   [RFC8540], several updates are bundled together in a single document.
   It should be noted that not all such updates are defined in a form
   that specifies old-text/new-text blocks; for example, [RFC7647]
   describes updates to an existing document in simple prose, but it is
   semantically the same as documents that perform text replacement.

   An unfortunate consequence of this approach to updating RFCs is that
   consumers of such documents are left with no authoritative, correct
   version of a document.  Instead, they must read the base document,
   and then mentally apply the updates specified by each successor
   document that has updated it in this fashion.  As a secondary
   concern, the production of such documents is complicated by the need
   for authors, contributors, and reviewers to flip back-and-forth
   between the base document and the updating document; and if multiple
   RFCs update a base document in sequence, this problem is compounded
   even further.

   One major concern that drives these incremental document updates is
   that an attempt to republish an RFC as originally described in RFC
   2026 can result in such an effort being bogged down by issues that
   exist in text unrelated to the desired changes.  Such issues can
   arise from a change in the consensus of the IETF around best current
   practices, such as in the areas of security, privacy, or
   architectural design of an underlying protocol.  This complication
   arises from the fact that processing of an updated full version of an
   RFC is procedurally identical to processing of a green-field
   definition of a new protocol: review by the IETF at large, and review
   by the IESG, are performed on the entire document, leaving legacy
   text open to comments that will delay - and occasionally block -
   publication of such documents.

   In order to address this concern, this document proposes new
   guidelines intended to reduce the barriers to publication of updated
   documents, and to reduce the load on reviewers during IETF and IESG
   review.

2.  Terminology

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in BCP




Roach                   Expires November 8, 2019                [Page 3]


Internet-Draft         Minor -bis Document Process              May 2019


   14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

3.  Processing for Revised Documents

   At a high level, the process described in this document allows bis
   versions of documents to be processed along with a request to review
   teams, directorates, the IETF community, and the IESG that any
   reviews primarily take into consideration the changes to the
   document, rather than the document as a whole.  While these requests
   do not strictly preclude feedback and discussion of the unchanged
   portions of bis documents, reviewers are expected to take them under
   serious consideration.

   Note that the process described in this document exclusively
   considers IETF-stream documents.

3.1.  Basic Qualifications

   In order to be considered for the processing described in this
   document, a bis update needs to satisfy the following criteria:

   1.  The document must formally obsolete (not update) an existing RFC.

   2.  The changes from the document being obsoleted must not constitute
       the majority of the document.  This is a subjective evaluation,
       not a mathematical one.

   3.  Except as detailed in verified errata, the document does not
       contain spurious changes (such as reformatting) in sections other
       than those containing substantive updates.

   4.  The document SHOULD contain an appendix detailing the changes
       from the RFC it is replacing.  Any change for which the rationale
       is not abundantly obvious should be explained in this appendix.

   5.  The publication track of the new document MUST be the same as the
       document that is being replaced (for example, the process cannot
       be used when obsoleting an Experimental document with a Standards
       Track one)

   6.  The AD sponsoring the document must explicitly approve the use of
       the process described in this document.

   Although not a strict qualification, working groups and authors of
   documents using this process should carefully evaluate all verified
   errata on the original RFC and all RFCs that formally update the




Roach                   Expires November 8, 2019                [Page 4]


Internet-Draft         Minor -bis Document Process              May 2019


   original RFC to determine which, if any, the new document should
   incorporate.

3.2.  Document Evaluation Process

   When an author or working group wish to request publication of a bis
   document with targeted review of limited changes, the following
   considerations are applied.

   1.  The shepherd's write-up includes a statement indicating that the
       qualifications outlined in Section 3.1 are satisfied, and asking
       for the processing described in this document.

   2.  The "Last-Call notification" that is specified by RFC 2026
       section 6.1.2 will include a prominent notification stating:
       "This document is being published according to the process
       defined in RFC XXXX.  While reading the entire contents of the
       document will provide useful context to reviewers, the IESG is
       primarily soliciting input regarding the changed portions of the
       document at this time".

   3.  The "Last-Call notification" MUST also include a pointer to a
       mechanically-generated diff file that exhaustively indicates the
       changes between the bis document and the document it is
       obsoleting.

   4.  As part of the IESG's evaluation of the document, its sponsoring
       AD will communicate to the IESG that processing is requested
       according to the procedures in this document.  This communication
       will request that the IESG focus on the changes from the
       obsoleted RFC.  IESG members SHOULD NOT issue DISCUSS or ABSTAIN
       ballot positions based on unchanged text except as described in
       Section 3.3.  In the rare case that such positions are balloted,
       they need to balance the scope of changes between existing RFC
       and bis document against the amount of work required to address
       potential comments.

3.3.  Deprecated Technology

   One major change that results from the application of the procedure
   described in this document is that the IETF may re-publish older text
   that describes approaches to protocol design that are no longer
   considered safe, advisable, or appropriate.  To avoid this re-
   publication implying an endorsement by the IETF of such deprecated
   approaches, they MUST be clearly indicated in the "Introduction"
   section of the document using the following text or text
   substantially similar to it:




Roach                   Expires November 8, 2019                [Page 5]


Internet-Draft         Minor -bis Document Process              May 2019


     This document is a revision of a previously published RFC. Some
     portions of the text have not been updated and do not meet current
     best practices for documents published by the IETF.

   The introduction must then detail each specific technique in the
   document that would not generally be acceptable in newly-published
   specifications.

   Notably, this text might be added by the working group during
   development of the revision, as a result of IETF Last-Call or
   directorate reviews, or as part of the IESG evaluation process.  The
   need for such a notice is explicitly considered an acceptable
   rationale for an IESG member to hold a blocking position on a
   document ballot.

4.  Implications for Other Documents

   To avoid those usability issues described in Section 1, IETF-stream
   documents generally SHOULD NOT perform updates to existing RFCs by
   replacing text in such RFCs (either syntactically via "OLD TEXT"/"NEW
   TEXT" sections, or semantically by describing changes to protocol
   processing).  Instead, such updates should be performed by publishing
   new versions of existing RFCs.  Note that such new versions do not
   necessarily need to make use of the process described in this
   document.

   There may be exceptional circumstances that warrant simple text
   replacement rather than new document versions.  These cases should be
   rare and carefully considered; and documents that do so should
   contain text explaining why the publication of a new version of the
   updated document is not desirable.

5.  To-Do

   o  The text uses phrasing like "the process described in this
      document" in several places.  This is cumbersome.  Ideally, we
      would come up with a short term of art to describe this process.

6.  IANA Considerations

   This document makes no requests of IANA.  Authors of documents that
   use this process should carefully examine the "IANA Considerations"
   sections of the document they are obsoleting, and ensure that any
   IANA data pointing to the obsoleted document is updated to instead
   indicate the new document.






Roach                   Expires November 8, 2019                [Page 6]


Internet-Draft         Minor -bis Document Process              May 2019


7.  Security Considerations

   As stated in Section 3.3, this process may result in the re-
   publication of techniques, including security techniques, that are no
   longer considered safe.  During development of a bis document,
   authors and working groups are strongly encouraged to update such
   outmoded security approaches in favor of more modern ones.

   It should be noted that, while the process introduced by this
   document does not necessarily improve this situation, it is carefully
   designed to also not exacerbate the status quo.  Absent this process,
   the historical approach of issuing documents that update small
   portions of older RFCs would continue, and such outmoded security
   techniques would remain equally in effect.

8.  Acknowledgments

   Thanks to Ben Campbell and Joe Hildebrand for early conversations
   that helped inform the contents of this document, and to the 2019
   members of the IESG for helping to refine some of the more subtle
   points of handling deprecated approaches.

9.  References

9.1.  Normative References

   [RFC2026]  Bradner, S., "The Internet Standards Process -- Revision
              3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, October 1996,
              <https://www.rfc-editor.org/info/rfc2026>.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/
              RFC2119, March 1997, <https://www.rfc-editor.org/info/
              rfc2119>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/info/rfc8174>.

9.2.  Informative References

   [RFC7647]  Sparks, R. and A. Roach, "Clarifications for the Use of
              REFER with RFC 6665", RFC 7647, DOI 10.17487/RFC7647,
              September 2015, <https://www.rfc-editor.org/info/rfc7647>.







Roach                   Expires November 8, 2019                [Page 7]


Internet-Draft         Minor -bis Document Process              May 2019


   [RFC8035]  Holmberg, C., "Session Description Protocol (SDP) Offer/
              Answer Clarifications for RTP/RTCP Multiplexing", RFC
              8035, DOI 10.17487/RFC8035, November 2016,
              <https://www.rfc-editor.org/info/rfc8035>.

   [RFC8540]  Stewart, R., Tuexen, M., and M. Proshin, "Stream Control
              Transmission Protocol: Errata and Issues in RFC 4960", RFC
              8540, DOI 10.17487/RFC8540, February 2019,
              <https://www.rfc-editor.org/info/rfc8540>.

Author's Address

   Adam Roach
   Mozilla

   Email: adam@nostrum.com



































Roach                   Expires November 8, 2019                [Page 8]


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