Subject: Proposed IESG Statement on the use of the “Updates” header

From: Ben Campbell <[email-masked]>
Date: Tue, 11 Sep 2018 10:55:51 -0500

Hi Everyone,

There have been several discussions lately about the use and meaning of the “Updates” header in RFCs, and the resulting “Updates”/“Updated by” relationships. The IESG is thinking about making the following statement, and solicits feedback.

Thanks!

Ben.
--------------------------------------------

There has been considerable confusion among the IETF community about the formal meaning of the “Updates” / "Updated by" relationship in IETF stream RFCs. The “Updates” header has been historically used for number of reasons of various strength. For example, the “Updates” header may be used to indicate critical normative updates (i.e. bug fixes), optional extensions, and even “additional information”.

The IESG intends these headers to be used to inform readers of an updated RFC that they need to be aware of the RFC that updates it. The headers have no formal meaning beyond that. In particular, the headers do not, by themselves, imply a normative change to the updated RFC, nor do they, by themselves, imply that implementers must implement the updating RFC to continue to comply with the updated one.

The specific reasons that a given RFC updates another should be described in the abstract and body of the new RFC. The level of detail may differ between the abstract and the body; typically an abstract should contain enough detail to help readers decide if they need to read the rest of the RFC. The body should contain enough detail for readers to fully understand the nature of the update.

The importance of including an “Updates” header depends on the nature of the update. Normative updates that do not use a known extension point should always include an “Updates” header. Extensions that do use known extension points do not typically need to include the “Updates” header, but may in cases where it’s important to make the extension known to readers of the original RFC. Other uses of “Updates” may be appropriate when it’s important for readers to know about them; for example a new RFC may expand security or operational considerations in a way that is not normative, but still important.

RFCs that fully replace other RFCs should typically use the “Obsoletes” header rather than the “Updates” header. The “Updates” header should be used to flag updates to published RFCs; it is not appropriate to “Update” an Internet-Draft.

---

From: tom petch <[email-masked]>
Date: Tue, 11 Sep 2018 16:31:47 +0000

Ben

I don't understand it! In particular

'Normative updates that do not use a known extension point should always
include an “Updates” header.'

leaves me ignorant.

'Normative' I am well familiar with from I-D references but that meaning
does not seem to apply here (since Normative as a Reference means you
must understand the referenced work)..

'..known extension point..' I am not familiar with except for a rather
technical discussion which I read - but did not understand - on this
list recently.

To give a practical problem; when an I-D adds new entries to an existing
registry, is that an 'Updates'?  I have seen ADs firmly tell WG Chairs,
holding the contrary opinion, that it is not, and I thought that that
was settled, but applying this statement to that situation leaves me in
ignorance.

Tom Petch

----- Original Message -----
From: "Ben Campbell" <[email-masked]>
To: <[email-masked]>
Cc: "The IESG" <[email-masked]>
Sent: Tuesday, September 11, 2018 4:55 PM

Hi Everyone,

There have been several discussions lately about the use and meaning of
the “Updates” header in RFCs, and the resulting “Updates”/“Updated by”
relationships. The IESG is thinking about making the following
statement, and solicits feedback.

Thanks!

Ben.

There has been considerable confusion among the IETF community about the
formal meaning of the “Updates” / "Updated by" relationship in IETF
stream RFCs. The “Updates” header has been historically used for number
of reasons of various strength. For example, the “Updates” header may be
used to indicate critical normative updates (i.e. bug fixes), optional
extensions, and even “additional information”.

The IESG intends these headers to be used to inform readers of an
updated RFC that they need to be aware of the RFC that updates it. The
headers have no formal meaning beyond that. In particular, the headers
do not, by themselves, imply a normative change to the updated RFC, nor
do they, by themselves, imply that implementers must implement the
updating RFC to continue to comply with the updated one.

The specific reasons that a given RFC updates another should be
described in the abstract and body of the new RFC. The level of detail
may differ between the abstract and the body; typically an abstract
should contain enough detail to help readers decide if they need to read
the rest of the RFC. The body should contain enough detail for readers
to fully understand the nature of the update.

The importance of including an “Updates” header depends on the nature of
the update. Normative updates that do not use a known extension point
should always include an “Updates” header. Extensions that do use known
extension points do not typically need to include the “Updates” header,
but may in cases where it’s important to make the extension known to
readers of the original RFC. Other uses of “Updates” may be appropriate
when it’s important for readers to know about them; for example a new
RFC may expand security or operational considerations in a way that is
not normative, but still important.

RFCs that fully replace other RFCs should typically use the “Obsoletes”
header rather than the “Updates” header. The “Updates” header should be
used to flag updates to published RFCs; it is not appropriate to
 “Update” an Internet-Draft.

---

From: Ben Campbell <[email-masked]>
Date: Tue, 11 Sep 2018 11:40:48 -0500

> On Sep 11, 2018, at 11:31 AM, tom petch <[email-masked]> wrote:
> 
> Ben
> 

A known extension point is any mechanism in the original RFC designed to allow extensibility without modifying the RFC. IANA registered code points are a common approach. Feature negotiation mechanisms also come to mind.

Can you suggest a better term for this?

> was settled, but applying this statement to that situation leaves me in

The intent is that these are usually not “Updates”. But they can be if there are special circumstances, which I presume would be documented in the text that describes the nature of the update. An individual AD may or may not agree with an argument that a particular update is “special” in this sense, but I believe we all agree that such special cases are in the realm of possibility.

