idnits 2.17.1 draft-wilde-updating-rfcs-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 : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The abstract seems to contain references ([2], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 14, 2016) is 2781 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Downref: Normative reference to an Informational RFC: RFC 7322 (ref. '1') -- Obsolete informational reference (is this intentional?): RFC 2223 (ref. '2') (Obsoleted by RFC 7322) Summary: 4 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 E. Wilde 3 Internet-Draft CA Technologies 4 Intended status: Standards Track September 14, 2016 5 Expires: March 18, 2017 7 Updating RFCs 8 draft-wilde-updating-rfcs-00 10 Abstract 12 As part of document metadata, RFCs can reference existing RFC that 13 they update or obsolete. While obsoleting is well-understood 14 (replace the obsoleted RFC in its entirety), updating has more 15 nuances because the updated RFC remains valid. This document 16 contains some clarifications about how to handle updating in a way 17 that makes it easier for readers to understand how the original and 18 the updating RFC relate. 20 Note to Readers 22 This draft should be discussed on the wgchairs mailing list [1]. 24 Online access to all versions and files is available on github [2]. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at http://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on March 18, 2017. 43 Copyright Notice 45 Copyright (c) 2016 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 61 2. Reasons for updating RFC 7233 . . . . . . . . . . . . . . . . 2 62 3. Documenting the Update Reasons . . . . . . . . . . . . . . . 3 63 4. References . . . . . . . . . . . . . . . . . . . . . . . . . 4 64 4.1. Normative References . . . . . . . . . . . . . . . . . . 4 65 4.2. Non-Normative References . . . . . . . . . . . . . . . . 4 66 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 4 67 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 4 69 1. Introduction 71 The "RFC Style Guide" [1] defines two possible ways in which an RFC 72 can relate to existing RFCs: It can obsolete existing RFCs, and/or it 73 can update existing RFCs. When obsoleting an RFC, the obsoleted RFC 74 is effectively replaced in its entirety by the obsoleting RFC (or 75 parts of it). For updates, the relationship is a little less clear. 77 The obsoleted "Instructions to RFC Authors" [2] in Section 12 78 describe what "Updates" and "Obsoletes" mean. These descriptions do 79 not appear in RFC 7322, and even if they did, they might still not 80 always be sufficient to understand the exact nature of the update. 82 This memo therefore recommends that RFC authors should include 83 explicit information about any updates that their RFC makes, and 84 include this in a place where it is easy to locate. This way, 85 readers of the updated RFC as well as those of the updating RFC can 86 easily understand how the two documents relate. 88 2. Reasons for updating RFC 7233 90 This document clarifies the way in which RFCs should describe their 91 relationship to updated RFCs. It proposes to include individual 92 "Reasons for updating RFC ..." sections for all updated RFCs as 93 section(s) early on in the document. These sections are supposed to 94 supplement the more formal "Updates" metadata and are not intended to 95 replace it. 97 3. Documenting the Update Reasons 99 RFC authors that use "Updates" in their document should include 100 individual "Reasons for updating ..." sections for each updated RFC. 101 These sections should be placed relatively early in the document. In 102 each of these sections, there should be a short description of the 103 nature of the update. 105 Authors should note that these sections are in no way intended to 106 replace the more formal "Updates" metadata in the RFC itself. 107 Instead, for each of the RFCs listed in the "Updates" metadata, one 108 such section should be added. 110 When writing these sections, it helps to specifically think about the 111 two possible perspectives: 113 When reading the updating RFC, there is a clear dependency on the 114 updated RFC. The most important question for somebody reading and 115 implementing the updating RFC is how this will affect 116 interoperability with implementations only implementing the 117 updated RFC. Documenting the expected behavior will make it 118 easier for implementers to understand the how different 119 implementations can be expected to interact. 121 When reading the updated RFC, it is important to keep in mind that 122 it is still valid as a standalone document. The most important 123 question for somebody who has implemented the updated RFC is how 124 the new updating RFC may affect interoperability. Documenting why 125 the updating RFC chose to explicitly update (instead of just being 126 an extension/add-on) will make it easier to understand the nature 127 of the update. 129 Generally speaking, using "Updates" often has one of two possible 130 motivations: One is a bug fix or a clarification that negatively 131 affected the original specification, in at least some of the 132 scenarios and implementations. In such a case, the update should be 133 of interest to everybody implementing the updated RFC, and the 134 section clearly state why and how that is the case. 136 The second motivation is that the updating RFC is a backwards 137 compatible extension, which means that strictly speaking, it does not 138 even need to mention the updated RFC. However, there may be reasons 139 to establish the relationship between the RFCs so the implementers 140 are aware of it and that new implementations of the updated RFC are 141 more likely to also implement the extension in the updating RFC. In 142 such a case, the section should be clear about the fact that the 143 update is optional, and may make a case for new implementations to 144 support the extension as well. 146 In case of non-protocol documents (such as this one), the general 147 question is the same: Does the updated practice specified in the 148 updating document warrant mentioning in the updated RFC? Once again, 149 if the author of the updating RFC thinks that this would be 150 appropriate, the explanation of the practice update should be given 151 in the "Reasons for updating ..." Section Section 3, so that it is 152 easy to understand why and how the practice was updated. 154 4. References 156 4.1. Normative References 158 [1] Flanagan, H. and S. Ginoza, "RFC Style Guide", RFC 7322, 159 DOI 10.17487/RFC7322, September 2014, 160 . 162 4.2. Non-Normative References 164 [2] Postel, J. and J. Reynolds, "Instructions to RFC Authors", 165 RFC 2223, DOI 10.17487/RFC2223, October 1997, 166 . 168 Appendix A. Acknowledgements 170 Thanks for comments and suggestions provided by Benoit Claise and 171 Tony Hansen. 173 Author's Address 175 Erik Wilde 176 CA Technologies 178 Email: dret@ca.com 179 URI: http://dret.net/netdret/