| Network Working Group | M. Kuehlewind |
| Internet-Draft | Ericsson |
| Intended status: Best Current Practice | S. Krishnan |
| Expires: January 28, 2020 | Kaloom |
| July 27, 2019 |
Definition of new tags for relations between RFCs
draft-kuehlewind-update-tag-00
The metadata of an RFC can include a tag called “Updates” which can be used to link a new RFC to an existing RFC. On publication of such an RFC, the existing RFC will include an additional metadata tag called “Updated by” which provides a link to the new RFC. However, this tag pair is not well-defined and therefore it is currently used for multiple different purposes, which leads to confusion about the actual meaning of this tag and inconsistency in its use.
This document recommends the discontinuation of the use of the updates/updated by tag pair, and instead proposes three new tag pairs that have well-defined meanings and use cases.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 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 at https://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 January 28, 2020.
Copyright (c) 2019 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://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 in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
The metadata of an RFC can include a tag called “Updates” which can be used to link a new RFC to an existing RFC. On publication of such an RFC, the existing RFC will include an additional metadata tag called “Updated by” which provides a link to the new RFC. However, this tag pair is not well-defined and therefore it is currently used for multiple different purposes, which leads to confusion about the actual meaning of this tag and inconsistency in its use.
The “Updates/Updates by” tag pair is currently used by different working groups and different areas, which tend to apply different meanings to it. They also differ greatly about the obligations on the implementors of the Updated RFC. While updating an RFC never makes the updated RFC invalid, updates can contain bug fixes or critical changes. Some groups apply the update tag only to these kind of changes with the expectation that new implementors are also obliged to implement this new RFC. Some other groups use the update tag to define optional extensions or use of extension points in the current protocol. This disconnect leads to a situation where it is desirable to add a “mandatory-to-implement” indication to an existing RFC.
Groups or individuals that apply such restrictive conditions to the Updates tag, consequently usually don’t use the update tag for any extensions or addition to a protocol. However, as there is no other way in the current metadata scheme to link a new RFC to an existing RFC, not using the Updates tag makes it harder to find these new RFCs. While implementors might well benefit from some extensions or additions, they might not be aware of them and either not use them or, in the worst case, implement an alternate mechanism instead.
Currently the Updates/Updated by tag pair mainly provides a way to link two documents. The cases mentioned above clearly benefit from such a linkage which the expectation that readers of one RFC as least look or also read the other RFC. Additionally, there are more cases where such a linkage could be useful to improve awareness of some newer related technology without providing any indication on the importance of the linked document. As the conditions for the use of the Updates tag are not clear, often it is not used in such cases.
This document recommends the discontinuation of the use of the Updates/Updated by tag pair, and instead proposes three new tag pairs that have well-defined meanings and use cases.
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 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
Based on the problems identified above this document defines three new tag pairs with the following meanings:
Amends/Amended by: This tag pair is used with an amending RFC that changes the amended RFC. This could include bug fixes, behavior changes etc. This is intended to specify mandatory changes to the protocol. The goal of this tag pair is to signal to anyone looking to implement the amended RFC that they MUST also implement the amending RFC.
Extends/Extended by: This tag pair is used with an extending RFC that defines an optional addition to the extended RFC. This can be used by documents that use existing extension points or clarifications that do not change existing protocol behavior. This signals to implementers and protocol designers that there are changes to the extended RFC that they need to consider but not necessarily implement.
See Also/See Also: This is intended as a catch-all tag where two documents are related loosely but do not fit either of the above categories. The main intention of this tag is to provide a forward reference from the existing RFC to the RFCs that may be of interest to read.
These three tags MUST only be used for the defined meanings, mostly with respect to the implication on implementation requirements. This document does not mandate the use of these tags if one of the described use cases apply. Tags are optional metadata that are useful to understand the context of RFCs and navigate the RFC series.
[NOTE: This is open for discussion and we would like opinions on whether the use of Updates needs to be discontinued for all future documents or not. This requires further discussion with the RFC Editor and the other stream managers to see if we can have a unified policy for all streams]
This document makes the updates tag obsolete for future use: it MUST NOT be used in new IETF stream documents. The new tags are to be used instead, beginning with the publication of this document as an RFC.
However, the Updates/Updated by tag pair will remain in existing documents and there is no plans to change these metadata in order to apply the new tags instead. Any such change would need working group consensus as it might not be straight forward in all cases. Further, simply replacing the tag would not be sufficient, as also RFCs that currently do not have an updates tag would probably qualify to have one of the new tags defined in this document.
This document does not impose any requirements on the form of the amendment made. Some RFCs use and OLD/NEW style to highlight actual text changes others simply describe the changes in text. Both can make sense in certain situation. However, this document does recommend to use the OLD/NEW rather for smaller and a limited number of changes, while if larger or many changes are needed, a new document revision that obsoletes the old RFC should be considered.
The RFC style guide (add ref!) recommends to indicate updates in the abstract and introduction. Note that both is needed as the abstract is meant to function in a stand-alone fashion. This document will keep this practice for the new Amends/Amended by and Extends/Extended by tag pairs as well. It is further recommended to provide additional information about the extension in the abstract or introduction for the Extends/Extended by tag pair in order to provide the reader some assistance whether he or she also needs to read the rest of extending RFC.
For the See Also/See Also tag pair, additional information of the linked RFC may be added in the introduction but there is no expectation to name these RFC in the abstract.
There will be a need to update the RFC Style Guide [RFC7322] (and specifically Section 4.1.4.) in order to discuss the new tags if and when this document is published.
The authors would like to thank Alexey Melnikov, Alvaro Retana, Barry Leiba, Eric Vyncke, Heather Flanagan, Martin Vigoureux and Sandy Ginoza for their reviews and comments that improved this document.