idnits 2.17.1 draft-roach-bis-documents-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (May 07, 2019) is 1815 days in the past. Is this intentional? Checking references for intended status: Best Current Practice ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Obsolete informational reference (is this intentional?): RFC 8540 (Obsoleted by RFC 9260) Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Roach 3 Internet-Draft Mozilla 4 Intended status: Best Current Practice May 07, 2019 5 Expires: November 8, 2019 7 Process for Handling Non-Major Revisions to Existing RFCs 8 draft-roach-bis-documents-00 10 Abstract 12 This document discusses mechanisms the IETF has historically used for 13 updating RFCs subsequent to their publication, and outlines an 14 updated procedure for publishing newer versions (colloquially known 15 as "bis versions") that is appropriate in certain circumstances. 16 This procedure is expected to be easier for both authors and 17 consumers of RFCs. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on November 8, 2019. 36 Copyright Notice 38 Copyright (c) 2019 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 54 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 3. Processing for Revised Documents . . . . . . . . . . . . . . 4 56 3.1. Basic Qualifications . . . . . . . . . . . . . . . . . . 4 57 3.2. Document Evaluation Process . . . . . . . . . . . . . . . 5 58 3.3. Deprecated Technology . . . . . . . . . . . . . . . . . . 5 59 4. Implications for Other Documents . . . . . . . . . . . . . . 6 60 5. To-Do . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 61 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 62 7. Security Considerations . . . . . . . . . . . . . . . . . . . 7 63 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 7 64 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 65 9.1. Normative References . . . . . . . . . . . . . . . . . . 7 66 9.2. Informative References . . . . . . . . . . . . . . . . . 7 67 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 8 69 1. Introduction 71 [RFC2026] defines the Internet Standards Process, largely focusing on 72 the handling of the RFC publication process. Part of this process as 73 originally envisioned includes republication of documents under a 74 number of circumstances, such as when a document is progressed 75 towards Internet Standard status. The circumstances that 76 necessitated republication originally also included various fixes to 77 the contents of the documents; for example, RFC 2026 specifies: 79 [A]n important typographical error, or a technical error that does 80 not represent a change in overall function of the specification, 81 may need to be corrected immediately. In such cases, the IESG or 82 RFC Editor may be asked to republish the RFC (with a new number) 83 with corrections... 85 In the intervening years since the publication of RFC 2026, various 86 additional mechanisms have emerged to deal with minor updates to 87 existing, published RFCs. The RFC Editor maintains a set of errata 88 associated with published documents. These errata are intended for 89 use when the intention of the document can be deduced, but the 90 expression of the intention is imperfect (e.g., it contains a 91 typographical error or is ambiguous in its phrasing). Notably, 92 errata cannot be used to change the intended meaning of a document 93 from that which was originally intended. 95 Additionally, it is increasingly common to publish new, relatively 96 small RFCs whose sole purpose is to update the functioning of an 97 existing RFC. Such documents are frequently formatted in a way that 98 specifies an original text block that is to be replaced with a new 99 text block. In some cases, such as [RFC8035], these documents 100 contain a single straightforward update. In others, such as 101 [RFC8540], several updates are bundled together in a single document. 102 It should be noted that not all such updates are defined in a form 103 that specifies old-text/new-text blocks; for example, [RFC7647] 104 describes updates to an existing document in simple prose, but it is 105 semantically the same as documents that perform text replacement. 107 An unfortunate consequence of this approach to updating RFCs is that 108 consumers of such documents are left with no authoritative, correct 109 version of a document. Instead, they must read the base document, 110 and then mentally apply the updates specified by each successor 111 document that has updated it in this fashion. As a secondary 112 concern, the production of such documents is complicated by the need 113 for authors, contributors, and reviewers to flip back-and-forth 114 between the base document and the updating document; and if multiple 115 RFCs update a base document in sequence, this problem is compounded 116 even further. 118 One major concern that drives these incremental document updates is 119 that an attempt to republish an RFC as originally described in RFC 120 2026 can result in such an effort being bogged down by issues that 121 exist in text unrelated to the desired changes. Such issues can 122 arise from a change in the consensus of the IETF around best current 123 practices, such as in the areas of security, privacy, or 124 architectural design of an underlying protocol. This complication 125 arises from the fact that processing of an updated full version of an 126 RFC is procedurally identical to processing of a green-field 127 definition of a new protocol: review by the IETF at large, and review 128 by the IESG, are performed on the entire document, leaving legacy 129 text open to comments that will delay - and occasionally block - 130 publication of such documents. 132 In order to address this concern, this document proposes new 133 guidelines intended to reduce the barriers to publication of updated 134 documents, and to reduce the load on reviewers during IETF and IESG 135 review. 137 2. Terminology 139 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 140 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 141 "OPTIONAL" in this document are to be interpreted as described in BCP 142 14 [RFC2119] [RFC8174] when, and only when, they appear in all 143 capitals, as shown here. 145 3. Processing for Revised Documents 147 At a high level, the process described in this document allows bis 148 versions of documents to be processed along with a request to review 149 teams, directorates, the IETF community, and the IESG that any 150 reviews primarily take into consideration the changes to the 151 document, rather than the document as a whole. While these requests 152 do not strictly preclude feedback and discussion of the unchanged 153 portions of bis documents, reviewers are expected to take them under 154 serious consideration. 156 Note that the process described in this document exclusively 157 considers IETF-stream documents. 159 3.1. Basic Qualifications 161 In order to be considered for the processing described in this 162 document, a bis update needs to satisfy the following criteria: 164 1. The document must formally obsolete (not update) an existing RFC. 166 2. The changes from the document being obsoleted must not constitute 167 the majority of the document. This is a subjective evaluation, 168 not a mathematical one. 170 3. Except as detailed in verified errata, the document does not 171 contain spurious changes (such as reformatting) in sections other 172 than those containing substantive updates. 174 4. The document SHOULD contain an appendix detailing the changes 175 from the RFC it is replacing. Any change for which the rationale 176 is not abundantly obvious should be explained in this appendix. 178 5. The publication track of the new document MUST be the same as the 179 document that is being replaced (for example, the process cannot 180 be used when obsoleting an Experimental document with a Standards 181 Track one) 183 6. The AD sponsoring the document must explicitly approve the use of 184 the process described in this document. 186 Although not a strict qualification, working groups and authors of 187 documents using this process should carefully evaluate all verified 188 errata on the original RFC and all RFCs that formally update the 189 original RFC to determine which, if any, the new document should 190 incorporate. 192 3.2. Document Evaluation Process 194 When an author or working group wish to request publication of a bis 195 document with targeted review of limited changes, the following 196 considerations are applied. 198 1. The shepherd's write-up includes a statement indicating that the 199 qualifications outlined in Section 3.1 are satisfied, and asking 200 for the processing described in this document. 202 2. The "Last-Call notification" that is specified by RFC 2026 203 section 6.1.2 will include a prominent notification stating: 204 "This document is being published according to the process 205 defined in RFC XXXX. While reading the entire contents of the 206 document will provide useful context to reviewers, the IESG is 207 primarily soliciting input regarding the changed portions of the 208 document at this time". 210 3. The "Last-Call notification" MUST also include a pointer to a 211 mechanically-generated diff file that exhaustively indicates the 212 changes between the bis document and the document it is 213 obsoleting. 215 4. As part of the IESG's evaluation of the document, its sponsoring 216 AD will communicate to the IESG that processing is requested 217 according to the procedures in this document. This communication 218 will request that the IESG focus on the changes from the 219 obsoleted RFC. IESG members SHOULD NOT issue DISCUSS or ABSTAIN 220 ballot positions based on unchanged text except as described in 221 Section 3.3. In the rare case that such positions are balloted, 222 they need to balance the scope of changes between existing RFC 223 and bis document against the amount of work required to address 224 potential comments. 226 3.3. Deprecated Technology 228 One major change that results from the application of the procedure 229 described in this document is that the IETF may re-publish older text 230 that describes approaches to protocol design that are no longer 231 considered safe, advisable, or appropriate. To avoid this re- 232 publication implying an endorsement by the IETF of such deprecated 233 approaches, they MUST be clearly indicated in the "Introduction" 234 section of the document using the following text or text 235 substantially similar to it: 237 This document is a revision of a previously published RFC. Some 238 portions of the text have not been updated and do not meet current 239 best practices for documents published by the IETF. 241 The introduction must then detail each specific technique in the 242 document that would not generally be acceptable in newly-published 243 specifications. 245 Notably, this text might be added by the working group during 246 development of the revision, as a result of IETF Last-Call or 247 directorate reviews, or as part of the IESG evaluation process. The 248 need for such a notice is explicitly considered an acceptable 249 rationale for an IESG member to hold a blocking position on a 250 document ballot. 252 4. Implications for Other Documents 254 To avoid those usability issues described in Section 1, IETF-stream 255 documents generally SHOULD NOT perform updates to existing RFCs by 256 replacing text in such RFCs (either syntactically via "OLD TEXT"/"NEW 257 TEXT" sections, or semantically by describing changes to protocol 258 processing). Instead, such updates should be performed by publishing 259 new versions of existing RFCs. Note that such new versions do not 260 necessarily need to make use of the process described in this 261 document. 263 There may be exceptional circumstances that warrant simple text 264 replacement rather than new document versions. These cases should be 265 rare and carefully considered; and documents that do so should 266 contain text explaining why the publication of a new version of the 267 updated document is not desirable. 269 5. To-Do 271 o The text uses phrasing like "the process described in this 272 document" in several places. This is cumbersome. Ideally, we 273 would come up with a short term of art to describe this process. 275 6. IANA Considerations 277 This document makes no requests of IANA. Authors of documents that 278 use this process should carefully examine the "IANA Considerations" 279 sections of the document they are obsoleting, and ensure that any 280 IANA data pointing to the obsoleted document is updated to instead 281 indicate the new document. 283 7. Security Considerations 285 As stated in Section 3.3, this process may result in the re- 286 publication of techniques, including security techniques, that are no 287 longer considered safe. During development of a bis document, 288 authors and working groups are strongly encouraged to update such 289 outmoded security approaches in favor of more modern ones. 291 It should be noted that, while the process introduced by this 292 document does not necessarily improve this situation, it is carefully 293 designed to also not exacerbate the status quo. Absent this process, 294 the historical approach of issuing documents that update small 295 portions of older RFCs would continue, and such outmoded security 296 techniques would remain equally in effect. 298 8. Acknowledgments 300 Thanks to Ben Campbell and Joe Hildebrand for early conversations 301 that helped inform the contents of this document, and to the 2019 302 members of the IESG for helping to refine some of the more subtle 303 points of handling deprecated approaches. 305 9. References 307 9.1. Normative References 309 [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 310 3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, October 1996, 311 . 313 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 314 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 315 RFC2119, March 1997, . 318 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 319 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 320 May 2017, . 322 9.2. Informative References 324 [RFC7647] Sparks, R. and A. Roach, "Clarifications for the Use of 325 REFER with RFC 6665", RFC 7647, DOI 10.17487/RFC7647, 326 September 2015, . 328 [RFC8035] Holmberg, C., "Session Description Protocol (SDP) Offer/ 329 Answer Clarifications for RTP/RTCP Multiplexing", RFC 330 8035, DOI 10.17487/RFC8035, November 2016, 331 . 333 [RFC8540] Stewart, R., Tuexen, M., and M. Proshin, "Stream Control 334 Transmission Protocol: Errata and Issues in RFC 4960", RFC 335 8540, DOI 10.17487/RFC8540, February 2019, 336 . 338 Author's Address 340 Adam Roach 341 Mozilla 343 Email: adam@nostrum.com