Thanks!

Ben.

---

From: Paul Wouters <[email-masked]>
Date: Tue, 11 Sep 2018 12:45:51 -0400

I always interpreted it as “don’t implement this RFC as-is without reading the RFC that updates this document”

So modular extensions would not need to update:

Sent from my iPhone

> On Sep 11, 2018, at 11:55, Ben Campbell <[email-masked]> wrote:
> 
> Hi Everyone,
>

---

From: tom petch <[email-masked]>
Date: Tue, 11 Sep 2018 16:58:42 +0000

----- Original Message -----
From: "Ben Campbell" <[email-masked]>
Sent: Tuesday, September 11, 2018 5:40 PM

> technical discussion which I read - but did not understand - on this

A known extension point is any mechanism in the original RFC designed to
allow extensibility without modifying the RFC. IANA registered code
points are a common approach. Feature negotiation mechanisms also come
to mind.

Ben

No:-(  I understand your explanation and see that concept in many
places, but do not know of any generic term for it.  (Thus I think of
YANG augments, but that term would probably not make sense to those not
versed in YANG). Rather, I would like to see your sentence of
explanation or something like it in the statement.

Tom Petch

> was settled, but applying this statement to that situation leaves me
in

The intent is that these are usually not “Updates”. But they can be if
there are special circumstances, which I presume would be documented in
the text that describes the nature of the update. An individual AD may
or may not agree with an argument that a particular update is “special”
in this sense, but I believe we all agree that such special cases are in
the realm of possibility.

Thanks!

Ben.

---

From: Robert Sparks <[email-masked]>
Date: Tue, 11 Sep 2018 13:08:44 -0500

I can live with this statement, but I don't like it.

I'm in the camp that prefers the more specific "This changes the code 
you need to write" camp - I would prefer Update be restricted to the 
cases where you are changing the protocol defined in the updated 
document in an essential way. The use of extension points doesn't cross 
that bar. So, count me as against everything in the second paragraph 
beyond the first sentence.

That said, I again note that I can live with what's proposed.

RjS

p.s. I assume you've rehashed previous IESGs discussions of adding a 
"See Also" relationship?

---

From: Michael Richardson <[email-masked]>
Date: Tue, 11 Sep 2018 14:25:20 -0400

I have read the statement, and I think it's a bit weak.
I don't feel very clarified, and Tom asked the question I would have.

Ben Campbell <[email-masked]> wrote:
    >> To give a practical problem; when an I-D adds new entries to an
    >> existing registry, is that an 'Updates'?  I have seen ADs firmly tell
    >> WG Chairs, holding the contrary opinion, that it is not, and I thought
    >> that that was settled, but applying this statement to that situation
    >> leaves me in ignorance.

    > in this sense, but I believe we all agree that such special cases are
    > in the realm of possibility.

I don't think that this situation is terribly rare or special.
It definitely happens regularly in my opinion.

When doing -bis documents with the intent of Obsoletes a previous document,
I think that all of the Updates: need to be reviewed.  I think that Updates:
should be considered in a future context of revising the document.
  "if you were revising it now, would you include the new text?"

If the feature/extension is still quite rare, unpopular, or very specific to
very narrow scopes, then I don't think it should Updates:.    In most cases
when a document in WG X does an allocation from a document produced by WG Y,
I don't think it's ever an Update. (X!=Y, except when X and Y are clearly
related, such when Y=="Xupdates" or "Xmaint")

When WG X does such an allocation for the WG-X-protocol-foo-extension, then I
think it definitely is an update, but that's not because it did the
allocation, but because of what it does to the protocol.

--
]               Never tell me the odds!                 | ipv6 mesh networks [
]   Michael Richardson, Sandelman Software Works        | network architect  [
]     [email-masked]  http://www.sandelman.ca/        |   ruby on rails    [

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

---

From: Kathleen Moriarty <[email-masked]>
Date: Tue, 11 Sep 2018 14:30:36 -0400

Sent from my mobile device

> On Sep 11, 2018, at 2:08 PM, Robert Sparks <[email-masked]> wrote:
> 
> I'm in the camp that prefers the more specific "This changes the code you need to write" camp - I would prefer Update be restricted to the cases where you are changing the protocol defined in the updated document in an essential way. The use of extension points doesn't cross that bar. So, count me as against everything in the second paragraph beyond the first sentence.

+1

Kathleen 

> p.s. I assume you've rehashed previous IESGs discussions of adding a "See Also" relationship?
>

---

From: Bob Hinden <[email-masked]>
Date: Tue, 11 Sep 2018 11:31:27 -0700

Ben,

> On Sep 11, 2018, at 8:55 AM, Ben Campbell <[email-masked]> wrote:
> 
> Hi Everyone,
> 

I worry about the

   "abstract should contain enough detail to help readers decide if they need to read the rest of the RFC”

This may result in a long Abstract depending on the nature of the “update” and defeat the purpose of the abstract if it gets too long.   I think the update text in Abstract should be limited to a few sentences and that the IESG statement include something to that effect.

> RFCs that fully replace other RFCs should typically use the “Obsoletes” header rather than the “Updates” header. The “Updates” header should be used to flag updates to published RFCs; it is not app…

While on the general topic of “Updates”.   Having done the process that resulted in RFC8200 that included incorporating the updates for RFC2460, it’s also important that updating RFCs are very clear what the actual change is.  This is important both for someone doing a BIS document, and for implementations understanding what the changes are.   It can be quite confusing when there a multiple updates to a single RFC.

Thanks,
Bob

---

From: "Adrian Farrel" <[email-masked]>
Date: Tue, 11 Sep 2018 19:38:50 +0100

Pretty much agree with Robert here.

Can live with it, and some rule will be more helpful than no rule.

But there may be an issue caused by talking about "complying with an RFC". What we want to do is implement protocols in a way that ensures interoperability. So what Robert says about "changing the protocol defined in the updated document in an essential way" is the language I'd prefer. 

I guess people are worried that their "compliant" implementation will suddenly be declared "non-compliant" by the publication of an "Update". That's a good worry, but we should recall that if a spec is broken, then the implementation is also broken and claiming compliance won't help. So, yes, adding features in a backward compatible way is not an Update.

As I said, and just like Robert, I can live with what's proposed. Just would prefer it different.

Thanks,
Adrian

> -----Original Message-----
> From: ietf [mailto:[email-masked]] On Behalf Of Robert Sparks
> Sent: 11 September 2018 19:09
> To: Ben Campbell; [email-masked]
> Cc: The IESG
> Subject: Re: Proposed IESG Statement on the use of the “Updates” header
> 
> > There have been several discussions lately about the use and meaning of the
> “Updates” header in RFCs, and the resulting “Updates”/“Updated by”
> relationships. The IESG is thinking about making the following statement, and
> solicits feedback.
> >
> > Thanks!
> >
> > Ben.
> formal meaning of the “Updates” / "Updated by" relationship in IETF stream
> RFCs. The “Updates” header has been historically used for number of reasons of
> various strength. For example, the “Updates” header may be used to indicate
> critical normative updates (i.e. bug fixes), optional extensions, and even
> “additional information”.
> >
> > The IESG intends these headers to be used to inform readers of an updated
> RFC that they need to be aware of the RFC that updates it. The headers have no
> formal meaning beyond that. In particular, the headers do not, by themselves,
> imply a normative change to the updated RFC, nor do they, by themselves, imply
> that implementers must implement the updating RFC to continue to comply with
> the updated one.
> >
> > The specific reasons that a given RFC updates another should be described in
> the abstract and body of the new RFC. The level of detail may differ between the
> abstract and the body; typically an abstract should contain enough detail to help
> readers decide if they need to read the rest of the RFC. The body should contain
> enough detail for readers to fully understand the nature of the update.
> >
> > The importance of including an “Updates” header depends on the nature of the
> update. Normative updates that do not use a known extension point should
> always include an “Updates” header. Extensions that do use known extension
> points do not typically need to include the “Updates” header, but may in cases
> where it’s important to make the extension known to readers of the original RFC.
> Other uses of “Updates” may be appropriate when it’s important for readers to
> know about them; for example a new RFC may expand security or operational
> considerations in a way that is not normative, but still important.
> >
> > RFCs that fully replace other RFCs should typically use the “Obsoletes” header
> rather than the “Updates” header. The “Updates” header should be used to flag
> updates to published RFCs; it is not appropriate to “Update” an Internet-Draft.
> >
> >

---

From: Ben Campbell <[email-masked]>
Date: Tue, 11 Sep 2018 13:42:16 -0500

> On Sep 11, 2018, at 1:08 PM, Robert Sparks <[email-masked]> wrote:
> 

Yes :-)

This statement is intended to be a clarification of what the IESG believes to be the correct interpretation of the existing headers. This doesn’t prevent community efforts to add new ones.

Thanks!

Bne.

---

From: Ben Campbell <[email-masked]>
Date: Tue, 11 Sep 2018 13:44:50 -0500

> On Sep 11, 2018, at 1:31 PM, Bob Hinden <[email-masked]> wrote:
> 
> Ben,
> 

I agree with you on the length. I think we assumed that detail to “decide if you need to read the document” could be done in a a few sentences. We could add something to that effect, but I don’t think we want to take on the general topic of “what makes a good abstract” in this statement.

> While on the general topic of “Updates”.   Having done the process that resulted in RFC8200 that included incorporating the updates for RFC2460, it’s also important that updating RFCs are very clea…

I agree.

Ben.

---

From: Christer Holmberg <[email-masked]>
Date: Tue, 11 Sep 2018 18:51:49 +0000

Hi,

...

>> This may result in a long Abstract depending on the nature of the “update” and defeat the purpose of the abstract 
>> if it gets too long.   I think the update text in Abstract should be limited to a few sentences and that the IESG statement 
>> include something to that effect.
>
> I agree with you on the length. I think we assumed that detail to “decide if you need to read the document” could be done
> in a a few sentences. We could add something to that effect, but I don’t think we want to take on the general topic of “what 
> makes a good abstract” in this statement.

I think there shall always be an "Update to RFC XXXX" section, where the actual updates are defined. The updates may be clear to the people who have been working on the spec, but maybe not to others.

In addition, the Introduction (rather than the Abstract) can give an overview of what the updates are.

Regards,

Christer

---

From: Ben Campbell <[email-masked]>
Date: Tue, 11 Sep 2018 13:52:21 -0500

Hi Adrien,

The question of compliance came up in internal IESG discussion.

I think that whenever “compliance” comes up in discussion, we are off-mission. RFCs exist to enable interoperability. Whether an implementation complies with an RFC is a red herring; what matters is if it interoperates with other implementations. From that perspective, I think questions about whether an implementation continues to “comply” are irrelevant.

