Subject: [rfc-i] "Obsoleting" a perfectly valid document

From: Carsten Bormann <[email-masked]>
Date: Thu, 4 Jul 2019 18:50:55 +0200

I hope the current high-volume threads (and the various holidays) still allow me to ask one question here:

The current draft for the 7049bis document says:

> This document obsoletes RFC 7049.

Very clear to people who live and breathe RFCs.
What most everybody else will read from this is:

> This document obsoletes all implementations of RFC 7049.

This is not at all what is going on, though.

What I would really like to say is something like

> This document is a revised edition of RFC 7049, with editorial improvements, added detail, and a few fixed errata.  The revision formally “obsoletes” RFC 7049, while keeping full compatibility of the interchange format — it does not create a new “version” of the format.

But then I’m not a friend of scare quotes.

What is the right way to say this?  Any examples to steal from?

Grüße, Carsten

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

---

From: Tim Bray <[email-masked]>
Date: Thu, 4 Jul 2019 10:04:45 -0700

I agree with Carsten's underlying concern and also like his proposed
language.

On Thu, Jul 4, 2019 at 9:51 AM Carsten Bormann <[email-masked]> wrote:

> > This document is a revised edition of RFC 7049, with editorial
> improvements, added detail, and a few fixed errata.  The revision formally
> “obsoletes” RFC 7049, while keeping full compatibility of the interchange
> format — it does not create a new “version” of the format.
>

---

From: Дилян Палаузов <[email-masked]>
Date: Thu, 04 Jul 2019 17:51:25 +0000

Hello Carsten,

this discussion is now out of any context.

A RFC can be updated, obsoleted, moved to historic.  When it is updated, the reader has to read both the original and
the update to understand the whole concept.  When it is obsoleted, the reader has to read only the obsoleting
document.  When it is moved to historic, the reader does not have to read anything.

As an examle: https://tools.ietf.org/html/rfc2426 contains at the top "Obsoleted by: 6350".  For this to happen, RFC
6350 states: “This document obsoletes RFCs 2426”.

If 7049bis states ... “obsoletes” RFC 7049, then https://tools.ietf.org/html/rfc7049 will be changed to state in the
upper lines:

“Obsoleted” by RFC (7049bis) - with the quotes.  So far no RFC is obsoleted by using quotes on the verb.

The wording “This document obsoletes RFC 7049.” does appear in many replaced RFC, but in no means shall be understood as
neglecting the work of the authors of those RFCs.

As far as the wording “This document obsoletes all implementations of RFC 7049.” is concerned, without knowing the
details, I would say, that if the changes are backwards compatible, then the implementations are not obsoleted and this
shall be addressed in first place to the authors of 7049bis.

For the record, if you mean https://tools.ietf.org/html/draft-ietf-cbor-7049bis-06 or 
https://tools.ietf.org/html/draft-ietf-cbor-7049bis-05, you are mentioned as author and I do not find inside the string
“This document obsoletes all implementations of RFC 7049”.    Appendix F “Changes from RFC 7049” does not sound like
this.

The right way to tell the reader, that she has to read only the new document, is to state in the new document, that the
old one is obsoleted.

Regards
  Дилян

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 4 Jul 2019 20:31:21 +0200

Hi Дилян,

sorry for not giving more context.  The text I don’t like actually now is in https://tools.ietf.org/html/draft-ietf-cbor-7049bis-06, twice, in the abstract and at the end of the introductory text of Section 1.

I do understand the language we use inside the IETF for document revisions, and I agree that the sentence we wrote is clear for readers that know that special language.  Actually, giving that information is necessary for the reason you give:  So people know which documents they no longer need to read.

However, for someone who isn’t as familiar with RFCs, there is a significant danger of misunderstanding the term “obsoletes”: 

> obsolete | ˌɑbsəˈlit | 
> verb [with object] chiefly US 
> cause (a product or idea) to be or become obsolete by replacing it with something new: “we’re trying to stimulate the business by obsoleting last year’s designs”. 
[cited from New Oxford American Dictionary]

But the idea or the product are not obsolete, only the specification has been revised after 5 years of experience with people using it.  People use RFC numbers both to refer to the actual RFC and to the concept defined in there (as in “an RFC822 message”, of course usually with the number of an obsoleted RFC…).

