Subject: Re: [rfc-i] I-D Action: draft-kuehlewind-update-tag-01.txt

From: "Adrian Farrel" <[email-masked]>
Date: Wed, 4 Sep 2019 14:05:10 +0100

Thanks Mirja and Suresh,

I believe you have correctly identified that the "updates" relationship has
for a long time been unclear. I think that authors are unable to decide how
to use the tag, WG chairs and even ADs are unable to give consistent advice,
and readers do not know how to understand the tag. Although previous IESGs
have been clear that the meaning was per your proposed "Amends/Amended by",
that clarity no longer exists.

"Something should be done."

Below are some comments on the current version of your draft. Hope they
help.

Thanks,
Adrian

== Substantive points

Can you clarify in the document whether it is your intention that this
applies to all RFCs or just to the IETF stream.

---

The Abstract and Introduction say "discontinue the use", and I find that
ambiguous. I do not think that you are proposing changing the metadata of
every RFC related to an existing "updates" tag. Indeed, your section 4.1
explicitly says (with the caveat that it is open for discussion) that you
don't propose that change. So I think you should be saying "no longer allow
the use for new RFCs".

It might be helpful, to change the title of section 4.1 as well.

---

Part of what you are achieving is highly desirable - you are writing down
what the metadata means. Thanks.
I wonder, however, whether you still need to write down what "Updates" means
because the large cannon still exists and will continue to be read and
implemented. Readers will look at this document and say, "Great, I
understand what the new tags mean," but they will be none the wiser about
existing documents.
I believe it would be useful to write some text about "Updates" and how it
should be interpreted in the future. I think you'll find that it may cover
all cases of "Amends", some cases of "Extends", and no cases of "See Also". 

---

I think that "Extends" needs a section like 4.2 because many people will
still get stuck between "Amend" and "Extend". For example, I add a new TLV
to a protocol - that's an extension, right? But it is my intention that new
implementations of the base protocol must include the new TLV - oh, that's
an update.

== Nits:

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.

I think you should use the past tense, here, to allow for the possibility
that your document will become an RFC.

   Some published RFCs include a metadata tag called "Updates" which
   provides a between an RFC and an older RFC.  A similar metadata tag
   called "Updated by" provides the reverse direction linkage.

Similar text in the Introduction.

---

Instead saying "this document recommends" I think you can afford to be more
definitive. You are stopping it!

(Abstract and Introduction)

---

Instead of saying that the document "proposes" please say it "defines".
(Consider the text when/if this is an RFC.)

(Abstract and Introduction)

---

Could you please include a ToC per the style guide.

---

Section 1

s/The "Updates/Updates by" tag pair/The "Updates/Updated by" tag pair/

---

Do a quick search on the document and make a decision on the capitalisation
of "update"

---

4.3 

Missing ref to 7322

s/Note that both is needed/Note that both are needed/

---

Section 5

I think you're going to need to want to ask for changes to xml2rfc and
idnits

-----Original Message-----
From: I-D-Announce <[email-masked]> On Behalf Of
[email-masked]
Sent: 04 September 2019 11:58
To: [email-masked]
Subject: I-D Action: draft-kuehlewind-update-tag-01.txt

A New Internet-Draft is available from the on-line Internet-Drafts
directories.

        Title           : Definition of new tags for relations between RFCs
        Authors         : Mirja Kuehlewind
                          Suresh Krishnan
	Filename        : draft-kuehlewind-update-tag-01.txt
	Pages           : 5
	Date            : 2019-09-04

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.

The IETF datatracker status page for this draft is:
https://datatracker.ietf.org/doc/draft-kuehlewind-update-tag/

There are also htmlized versions available at:
https://tools.ietf.org/html/draft-kuehlewind-update-tag-01
https://datatracker.ietf.org/doc/html/draft-kuehlewind-update-tag-01

A diff from the previous version is available at:
https://www.ietf.org/rfcdiff?url2=draft-kuehlewind-update-tag-01

Please note that it may take a couple of minutes from the time of submission
until the htmlized version and diff are available at tools.ietf.org.

Internet-Drafts are also available by anonymous FTP at:
ftp://ftp.ietf.org/internet-drafts/

_______________________________________________
I-D-Announce mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/i-d-announce
Internet-Draft directories: http://www.ietf.org/shadow.html
or ftp://ftp.ietf.org/ietf/1shadow-sites.txt

_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest