idnits 2.17.1 draft-kuehlewind-update-tag-01.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 document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 119: '...ed RFC that they MUST also implement t...' RFC 2119 keyword, line 136: '...These three tags MUST only be used for...' RFC 2119 keyword, line 168: '...s tag obsolete for future use: it MUST...' Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 04, 2019) is 1696 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) -- Missing reference section? 'RFC2119' on line 109 looks like a reference -- Missing reference section? 'RFC8174' on line 109 looks like a reference -- Missing reference section? 'RFC7322' on line 211 looks like a reference Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 4 comments (--). 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: March 7, 2020 Kaloom 6 September 04, 2019 8 Definition of new tags for relations between RFCs 9 draft-kuehlewind-update-tag-01 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 March 7, 2020. 42 Copyright Notice 44 Copyright (c) 2019 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 49 (https://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 1. Introduction 59 An RFC can include a tag called "Updates" which can be used to link a 60 new RFC to an existing RFC. On publication of such an RFC, the 61 existing RFC will include an additional metadata tag called "Updated 62 by" which provides a link to the new RFC. However, this tag pair is 63 not well-defined and therefore it is currently used for multiple 64 different purposes, which leads to confusion about the actual meaning 65 of this tag and inconsistency in its use. 67 The "Updates/Updates by" tag pair is currently used by different 68 working groups and different areas, which tend to apply different 69 meanings to it. They also differ greatly about the obligations on 70 the implementors of the Updated RFC. While updating an RFC never 71 makes the updated RFC invalid, updates can contain bug fixes or 72 critical changes. Some groups apply the update tag only to these 73 kind of changes with the expectation that new implementors are also 74 obliged to implement this new RFC. Some other groups use the update 75 tag to define optional extensions or use of extension points in the 76 current protocol. This disconnect leads to a situation where it is 77 desirable to add a "mandatory-to-implement" indication to an existing 78 RFC. 80 Groups or individuals that apply such restrictive conditions to the 81 Updates tag, consequently usually don't use the update tag for any 82 extensions or addition to a protocol. However, as there is no other 83 way in the current metadata scheme to link a new RFC to an existing 84 RFC, not using the Updates tag makes it harder to find these new 85 RFCs. While implementors might well benefit from some extensions or 86 additions, they might not be aware of them and either not use them 87 or, in the worst case, implement an alternate mechanism instead. 89 Currently the Updates/Updated by tag pair mainly provides a way to 90 link two documents. The cases mentioned above clearly benefit from 91 such a linkage which the expectation that readers of one RFC as least 92 look or also read the other RFC. Additionally, there are more cases 93 where such a linkage could be useful to improve awareness of some 94 newer related technology without providing any indication on the 95 importance of the linked document. As the conditions for the use of 96 the Updates tag are not clear, often it is not used in such cases. 98 This document recommends the discontinuation of the use of the 99 Updates/Updated by tag pair, and instead proposes three new tag pairs 100 that have well-defined meanings and use cases. 102 2. Requirements Language 104 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 105 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 106 "OPTIONAL" in this document are to be interpreted as described in BCP 107 14 [RFC2119] [RFC8174] when, and only when, they appear in all 108 capitals, as shown here. 110 3. New Definitions 112 Based on the problems identified above this document defines three 113 new tag pairs with the following meanings: 115 Amends/Amended by: This tag pair is used with an amending RFC that 116 changes the amended RFC. This could include bug fixes, behavior 117 changes etc. This is intended to specify mandatory changes to the 118 protocol. The goal of this tag pair is to signal to anyone looking 119 to implement the amended RFC that they MUST also implement the 120 amending RFC. 122 Extends/Extended by: This tag pair is used with an extending RFC that 123 defines an optional addition to the extended RFC. This can be used 124 by documents that use existing extension points or clarifications 125 that do not change existing protocol behavior. This signals to 126 implementers and protocol designers that there are changes to the 127 extended RFC that they need to consider but not necessarily 128 implement. 130 See Also/See Also: This is intended as a catch-all tag where two 131 documents are related loosely but do not fit either of the above 132 categories. The main intention of this tag is to provide a forward 133 reference from the existing RFC to the RFCs that may be of interest 134 to read. 136 These three tags MUST only be used for the defined meanings, mostly 137 with respect to the implication on implementation requirements. This 138 document does not mandate the use of these tags if one of the 139 described use cases apply. Tags are optional metadata that are 140 useful to understand the context of RFCs and navigate the RFC series. 142 This document does not impose any restrictions on the status or 143 maturity level of the RFC that uses these new tags in relation the 144 RFC that gets amended/extended. Further, no restrictions are made on 145 the use of these tags across RFC streams. However, it is expected 146 that some cases are less likely, e.g. an IETF-stream RFC gets amended 147 by an RFC from another stream. Examples exist where non IETF-stream 148 documents update IETF-stream documents. However, these updates 149 usually utilize an existing extension point and therefore the use of 150 "Extends" would be expected in future, e.g. RFC 3579 (RADIUS Support 151 For EAP) which is a document in the Independent Submission Stream 152 updates RFC 2869 (RADIUS Extensions), an IETF stream document. In 153 fact, this new, more clear definition of tags could even lead to an 154 increase in cross stream usage of the "Extends" tag (if adopted by 155 other streams, which is still open for discussion and may be 156 reflected in future versions of this document). 158 4. Additional Recommendations 160 4.1. Discontinuation of the Use of Updates/Updated by 162 [NOTE: This is open for discussion and we would like opinions on 163 whether the use of Updates needs to be discontinued for all future 164 documents or not. This requires further discussion with the RFC 165 Editor and the other stream managers to see if we can have a unified 166 policy for all streams] 168 This document makes the updates tag obsolete for future use: it MUST 169 NOT be used in new IETF stream documents. The new tags are to be 170 used instead, beginning with the publication of this document as an 171 RFC. 173 However, the Updates/Updated by tag pair will remain in existing 174 documents and there is no plans to change these metadata in order to 175 apply the new tags instead. Any such change would require 176 changing/updating/amending the RFC carrying th "Updates" tag and 177 building consensus for such a change might also not be straight 178 forward in all cases. Further, simply replacing the tag would any 179 way not be sufficient, as also RFCs that currently do not have an 180 updates tag would probably qualify to have one of the new tags 181 defined in this document. 183 4.2. Amendments 185 This document does not impose any requirements on the form of the 186 amendment made. Some RFCs use and OLD/NEW style to highlight actual 187 text changes others simply describe the changes in text. Both can 188 make sense in certain situation. However, this document does 189 recommend to use the OLD/NEW rather for smaller and a limited number 190 of changes, while if larger or many changes are needed, a new 191 document revision that obsoletes the old RFC should be considered. 193 4.3. Indication of Linkage in the Abstract and Introduction 195 The RFC style guide (add ref!) recommends to indicate updates in the 196 abstract and introduction. Note that both is needed as the abstract 197 is meant to function in a stand-alone fashion. This document will 198 keep this practice for the new Amends/Amended by and Extends/Extended 199 by tag pairs as well. It is further recommended to provide 200 additional information about the extension in the abstract or 201 introduction for the Extends/Extended by tag pair in order to provide 202 the reader some assistance whether he or she also needs to read the 203 rest of extending RFC. 205 For the See Also/See Also tag pair, additional information of the 206 linked RFC may be added in the introduction but there is no 207 expectation to name these RFC in the abstract. 209 5. Future work 211 There will be a need to update the RFC Style Guide [RFC7322] (and 212 specifically Section 4.1.4.) in order to discuss the new tags if and 213 when this document is published. 215 6. Acknowledgments 217 The authors would like to thank Alexey Melnikov, Alvaro Retana, Barry 218 Leiba, Eric Vyncke, Heather Flanagan, Martin Vigoureux, Brian 219 Carpenter and Sandy Ginoza for their reviews and comments that 220 improved this document. 222 Authors' Addresses 224 Mirja Kuehlewind 225 Ericsson 227 Email: mirja.kuehlewind@ericsson.com 229 Suresh Krishnan 230 Kaloom 232 Email: Suresh@kaloom.com