The point is to give implementors enough information to decide if they need to apply an update. In some cases they may need to do so to continue to interoperate in the future, or to improve interoperability with other implementations. We don’t think questions like that can be fully answered by the Updates header alone; that’s why we ask that the updating RFC contain enough information to answer them.

Thanks!

Ben.

> On Sep 11, 2018, at 1:38 PM, Adrian Farrel <[email-masked]> wrote:
>

---

From: "Adrian Farrel" <[email-masked]>
Date: Tue, 11 Sep 2018 20:53:19 +0100

Ben,

Thanks for your time.

> I think that whenever “compliance” comes up in discussion, we are off-mission.
> RFCs exist to enable interoperability. Whether an implementation complies with
> an RFC is a red herring; what matters is if it interoperates with other
> implementations.

So when you write in the proposed statement...

>> In particular, the headers do not, by themselves,

... is this off-mission or a red herring?

> From that perspective, I think questions about whether an
> implementation continues to “comply” are irrelevant.

Why put something irrelevant in your proposed statement?

Thanks,
Adrian

---

From: Ben Campbell <[email-masked]>
Date: Tue, 11 Sep 2018 14:57:38 -0500

> On Sep 11, 2018, at 2:53 PM, Adrian Farrel <[email-masked]> wrote:
> 
> Ben,
> 
> Thanks for your time.
> 

It was an attempt to disclaim any any meaning of “compliance”. So maybe I mispoke; statements to the effect that “this is not about compliance” are at least somewhat less off-mission :-)

---

From: Brian E Carpenter <[email-masked]>
Date: Wed, 12 Sep 2018 08:56:23 +1200

On 2018-09-12 06:08, Robert Sparks wrote:
> document in an essential way. 

The IAB already opined indirectly on this topic.
https://tools.ietf.org/html/rfc6709#page-5 says:

>>>    Extension designers should examine their design for the following
>>>    issues:
>>> 
>>>    1.  Modifications or extensions to the underlying protocol.  An
>>>        extension document should be considered to update the underlying
>>>        protocol specification if an implementation of the underlying
>>>        protocol would need to be updated to accommodate the extension.
>>>        This should not be necessary if the underlying protocol was
>>>        designed with a modular interface.

(followed by more detailed discussion).

I'm not sure the IESG text is 100% compatible with this.

> nor do they, by themselves, imply that implementers must implement the updating RFC to continue to comply with the updated one.

seems to be going to far. It may be the intent of the update that
implementations *need* to be updated, because the update fixes a bug.
In that case, "updates" really means "partially obsoletes". 

Another point: the statement is scoped to the IETF stream. But it would
be much better if all RFC streams use the same semantics. I'd like to
hear from the RFC Series Editor on this.

     Brian

> The use of extension points doesn't cross

---

From: Robert Sparks <[email-masked]>
Date: Tue, 11 Sep 2018 16:06:57 -0500

On 9/11/18 3:56 PM, Brian E Carpenter wrote:
> Another point: the statement is scoped to the IETF stream.
And it's currently standards-track-centric. The text doesn't work well 
when considering an update of, say, RFC7957 (an IETF-stream process 
document).
> But it would

---

From: Donald Eastlake <[email-masked]>
Date: Tue, 11 Sep 2018 23:30:45 -0400

This does document a change that has occurred. In the past, it was
common for important extension RFCs to have an Updates header pointing
to the RFC that they extended.

I don't object to the change in Updates but I do object to the loss of
the ability to have a simple title page pointer on a RFC to RFCs it
updates in a important way. Please add an optional "Extends:" header
to the title page to preserve the previous functionality.

Thanks,
Donald
===============================
 Donald E. Eastlake 3rd   +1-508-333-2270 (cell)
 1424 Pro Shop Court, Davenport, FL 33896 USA
 [email-masked]

---

From: Michael Richardson <[email-masked]>
Date: Wed, 12 Sep 2018 08:42:20 -0400

> to the RFC that they extended.

