idnits 2.17.1 draft-kuehlewind-update-tag-04.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 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.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (12 July 2021) is 1020 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) ** Downref: Normative reference to an Informational RFC: RFC 7322 Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Kuehlewind 3 Internet-Draft Ericsson 4 Intended status: Best Current Practice S. Krishnan 5 Expires: 13 January 2022 Kaloom 6 12 July 2021 8 Definition of new tags for relations between RFCs 9 draft-kuehlewind-update-tag-04 11 Abstract 13 An RFC can include a tag called "Updates" which can be used to link a 14 new RFC to an existing RFC. On publication of such an RFC, the 15 existing RFC will include an additional metadata tag called "Updated 16 by" which provides a link to the new RFC. However, this tag pair is 17 not well-defined and therefore it is currently used for multiple 18 different purposes, which leads to confusion about the actual meaning 19 of this tag and inconsistency in its use. 21 This document recommends the discontinuation of the use of the 22 updates/updated by tag pair, and instead proposes three new tag pairs 23 that have well-defined meanings and use cases. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at https://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on 13 January 2022. 42 Copyright Notice 44 Copyright (c) 2021 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 49 license-info) in effect on the date of publication of this document. 50 Please review these documents carefully, as they describe your rights 51 and restrictions with respect to this document. Code Components 52 extracted from this document must include Simplified BSD License text 53 as described in Section 4.e of the Trust Legal Provisions and are 54 provided without warranty as described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 59 2. Requirements Language . . . . . . . . . . . . . . . . . . . . 3 60 3. New Definitions . . . . . . . . . . . . . . . . . . . . . . . 3 61 3.1. Cross-stream use and maturity levels . . . . . . . . . . 5 62 4. Additional Recommendations . . . . . . . . . . . . . . . . . 5 63 4.1. Discontinuation of the Use of Updates/Updated by . . . . 5 64 4.2. Formatting Style of Amendments . . . . . . . . . . . . . 6 65 4.3. Indication of Linkage in the Abstract and Introduction . 6 66 5. Future work . . . . . . . . . . . . . . . . . . . . . . . . . 6 67 6. Alternative Approaches . . . . . . . . . . . . . . . . . . . 7 68 7. Security Considerations . . . . . . . . . . . . . . . . . . . 7 69 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 8 70 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 71 9.1. Normative References . . . . . . . . . . . . . . . . . . 8 72 9.2. Informative References . . . . . . . . . . . . . . . . . 8 73 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9 75 1. Introduction 77 An RFC can include a tag called "Updates" which can be used to link a 78 new RFC to an existing RFC. On publication of such an RFC, the 79 existing RFC will include an additional metadata tag called "Updated 80 by" which provides a link to the new RFC. However, this tag pair is 81 not well-defined and therefore it is currently used for multiple 82 different purposes, which leads to confusion about the actual meaning 83 of this tag and inconsistency in its use. 85 The "Updates/Updates by" tag pair is currently used consistently as 86 different working groups or areas tend to apply different meanings to 87 it. Opinions also differ greatly about the obligations on 88 implementors for the updated RFC. While updating an RFC never makes 89 the updated RFC invalid, updates can contain bug fixes or critical 90 changes. Some groups apply the update tag only to these kind of 91 changes with the expectation that new implementations are also 92 obliged to implement the new updating RFC. Some other groups use the 93 update tag to define optional extensions or new uses of extension 94 points in the current protocol. This disconnect leads to a situation 95 where it is desirable to add a "mandatory-to-implement" indication to 96 an existing RFC. 98 Groups or individuals that apply such restrictive conditions to the 99 Updates tag, consequently usually do not use the update tag for any 100 extensions or addition to a protocol. However, as there is no other 101 way in the current metadata scheme to link a new RFC to an existing 102 RFC, not using the Updates tag makes it harder to find these new 103 RFCs. While implementors might well benefit from some extensions or 104 additions, they might not be aware of them and either not use them 105 or, in the worst case, implement an alternate mechanism instead. 107 Currently the Updates/Updated by tag pair mainly provides a way to 108 link two documents. The cases mentioned above clearly benefit from 109 such a linkage which the expectation that readers of updated RFC as 110 least look or also read the updating RFC. Additionally, there are 111 more cases where such a linkage could be useful to improve awareness 112 of some newer related technology without providing any indication on 113 the importance of the linked document. As the conditions for the use 114 of the Updates tag are not clear, often it is not used in such cases. 116 This document recommends the discontinuation of the use of the 117 Updates/Updated by tag pair, and instead proposes three new tag pairs 118 that have well-defined meanings and use cases. 120 2. Requirements Language 122 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 123 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 124 "OPTIONAL" in this document are to be interpreted as described in BCP 125 14 [RFC2119] [RFC8174] when, and only when, they appear in all 126 capitals, as shown here. 128 3. New Definitions 130 Based on the problems identified above this document defines three 131 new tag pairs with the following meanings: 133 Amends/Amended by: This tag pair is used with an amending RFC that 134 changes the amended RFC. This could include bug fixes, behavior 135 changes etc. This is intended to specify mandatory changes to the 136 protocol. The goal of this tag pair is to signal to anyone looking 137 to implement the amended RFC that they MUST also implement the 138 amending RFC. 140 Extends/Extended by: This tag pair is used with an extending RFC that 141 defines an optional addition to the extended RFC. This can be used 142 by documents that use existing extension points or clarifications 143 that do not change existing protocol behavior. This signals to 144 implementers and protocol designers that there are changes to the 145 extended RFC that they need to consider but not necessarily 146 implement. 148 See Also/See Also: This is intended as a catch-all tag where two 149 documents are related loosely but do not fit either of the above 150 categories. The main intention of this tag is to provide a forward 151 reference from the existing RFC to the RFCs that may be of interest 152 to read. However, it is not recommenced to use this tag extensively. 154 These three tags MUST only be used for the defined meanings, mostly 155 with respect to the implication on implementation requirements. This 156 document does not mandate the use of these tags if one of the 157 described use cases apply. Tags are optional metadata that are 158 useful to understand the context of RFCs and navigate the RFC series. 159 All three tags can only be used to reference other RFCs (and not as 160 reference to external sources). 162 If a new RFC amends an old RFC while also defining an extension, 163 usually it is sufficient to use the "Amends" tag. However, both tags 164 could be used as well. In any case, it is more important to explain 165 clearly in the abstract what is amended/extended by the new RFC (see 166 section Section 4.3). 168 As today with "updates", none of the new tags makes the extended/ 169 amended RFC invalid. An implementation that conforms to the amended 170 RFC still conforms to that RFC, even when an amendment is published. 171 However, an implementation can, and hopefully should, of course be 172 updated to also conform to the new RFC with the amendment. If only 173 conformance to the new RFC is desired, obsoleting the respective RFC 174 with a new full (bis) specification may be more appropriate and 175 should be consider instead. 177 3.1. Cross-stream use and maturity levels 179 This document does not impose any restrictions on the status or 180 maturity level of the RFC that uses these new tags in relation the 181 RFC that gets amended/extended. Further, no restrictions are made on 182 the use of these tags across RFC streams. 184 However, it is expected that some cases are less likely, e.g. an 185 IETF-stream RFC gets amended by an RFC from another stream. For 186 amendments that effectively change the originally RFC is is expected 187 that the same consensus process is applied. This document does not 188 specify any detailed process requirements on how this is achieved. 190 Examples exist where non IETF-stream documents update IETF-stream 191 documents. However, these updates usually utilise an existing 192 extension point and therefore the use of "Extends" would be expected 193 in future, e.g. RFC 3579 (RADIUS Support For EAP) which is a 194 document in the Independent Submission Stream updates RFC 2869 195 (RADIUS Extensions), an IETF stream document. In fact, this new, 196 more clear definition of tags could even lead to an increase in cross 197 stream usage of the "Extends" tag (if adopted by other streams, which 198 is still open for discussion and may be reflected in future versions 199 of this document). 201 4. Additional Recommendations 203 4.1. Discontinuation of the Use of Updates/Updated by 205 [NOTE: This is open for discussion and we would like opinions on 206 whether the use of Updates needs to be discontinued for all future 207 documents or not. This requires further discussion with the RFC 208 Editor and the other stream managers to see if we can have a unified 209 policy for all streams] 211 This document makes the updates tag obsolete for future use: it MUST 212 NOT be used in new IETF stream documents. The new tags are to be 213 used instead, beginning with the publication of this document as an 214 RFC. 216 However, the Updates/Updated by tag pair will remain in existing 217 documents and there is no plans to change these metadata in order to 218 apply the new tags instead. While it would be possible to change the 219 "Updated by" tag in the metadata without republishing the updating 220 RFC, the mapping to either "Amended by", "Extended by", or "See also" 221 is not always straight forward and as such would require building 222 consensus for each RFC separately. Further, simply replacing the tag 223 would in any way not be sufficient, as also RFCs that currently do 224 not have an updates tag would probably qualify to have one of the new 225 tags defined in this document. 227 4.2. Formatting Style of Amendments 229 This document does not impose any requirements on the form of the 230 amendment made. Some RFCs use and OLD/NEW style to highlight actual 231 text changes others simply describe the changes in text. Both can 232 make sense in certain situation. However, this document does 233 recommend to use the OLD/NEW rather for smaller and a limited number 234 of changes, while if larger or many changes are needed, a new 235 document revision that obsoletes the old RFC should be considered. 237 4.3. Indication of Linkage in the Abstract and Introduction 239 The RFC style guide [RFC7322] recommends to indicate updates in the 240 abstract and introduction. Note that both is needed as the abstract 241 is meant to function in a stand-alone fashion. This document will 242 keep this practice for the new Amends/Amended by and Extends/Extended 243 by tag pairs as well. It is further recommended to provide 244 additional information about the extension in the abstract or 245 introduction for the Extends/Extended by tag pair in order to provide 246 the reader some assistance whether he or she also needs to read the 247 rest of extending RFC. 249 For the See Also/See Also tag pair, additional information of the 250 linked RFC may be added in the introduction but there is no 251 expectation to name these RFC in the abstract. 253 5. Future work 255 There will be a need to update the RFC Style Guide [RFC7322] (and 256 specifically Section 4.1.4.) in order to discuss the new tags if and 257 when this document is published. 259 Further, the "updates" attribute is part of the "xml2rfc" Version 3 260 Vocabulary [RFC7991]. Therefore an extension to [RFC7991] is need as 261 well. This may be done by a future version of this draft or in a 262 separate draft, e.g. with other extension or amendments to [RFC7991]. 264 6. Alternative Approaches 266 This document proposes three new meta data tag pairs to address the 267 problem that the use of the "Updates" tag is currently undefined 268 which causes confusion due to various different practices applied in 269 different group and after all a waste of time in recurring discussion 270 about using or not using the tag. 272 Alternatively, in order to solely solve the problem of avoiding 273 unnecessary discussion time, it would also be possible to document 274 that the "Updates" tag is undefined and as such there are no strict 275 rules about applying it or any implications of using it. This was 276 proposed by the IESG providing an IESG statement for community 277 discussion and lead to community feedback indicating that this 278 solution is not preferred. 280 However, rather than defining three new tags, one could also just 281 clearly define the meaning of the existing update tag. Still, this 282 could also be confusing as it would not apply to RFCs that are 283 already published. So re-naming and defining one tags, instead of 284 three, would be an alternative. This one tag could either cover all 285 three usages that are described in this draft or only one (probably 286 the one as defined by the proposed "Amends" tag, as this is usually 287 seen as the most important one). 289 This draft proposes three tags as those tags are considered to cover 290 most of the usages that we see today for the "Updates" tag, assuming 291 that these cases are benefiting from a forward reference of an 292 already published RFC to a new RFC. Especially separating changes to 293 an existing RFC, as often done by use of the OLD/NEW notation, from 294 extension/additions to an RFC is one of the main confusion and 295 discussion points and therefore this draft proposes different tags 296 for it. However, if it is observed that not all proposed tags are 297 actively used in future, or their usage is still not sufficiently 298 clear, it should be considered to deprecate the unused tags and 299 therefore restrict forward references to only some of the identified 300 usages. 302 7. Security Considerations 304 The changes in this document do not have directly impact the security 305 of any protocol or mechanism specified in the RFC series. However, 306 amendments or extensions can help to improve security or discuss 307 security-related issues. Therefore, the use of the proposed tags and 308 their clear definition can also support such RFCs in their intended 309 goals regarding security. 311 If a document is amended, it is expected that the same consensus 312 process is used as for the original document as an amended can be see 313 as an actual change of the original document. For extension points 314 usually the originally specification also defines requirement for an 315 extension mechanism to be used, e.g. in form of policy for IANA 316 registries. Of course, the requirement must be considered when 317 extending a protocol. 319 There is a risk that this experiment fails by either not seeing 320 adoption from the community or not addressing the discussed problems 321 sufficiently (ambiguity of use, implications for implementations). 322 However, it is not expected that the proposed tags will make these 323 problem worse. In the worst case, if the experiment is decided to be 324 reverted in future and the Updates tag should be used instead again, 325 this will likely not make the situation worse or more confusing than 326 it already is either. Maybe this effort is than seen as a waste of 327 time but the same recurring discussions about using or not using the 328 Updates tag (especially during IESG review but also before that in 329 the working group discussion) are a waste of time as well. 331 8. Acknowledgments 333 The authors would like to thank Alexey Melnikov, Alvaro Retana, Barry 334 Leiba, Eric Vyncke, Heather Flanagan, Martin Vigoureux, Brian 335 Carpenter and Sandy Ginoza for their reviews and comments that 336 improved this document. 338 9. References 340 9.1. Normative References 342 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 343 Requirement Levels", BCP 14, RFC 2119, 344 DOI 10.17487/RFC2119, March 1997, 345 . 347 [RFC7322] Flanagan, H. and S. Ginoza, "RFC Style Guide", RFC 7322, 348 DOI 10.17487/RFC7322, September 2014, 349 . 351 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 352 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 353 May 2017, . 355 9.2. Informative References 357 [RFC7991] Hoffman, P., "The "xml2rfc" Version 3 Vocabulary", 358 RFC 7991, DOI 10.17487/RFC7991, December 2016, 359 . 361 Authors' Addresses 363 Mirja Kuehlewind 364 Ericsson 366 Email: mirja.kuehlewind@ericsson.com 368 Suresh Krishnan 369 Kaloom 371 Email: Suresh@kaloom.com