Network Working Group A. RoachInternet-Draft MozillaIntended status: Best Current Practice May 07, 2019Expires: November 8, 2019Process for Handling Non-Major Revisions to Existing RFCsdraft-roach-bis-documents-00Abstract 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 ofBCP 78 andBCP 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 athttp://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 toBCP 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 inSection 4.e ofRoach 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 Contents1. Introduction . . . . . . . . . . . . . . . . . . . . . . . .22. Terminology . . . . . . . . . . . . . . . . . . . . . . . . .33. Processing for Revised Documents . . . . . . . . . . . . . .43.1. Basic Qualifications . . . . . . . . . . . . . . . . . .43.2. Document Evaluation Process . . . . . . . . . . . . . . .53.3. Deprecated Technology . . . . . . . . . . . . . . . . . .54. Implications for Other Documents . . . . . . . . . . . . . .65. To-Do . . . . . . . . . . . . . . . . . . . . . . . . . . . .66. IANA Considerations . . . . . . . . . . . . . . . . . . . . .67. Security Considerations . . . . . . . . . . . . . . . . . . .78. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . .79. References . . . . . . . . . . . . . . . . . . . . . . . . .79.1. Normative References . . . . . . . . . . . . . . . . . .79.2. Informative References . . . . . . . . . . . . . . . . .7 Author's Address . . . . . . . . . . . . . . . . . . . . . . . .81. 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 ofRFC 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 inRFC2026 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 BCPRoach 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 theRoach 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 inSection 3.1 are satisfied, and asking for the processing described in this document. 2. The "Last-Call notification" that is specified byRFC 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 inSection 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 inSection 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 20197. Security Considerations As stated inSection 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. References9.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 inRFC2119 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 withRFC 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",RFC8035, 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 inRFC 4960",RFC8540, DOI 10.17487/RFC8540, February 2019, <https://www.rfc-editor.org/info/rfc8540>.Author's Address Adam Roach Mozilla Email: adam@nostrum.comRoach Expires November 8, 2019 [Page 8]
draft-roach-bis-documents-00
Expired Internet-Draft (individual)
| Document | Document type | Expired Internet-Draft (individual) Expired & archived This document is an Internet-Draft (I-D). Anyone may submit an I-D to the IETF. This I-D isnot endorsed by the IETF and hasno formal standing in theIETF standards process. | |
|---|---|---|---|
| Select version | |||
| Author | Adam Roach Email authors | ||
| RFC stream | (None) | ||
| Intended RFC status | (None) | ||
| Other formats |