I don't think that the IESG proposes to remove this use.
I think that they intend to explicitely support it.
However, not every allocation by document Y of a registry from document X, is
an Updates: to X.

    > updates in a important way. Please add an optional "Extends:" header to
    > the title page to preserve the previous functionality.

    > Thanks, Donald =============================== Donald E. Eastlake 3rd
    > +1-508-333-2270 (cell) 1424 Pro Shop Court, Davenport, FL 33896 USA
    > [email-masked]

    >> On 2018-09-12 06:08, Robert Sparks wrote: > I can live with this
    >> statement, but I don't like it.
    >> >
    >> > I'm in the camp that prefers the more specific "This changes the
    >> code > you need to write" camp - I would prefer Update be restricted
    >> to the > cases where you are changing the protocol defined in the
    >> updated > document in an essential way.
    >>
    >> >>> protocol specification if an implementation of the underlying >>>
    >> protocol would need to be updated to accommodate the extension..  >>>
    >> This should not be necessary if the underlying protocol was >>>
    >> > nor do they, by themselves, imply that implementers must implement
    >> the updating RFC to continue to comply with the updated one.
    >>
    >> Another point: the statement is scoped to the IETF stream. But it
    >> would be much better if all RFC streams use the same semantics. I'd
    >> like to hear from the RFC Series Editor on this.
    >>
    >> Brian
    >>
    >> > The use of extension points doesn't cross > that bar. So, count me
    >> as against everything in the second paragraph > beyond the first
    >> sentence.
    >> >
    >> > On 9/11/18 10:55 AM, Ben Campbell wrote: >> Hi Everyone,
    >> >>
    >> >> There have been several discussions lately about the use and
    >> meaning of the “Updates” header in RFCs, and the resulting
    >> “Updates”/“Updated by” relationships. The IESG is thinking about
    >> making the following statement, and solicits feedback.
    >> >>
    >> >> Thanks!
    >> >>
    >> >> Ben.
    >> >> There has been considerable confusion among the IETF community
    >> about the formal meaning of the “Updates” / "Updated by" relationship
    >> in IETF stream RFCs. The “Updates” header has been historically used
    >> for number of reasons of various strength. For example, the “Updates”
    >> header may be used to indicate critical normative updates (i.e. bug
    >> fixes), optional extensions, and even “additional information”.
    >> >>
    >> do not, by themselves, imply a normative change to the updated RFC,
    >> nor do they, by themselves, imply that implementers must implement the
    >> should contain enough detail to help readers decide if they need to
    >> read the rest of the RFC.. The body should contain enough detail for
    >> readers to fully understand the nature of the update.
    >> >>
    >> >> The importance of including an “Updates” header depends on the
    >> nature of the update. Normative updates that do not use a known
    >> extension point should always include an “Updates” header. Extensions
    >> that do use known extension points do not typically need to include
    >> the “Updates” header, but may in cases where it’s important to make
    >> the extension known to readers of the original RFC. Other uses of
    >> “Updates” may be appropriate when it’s important for readers to know
    >> about them; for example a new RFC may expand security or operational
    >> >> RFCs that fully replace other RFCs should typically use the
    >> “Obsoletes” header rather than the “Updates” header. The “Updates”
    >> header should be used to flag updates to published RFCs; it is not
    >> appropriate to “Update” an Internet-Draft.
    >> >>
    >> >>
    >> >
    >> >
    >>

---

From: Sean Turner <[email-masked]>
Date: Wed, 12 Sep 2018 10:33:31 -0400

Thanks for taking one for the team ;). More below.

> There have been several discussions lately about the use and meaning of the “Updates” header in RFCs, and the resulting “Updates”/“Updated by” relationships. The IESG is thinking about making the f…

I like to say that I hate the whole list the reasons why in the abstract.  I understand that we also say what RFCs are updated in the abstract because there are some tools that don’t display the meta-data and that we do it so readers will know whether or not to keep reading.  That’s great for an RFC that’s updating one RFC and it keeps in line with keep the abstract succinct plus the boiler plate on the 1st page.  But, when you’ve got an RFC that’s going to update say eight (8) RFCs that this is kinda crazy.

> The importance of including an “Updates” header depends on the nature of the update. Normative updates that do not use a known extension point should always include an “Updates” header. Extensions…

I generally agree with this, but I can see the last sentence sometimes being a thing.  The example you have sounds perfectly reasonable to me, but that’s not why we need these rules ;). Some want their RFC to be “part of” the base specification, and they do it by trying to “link in” with the base specification.  Is “whether it’s import to know about” other RFCs going to become a question in the shepherd write-up or something the IESG asks during it’s evaluation?

> RFCs that fully replace other RFCs should typically use the “Obsoletes” header rather than the “Updates” header. The “Updates” header should be used to flag updates to published RFCs; it is not app…

Just checking - I seem to remember a time when there was draft (not an RFC) that “updated” another draft in the RFC editor’s queue.  I suspect the idea of pulling it back was way more painful that just doing the “updates” header.  That’s still okay right?

Finally, any thought given to going back and retroactively applying these rules to previously published RFCs’ meta-data?

spt

---

From: "Paul Hoffman" <[email-masked]>
Date: Wed, 12 Sep 2018 07:45:31 -0700

On 12 Sep 2018, at 7:33, Sean Turner wrote:

>> described in the abstract and body of the new RFC. The level of 
>> detail may differ between the abstract and the body; typically an 
>> abstract should contain enough detail to help readers decide if they 
>> need to read the rest of the RFC. The body should contain enough 
>> detail for readers to fully understand the nature of the update.
>
> I like to say that I hate the whole list the reasons why in the 
> abstract.  I understand that we also say what RFCs are updated in the 
> abstract because there are some tools that don’t display the 
> meta-data and that we do it so readers will know whether or not to 
> keep reading.  That’s great for an RFC that’s updating one RFC and 
> it keeps in line with keep the abstract succinct plus the boiler plate 
> on the 1st page.  But, when you’ve got an RFC that’s going to 
> update say eight (8) RFCs that this is kinda crazy.

Sean's exactly right here. Having to add a lot of new text to the 
abstract basically makes it a mini-introduction. Instead, please 
consider:

The specific reasons that a given RFC updates another should be 
described near the top of the Introduction section of the new RFC, 
possibly in its own sub-section. This text should contain enough detail 
to help readers who are familiar with the specification that is being 
updated to decide if they need to read the rest of this newer RFC. This 
text must contain enough detail for readers to fully understand the 
nature of the update.

--Paul Hoffman

---

From: Julian Reschke <[email-masked]>
Date: Wed, 12 Sep 2018 17:23:15 +0200

> text must contain enough detail for readers to fully understand the 

Yes.

...or maybe move that information into a later section/appendix, and 
refer to that from the introduction.

Best regards, Julian

---