My message was a request for help writing this up in a better way, but also a repeat of my ceterum censeo that some of the language we use to describe our processes is incomprehensible to outsiders.

Paul Hoffman has fixed up my proposed text a bit (https://github.com/cbor-wg/CBORbis/pull/89), and with the support here I think this can go in.  Still, I would like to hear about ways other people have handled similar situations — it is quite tedious to extract this kind of information from some 1140 RFCs that obsolete others.

(Just to give one example: RFC 2822, which obsoleted RFC 822 and was then obsoleted by RFC 5322, never says so except in the head of the front page.  It also goes ahead and defines a whole section of “obsolete syntax”, which retains some no longer desirable parts of RFC 822 only to keep some measure of backward compatibility.  None of this changed in RFC 5322.  Oh, and RFC 822 obsoletes RFC 733, but uses that term again only in its front page head, and uses “revises” in the text to describe the not insignificant technical changes that were made.)

Grüße, Carsten

---

From: Michael Richardson <[email-masked]>
Date: Thu, 04 Jul 2019 15:16:10 -0400

> But the idea or the product are not obsolete, only the specification
    > has been revised after 5 years of experience with people using it.
    > People use RFC numbers both to refer to the actual RFC and to the
    > concept defined in there (as in “an RFC822 message”, of course usually
    > with the number of an obsoleted RFC…).

Agreed. I think that we need to obsolete the term "obsolete" and create three
or four more new terms.

    > My message was a request for help writing this up in a better way, but
    > also a repeat of my ceterum censeo that some of the language we use to
    > describe our processes is incomprehensible to outsiders.

    > Paul Hoffman has fixed up my proposed text a bit
    > (https://github.com/cbor-wg/CBORbis/pull/89), and with the support here
    > I think this can go in.  Still, I would like to hear about ways other
    > people have handled similar situations — it is quite tedious to extract
    > this kind of information from some 1140 RFCs that obsolete others.

I also like the text.

    > (Just to give one example: RFC 2822, which obsoleted RFC 822 and was
    > then obsoleted by RFC 5322, never says so except in the head of the
    > front page.  It also goes ahead and defines a whole section of
    > “obsolete syntax”, which retains some no longer desirable parts of RFC
    > 822 only to keep some measure of backward compatibility.  None of this
    > changed in RFC 5322.  Oh, and RFC 822 obsoletes RFC 733, but uses that
    > term again only in its front page head, and uses “revises” in the text
    > to describe the not insignificant technical changes that were made.)

So, in this case, the lack of outside-of-IETF awareness of the status of
RFC822 [the whole rfc++ debate] contributes to the fact that nobody worries
that RFC822/2822 are obsolete in favour of 5288.   I think that it helps the
technical people that the "822" is repeated, but we can't easily do this for
every document.

--
Michael Richardson <[email-masked]>, Sandelman Software Works
 -= IPv6 IoT consulting =-

---

From: Дилян Палаузов <[email-masked]>
Date: Thu, 04 Jul 2019 21:06:27 +0000

Hello Carsten,

if somebody considers RFC 7049 as outdated and no longer useful, but RFC 7049bis as current, then there is no problem,
as long as the person sticks to RFC 7049bis and it is compatible with RFC 7049.

The shorter the wording, the better.  The “Status of this Memo”, “Copyright Notice”, RFC2119-KEYWORDS/Terminology
definitions repeated everywhere, lead to wasting considerable amount of papers, when I print RFCs, and this counts over
the whole globe, for every person that prints an RFC.  It will be much better, if there is a single RFC containing a
Status, Copyright Notice, and Keyword definitions (incl. the word obsoleted) that are valid both for that RFC and for
each other RFC that references the first RFC.  Think on all saved paper and time saved skipping that sections.

The RFCs are interconnected and to understand the concepts in one RFC one has to read several of them, so needs to get
used to their style.

So, instead of the word “obsoleting”, another single word can be taken, like “This RFC replaces/substitutes/supersedes
RFC x".  The details go in a section, describing the differences with the replaced document and from that section it
shall be evident, that this is a revised edition.

I think at the end it is up to the authors, here you, to decide how to word this.

Regards
  Дилян

---

From: Brian E Carpenter <[email-masked]>
Date: Fri, 5 Jul 2019 15:16:54 +1200

> But then I’m not a friend of scare quotes.

The text still works without them.
 
> What is the right way to say this?  Any examples to steal from?

It might have been better if, back in ancient times, the RFC Editor
of the day had included "Replaces" among the options, because in
many cases that is more heplful than "Obsoletes", which has more
than one possible meaning. But we don't have that option.

I don't see anything wrong with including a paragraph like you
suggest, with a forward reference to https://tools.ietf.org/html/draft-ietf-cbor-7049bis-06#appendix-F. Is that appendix complete?

RFC8200 is a bit different because it does make some substantive changes
from RFC2460, and describes them at https://tools.ietf.org/html/rfc8200#appendix-B.
However, I wish 6man had thought to include a similar paragraph.

Regards
   Brian

---

From: Loa Andersson <[email-masked]>
Date: Fri, 5 Jul 2019 10:51:56 +0200

Carsten,

I still think the points you make merit a discussion, there is also
at least one point that the authors should take care of.

Inline please,

>>> This document obsoletes all implementations of RFC 7049.

Yes - so it does, but if that is true it also lacks some info
in the header.

If the draft is written in xml the <rfc> element should look
somewhat like this:

<rfc category="info" docName="draft-xxxx-foo-bar-00"
      ipr="trust200902" obsoletes="7049">

That will generate

"Obsoletes: RFC 7049 (if approved)"

Which at least makes it clear for the in-experienced reader that
there is a condition to be fulfilled before RFC 7049 is obsoleted.

There is nothing that prevent authors to use the same language in
the abstract.

/Loa

-- 

Loa Andersson                        email: [email-masked]
Senior MPLS Expert
Bronze Dragon Consulting             phone: +46 739 81 21 64
_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: Loa Andersson <[email-masked]>
Date: Fri, 5 Jul 2019 11:03:11 +0200

Brian,

> than one possible meaning. But we don't have that option.

Are you saying that (given good motivations and rough consensus) the
RFC Editor could add "replace" to the options (or even have "replace"
obsolete "obsolete")?

/Loa

--

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 5 Jul 2019 11:20:35 +0200

> RFC Editor could add "replace" to the options (or even have "replace"

If we want to discuss changing the labels (my original question was more about trying to stay in the existing label set, but I’m also happy if there is a change):

RFC 1388 (RIPv2) “updated" RFC 1058 (RIPv1), the document.
It also obsoleted (not the RFC term) RIPv1 as a protocol.
RFC 1388 was “obsoleted” by RFC 1723, which still “updates” RFC 1058.
RFC 1723 in turn was obsoleted by RFC 2453, which no longer “updates” RFC 1058, apparently as it is standing on its own.
(RFC 1058 is historic now, so the question whether it was obsoleted by RFC 2453 is moot.)

I think it would be good if we could catch nuances like this.

Grüße, Carsten

---

From: S Moonesamy <[email-masked]>
Date: Fri, 05 Jul 2019 09:38:32 -0700

Hi Carsten,
At 09:50 AM 04-07-2019, Carsten Bormann wrote:
> > This document is a revised edition of RFC 
> 7049, with editorial improvements, added 
> detail, and a few fixed errata.  The revision 
> formally "obsoletes" RFC 7049, while keeping 
> full compatibility of the interchange format — 
> it does not create a new "version" of the format.
>But then I'm not a friend of scare quotes.

For what it is worth, what you described above 
sounds like an update of the specification.  The 
"obsoletes" informs the reader that there is a 
more recent version of the specification.

>What is the right way to say this?  Any examples to steal from?

Please see Section 1 of RFC 5322.

Regards,
S. Moonesamy

---

From: Brian E Carpenter <[email-masked]>
Date: Sat, 6 Jul 2019 08:52:34 +1200

> I think it would be good if we could catch nuances like this.

Yes, but life is complicated and each case may be different.
While I do think that a "Replaces" tag would be useful, I think
it's really a standards process issue that the IETF should sort out
first, e.g. like this:
https://tools.ietf.org/html/draft-ietf-newtrk-repurposing-isd-04

    Brian