Network Working Group                                      M. Kuehlewind
Internet-Draft                                                  Ericsson
Intended status: Best Current Practice                       S. Krishnan
Expires: March 7, 2020                                            Kaloom
                                                      September 04, 2019


           Definition of new tags for relations between RFCs
                     draft-kuehlewind-update-tag-01

Abstract

   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.

Status of This Memo

   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 March 7, 2020.

Copyright Notice

   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



Kuehlewind & Krishnan     Expires March 7, 2020                 [Page 1]

 
Internet-Draft             New Tag Definitions            September 2019


   (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.

.  Introduction

   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.



Kuehlewind & Krishnan     Expires March 7, 2020                 [Page 2]

 
Internet-Draft             New Tag Definitions            September 2019


   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.

.  Requirements Language

   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.

.  New Definitions

   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.

   This document does not impose any restrictions on the status or
   maturity level of the RFC that uses these new tags in relation the
   RFC that gets amended/extended.  Further, no restrictions are made on
   the use of these tags across RFC streams.  However, it is expected



Kuehlewind & Krishnan     Expires March 7, 2020                 [Page 3]

 
Internet-Draft             New Tag Definitions            September 2019


   that some cases are less likely, e.g. an IETF-stream RFC gets amended
   by an RFC from another stream.  Examples exist where non IETF-stream
   documents update IETF-stream documents.  However, these updates
   usually utilize an existing extension point and therefore the use of
   "Extends" would be expected in future, e.g.  RFC 3579 (RADIUS Support
   For EAP) which is a document in the Independent Submission Stream
   updates RFC 2869 (RADIUS Extensions), an IETF stream document.  In
   fact, this new, more clear definition of tags could even lead to an
   increase in cross stream usage of the "Extends" tag (if adopted by
   other streams, which is still open for discussion and may be
   reflected in future versions of this document).

.  Additional Recommendations

4.1.  Discontinuation of the Use of Updates/Updated by

   [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 require
   changing/updating/amending the RFC carrying th "Updates" tag and
   building consensus for such a change might also not be straight
   forward in all cases.  Further, simply replacing the tag would any
   way 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.

4.2.  Amendments

   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.





Kuehlewind & Krishnan     Expires March 7, 2020                 [Page 4]

 
Internet-Draft             New Tag Definitions            September 2019


4.3.  Indication of Linkage in the Abstract and Introduction

   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.

.  Future work

   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.

.  Acknowledgments

   The authors would like to thank Alexey Melnikov, Alvaro Retana, Barry
   Leiba, Eric Vyncke, Heather Flanagan, Martin Vigoureux, Brian
   Carpenter and Sandy Ginoza for their reviews and comments that
   improved this document.

Authors' Addresses

   Mirja Kuehlewind
   Ericsson

   Email: mirja.kuehlewind@ericsson.com


   Suresh Krishnan
   Kaloom

   Email: Suresh@kaloom.com










Kuehlewind & Krishnan     Expires March 7, 2020                 [Page 5]