From: Michael Richardson <[email-masked]>
Date: Wed, 12 Sep 2018 13:26:54 -0400

> text must contain enough detail for readers to fully understand the

well said.

---

From: Adam Roach <[email-masked]>
Date: Wed, 12 Sep 2018 13:10:18 -0500

Thanks for weighing in, Bob. I have a request for clarification.

On 9/11/18 1:31 PM, Bob Hinden wrote:
> This may result in a long Abstract depending on the nature of the “update” and defeat the purpose of the abstract if it gets too long.

Based on other people's comments, you're not alone in such a concern, 
and I'd like help understanding why. My conception of document abstracts 
in general is that they serve the singular purpose of letting people 
know whether they should read the rest of the document. This makes the 
text you quote almost tautological.

Clearly, you (and others) have a different notion of the purpose of the 
abstract section, and that understanding is driving these concerns. I 
don't think we can reach a reasonable consensus unless we surface what 
those differences in understanding are.

Can you concisely describe what purpose you believe an abstract serves?

/a

---

From: Stephen Farrell <[email-masked]>
Date: Wed, 12 Sep 2018 21:51:14 +0100

Hiya,

On 12/09/18 19:10, Adam Roach wrote:
>>     "abstract should contain enough detail to help readers decide if
>> they need to read the rest of the RFCâ€
>>
>> This may result in a long Abstract depending on the nature of the
>> â€œupdateâ€ and defeat the purpose of the abstract if it gets too long.
> 
> 

There are more than just functional properties. There's the issue of
folks having to jump through bureaucratic hoops. For some documents,
it'll be just fine if this information is somewhere other than the
abstract.

S.

---

From: Adam Roach <[email-masked]>
Date: Wed, 12 Sep 2018 16:18:28 -0500

On 9/12/18 3:51 PM, Stephen Farrell wrote:
>>> they need to read the rest of the RFC"
>>>
>>> "update" and defeat the purpose of the abstract if it gets too long.
>>

I still don't follow. If the abstract does not contain enough 
information to let someone know whether they want to read the rest of 
the RFC, then what purpose *does* it serve? I note that many (non-IETF) 
protocol specifications are published without an abstract at all. If 
ours doesn't serve any purpose, then perhaps it's time we discussed 
whether RFCs need them at all [1].

/a

____
[1] To be clear, I think this would be a Really Bad Idea, but it's the 
only logical conclusion I can draw from push-back on a proposal that our 
abstracts do the one thing that abstracts are intended to do.

---

From: Ted Lemon <[email-masked]>
Date: Wed, 12 Sep 2018 14:23:36 -0700

On Sep 12, 2018, at 2:18 PM, Adam Roach <[email-masked]> wrote:
> I still don't follow. If the abstract does not contain enough information to let someone know whether they want to read the rest of the RFC, then what purpose *does* it serve? I note that many (non-IETF) protocol specifications are published without an abstract at all. If ours doesn't serve any purpose, then perhaps it's time we discussed whether RFCs need them at all [1].

Abstracts are useful in precisely the way you suggest; the question is whether the abstract has to enumerate what the document updates.

This may not be necessary if the reader would be reading the document anyway because of the contents of the document.   So whether the abstract has to say specifically what is update is a judgment call.   Personally, I prefer to keep abstracts as short as possible—they should definitely say enough that I can decide whether I need to read them, but if they say more than that, then reading the abstract becomes enough work that it might as well just be an introduction (and indeed we often see IETF documents where the abstract and the introduction are largely the same text).

---

From: "Paul Hoffman" <[email-masked]>
Date: Wed, 12 Sep 2018 14:36:25 -0700

On 12 Sep 2018, at 14:18, Adam Roach wrote:

> the RFC, then what purpose *does* it serve?

To tell the reader if they want to read the Introduction. For example, 
it should indicate whether this is a description of the new Foo 
protocol, or an update to the Foo protocol, or just the definition of an 
extension. If it is defining a new protocol, what general realm is that 
protocol in?

> I note that many (non-IETF) protocol specifications are published 
> without an abstract at all. If ours doesn't serve any purpose, then 
> perhaps it's time we discussed whether RFCs need them at all [1].
> ____
> only logical conclusion I can draw from push-back on a proposal that 
> our abstracts do the one thing that abstracts are intended to do.

Yes, this is a bad idea, but there are needs of the reader that short 
abstracts fill just fine.

--Paul Hoffman

---

From: Stephen Farrell <[email-masked]>
Date: Wed, 12 Sep 2018 22:37:06 +0100

Hiya,

> the RFC, then what purpose *does* it serve? 

Take a peek at [1]. IMO the second para in the abstract is
neither needed nor useful. And such text has been the source
of irritation for authors (when they're called out for not
having done something they see as silly) and also (IMO)
pointless IESG debate.

So forcing that para to be there is not a good part of the
proposed IESG statement. That said, as others said, it's not
the end of the world if it stays, but better to do better
I'd argue.

S.

[1] https://tools.ietf.org/html/rfc8447

> I note that many (non-IETF)
> whether RFCs need them at all [1]

---

From: Brian E Carpenter <[email-masked]>
Date: Thu, 13 Sep 2018 10:07:46 +1200

> it'll be just fine if this information is somewhere other than the

Exactly. Common sense should apply in all cases. If the abstract is
too long or looks like a catalogue of boring stuff, it will itself
become TL;DR and therefore defeat its own purpose. So all - that's
*all* - of these guidelines should be *guidelines* that are varied
when that seems appropriate. If a document updates 8 others, then
the abstract could say: This document updates all the RFCs underlying
Foobar. Or for a current topic, perhaps: This document updates numerous
RFCs that mention the IAOC.

As Spencer says from time to time, do the right thing. When the rules
or guidelines are wrong, do the right thing.

(Possible update to RFC2119: if MUST is clearly nonsense in a particular
case, ignore it, especially in a BCP.)

   Brian

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Wed, 12 Sep 2018 15:27:08 -0700

> hear from the RFC Series Editor on this.

Ask and ye shall receive...

I agree that it is important for the same semantics to be used 
stream-wide. I think it's worth discussing, not necessarily with an eye 
towards changing what goes in this particular statement, if and how the 
terms Updates and Updated by might differ for things NOT standards track 
RFCs. These terms are used almost exclusively in the IETF stream, so 
it's realistic to expect the IETF definition to apply across the board. 
To throw some numbers in here, taking out Legacy documents, 1327 IETF 
RFCs have Updates and/or Updated by, whereas 7 IAB documents do, no IRTF 
documents do, and 20 Independent stream documents do.

I knew this was under discussion, and had sent in the RFC Editor input 
before this went out to the community. The stream managers for the other 
streams are aware of this discussion (two of them have in fact responded 
to the thread, though not necessarily with their stream manager hats on) 
so I don't think anyone will be surprised.

-Heather

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Wed, 12 Sep 2018 16:18:11 -0700

On 9/12/18 7:45 AM, Paul Hoffman wrote:
>> keep reading.  That’s great for an RFC that’s updating one RFC and it 
>> keeps in line with keep the abstract succinct plus the boiler plate 
>> on the 1st page.  But, when you’ve got an RFC that’s going to update 
>> say eight (8) RFCs that this is kinda crazy.
>
> possibly in its own sub-section. This text should contain enough 
> detail to help readers who are familiar with the specification that is 
> being updated to decide if they need to read the rest of this newer 
> RFC. This text must contain enough detail for readers to fully 
> understand the nature of the update.

I think this is a very reasonable approach. The abstract should 
definitely be succinct, and text explaining the relationship of one RFC 
to another (or set of others) should exist, too, but I see it necessary 
that it exists in the abstract itself. Put it in the introduction or put 
it in its own section if the relationships are complicated enough to 
need a roadmap of some type.

-Heather

---

From: Spencer Dawkins at IETF <[email-masked]>
Date: Wed, 12 Sep 2018 19:25:37 -0500

I have lots of opinions about things, some of which are useful, but this
isn't a topic I'm smart about, so I'm mostly following the discussion, to
help us do the right thing, whatever that turns out to be.

> need a roadmap of some type.

I think IESGs I've served on have tended to understand IESG statements as
"one size fits most". I would hope that continues for future IESGs.

I think what you're saying here, is that we should do what is helpful for
most users in most cases, recognizing that if a document (say) makes a
non-backward-compatible change that's critical for everyone to implement
right now that will Update 35 RFCs, the best we can do in an Abstract is
say that, followed by "and if you care about protocol FOO, you REALLY want
to read this document".

If I got that, you might very well be right.

Spencer

---

From: Heather Flanagan <[email-masked]>
Date: Wed, 12 Sep 2018 17:47:29 -0700

On 9/12/18 5:25 PM, Spencer Dawkins at IETF wrote:
> I have lots of opinions about things, some of which are useful, but 
> this isn't a topic I'm smart about, so I'm mostly following the 
> discussion, to help us do the right thing, whatever that turns out to be.
>
> On Wed, Sep 12, 2018 at 6:19 PM Heather Flanagan (RFC Series Editor) 
> <[email-masked] <mailto:[email-masked]>> wrote:
>
>     update
> I think IESGs I've served on have tended to understand IESG statements 
> as "one size fits most". I would hope that continues for future IESGs.
>
> I think what you're saying here, is that we should do what is helpful 
> for most users in most cases, recognizing that if a document (say) 
> makes a non-backward-compatible change that's critical for everyone to 
> implement right now that will Update 35 RFCs, the best we can do in an 
> Abstract is say that, followed by "and if you care about protocol FOO, 
> you REALLY want to read this document".
>

Basically correct. I wouldn't list the 35 RFCs in the Abstract, and I 
would prefer it if the abstract says "This RFC updates 35 other RFCs. 
Further details are in the document itself and in the document metadata."

I think we should definitely aim for "one size fits most" and recognize 
that we can and should be flexible when the unavoidable edge case shows up.

-Heather

---

From: Lars Eggert <[email-masked]>
Date: Thu, 13 Sep 2018 09:10:09 +0300

On 2018-9-11, at 21:08, Robert Sparks <[email-masked]> wrote:
> I'm in the camp that prefers the more specific "This changes the code you need to write" camp - I would prefer Update be restricted to the cases where you are changing the protocol defined in the updated document in an essential way.

+1

Lars

---

From: "Roni Even (A)" <[email-masked]>
Date: Thu, 13 Sep 2018 06:57:07 +0000

I am OK with Ben proposal.
I take the word "update" literally, and see the value of "updated by" as a forward reference for anyone who read the updated RFC .  Having "update" in an RFC provides motivation to read the updated RFC and some text about how this new RFC updates the previous one will be helpful. I understand that an RFC can have in the text a statement about updating another RFC with normative reference but it is simpler for a person that is new to a topic to see the linkage between RFCs
 
I am not worried about  implementation issues, "update" is about the content it does not require implementations.

As for  " I would prefer Update be restricted to the cases where you are changing the protocol defined in the updated document in an essential way",  I do not like the term "essential" it may open a can of worms. How do we quantify "essential".  For example a new extension may be "essential" to one usage but may not be totally useless to others. 

Roni

-----Original Message-----
From: ietf [mailto:[email-masked]] On Behalf Of Robert Sparks
Sent: Tuesday, September 11, 2018 9:09 PM
To: Ben Campbell; [email-masked]
Cc: The IESG
Subject: Re: Proposed IESG Statement on the use of the “Updates” header

RjS

---

From: Benjamin Kaduk <[email-masked]>
Date: Thu, 13 Sep 2018 08:34:11 -0500

> I'm not sure the IESG text is 100% compatible with this.

I believe it was intended to be, and I'm not sure what incompatibility you
are seeing; could you say more?

> In that case, "updates" really means "partially obsoletes". 

Is there anything stopping the body text of the document from saying "this
document updates [foo] by obsoleting the completely broken bits that do
[bar]"?

Namely, the *keyword* does not indicate that you must update
implementations.  The body text can try really hard to say that you should
do so, though.

-Ben

---

From: Brian E Carpenter <[email-masked]>
Date: Fri, 14 Sep 2018 08:59:53 +1200

Hi Ben,

> are seeing; could you say more?

There's a subtlety in this phrase:
  "would need to be updated to accommodate the extension."
Even though I'm a co-author of RFC6709, I'm not 100% sure what this means.
I think it means "if an implementor adds the extension to the code, she must
also modify the base code". The IAB text seems to be saying that if you add
a feature that does not *require* a change to the existing code, it's
not an update. I'm not sure I even agree with that, and I don't think
the IESG text does either. (If it does, we need a new tag "Extends:".)

>>> nor do they, by themselves, imply that implementers must implement the updating RFC to continue to comply with the updated one>>

Yes.

    Brian

---

From: Ben Campbell <[email-masked]>
Date: Thu, 13 Sep 2018 17:09:13 -0500

> I'm in the camp that prefers the more specific "This changes the code you need to write" camp - I would prefer Update be restricted to the cases where you are changing the protocol defined in the u…

I note that several people have agreed with this point or made similar points. I’d like to test what counts as “updating a document in an essential way”. Consider the following scenarios:

A) Critical bug fixes that impact all implementations of a protocol.
B) Critical bug fixes to an optional feature from the original RFC. It does not impact code that didn’t implement the option in the first place.
C) A modular extension that mitigates a security or network congestion issue in the base protocol. We really want people to implement it, but introduce it as a negotiated extension to avoid a fork-lift change.
D) A change to security considerations and/or operational considerations that, while not changing the protocol, significantly changes the environment it can be safely used in.
E) A modular extension that adds a new, optional feature.

Which of these needs an “Updates” header? I imagine most people agree that A does and that E does not. What about the ones in between?

> p.s. I assume you've rehashed previous IESGs discussions of adding a "See Also" relationship?

It has come up in conversation, yes :-)

Would you see a “see also” relationship as meaning “you really, really need to read this” or “this contains supplementary information”? Or something in between?

Thanks!

Ben.

---

From: Robert Sparks <[email-masked]>
Date: Thu, 13 Sep 2018 17:28:34 -0500

> Which of these needs an “Updates” header? I imagine most people agree that A does and that E does not. What about the ones in between?
Skipping this for now so I can make a quick reply to what's below.
> Would you see a “see also” relationship as meaning “you really, really need to read this” or “this contains supplementary information”? Or something in between?
I don't think I care.

I see it as an outlet to release pressure for those folks that want to 
put numbers on the first page that really should just be references with 
explanatory text making the references natural.

I might care more if we reset the conversation completely and stopped 
talking in terms of "stuff on the first page" and spoke more about 
"metadata about the documents that's curated enough for software to 
use". I think going there will be a bigger, longer, but more useful to 
the world in the long run, conversation. I suspect somewhere along that 
path, we'll be staring at yang models...

---

From: Brian E Carpenter <[email-masked]>
Date: Fri, 14 Sep 2018 12:52:51 +1200

>> D) A change to security considerations and/or operational considerations that, while not changing the protocol, significantly changes the environment it can be safely used in.

All of those, because a developer supporting an implementation of the
base protocol might need to touch their code.

>> E) A modular extension that adds a new, optional feature.>>
>> Which of these needs an “Updates” header? I imagine most people agree that A does and that E does not. 

I'm not so sure. Again, the developer might *want* to touch their code. So
absent a "See also:" or "Extends:" tag, some people might think this merits
"Updates:".

Look at RFC3461, updated by RFC8098, which clearly extends it in a fairly
explicit way. Wouldn't an implementor of  Delivery Status Notifications
want to know?

> What about the ones in between?

Maybe. But at the risk (no, certainty) of repeating myself, see draft-klensin-isdbis.

   Brian

---

From: Benjamin Kaduk <[email-masked]>
Date: Thu, 13 Sep 2018 21:27:29 -0500

> the IESG text does either. (If it does, we need a new tag "Extends:".)

Ah, I see what you mean -- thanks.  Our situation seems to be similar to
the distinction between the converse and contrapositive in logic, though --
just because an Updates header is not necessary for this reason, does not
a priori prevent an Updates header from being used for some other reason.

-Ben