Subject: Re: Comments on draft-roach-bis-documents-00

From: Heather Flanagan <[email-masked]>
Date: Sun, 2 Jun 2019 10:59:03 -0700

Hi Adam (and everyone else who has chimed in on this document),

I have a few comments/concerns from the point of view of the RFC Editor:

*If the editors only look at changes, critical context will be missed. Part of the RFC Editor job is to ensure consistency, which means reviewing a document in the context of other items published in the series. It is unclear how we are supposed to handle a -bis document where only sections of the document are updated, potentially resulting in large questions of terminology.

* I agree with Stephen Farrel’s concern regarding giving known issues a “free pass” - republishing them without changes implies endorsement. This is a reputational problem for the series. (I do see the flip side of this, however, that significant delays in updates and overall publication of material is also a repetitional hit for the series.)

* I share John Klensin’s concern around what should happen with normative references ( "And, of course, none of that addresses the cases in which other documents exist that normatively reference the original RFC and whether they are automagically treated as referencing the replacement document (works for some types of changes that might be covered by your I-D but not others) or continuing to reference the older, now-obsoleted one.”). This will need to be handled with explicit guidance to the RFC Editor.

* How should documents that span format and style guide eras be handled? For example, if a -bis document is updating a document that was created before there were required IANA and Security Consideration sections, should those be added? If the original document was based on .nroff and not XML, how much should the RFC Editor change/update with regards to document formatting of the original text?

* My preference for all RFCs that originate from a working or research group is that the RFCs have no more than two editors, and all contributors are recorded in the contributor section. I also recognize my preference on this one is not the consensus of any document stream, and I’d rather not reopen that battle on this particular thread. That said, I am unclear on what the expectation is with regards to the author list for a -bis document. If the original authors are retained in the author list, they will be requested to respond during AUTH48. It may be simpler to move them to contributors, and have someone be assigned as an editor for the -bis document. 

* If there are verified editorial errata associated with sections that are not otherwise being changed during the -bis process, can/should they be fixed in the -bis document?

Thanks,
Heather Flanagan

---

From: Eric Rescorla <[email-masked]>
Date: Sun, 2 Jun 2019 13:02:09 -0700

On Sun, Jun 2, 2019 at 10:59 AM Heather Flanagan <[email-masked]> wrote:

> That said, I am unclear on what the expectation is with regards to the
> author list for a -bis document. If the original authors are retained in
> the author list, they will be requested to respond during AUTH48. It may be
> simpler to move them to contributors, and have someone be assigned as an
> editor for the -bis document.
>

[Extensively trimming to focus just on this point].

It seems like the easiest way to manage this particular issue is to
separate out the list of people who appear at the top (whether labelled as
author or editor) from those who are consulted for AUTH48. For any given
document, we could allow the authors and/or the WG chairs or ADs to
identify a subset of the named authors/editors to serve as point for
AUTH48. I know that this isn't traditionally what we do for RFCs, but it's
not uncommon practice in other settings; for instance, it's routine for a
subset of the authors to be responsible for producing the "camera ready"
copy of papers for conferences.

-Ekr

---

From: John C Klensin <[email-masked]>
Date: Sun, 02 Jun 2019 16:03:29 -0400

--On Sunday, June 2, 2019 10:59 -0700 Heather Flanagan
<[email-masked]> wrote:

Heather,

An observation or three (for the moment) to add you your note...

> * My preference for all RFCs that originate from a working or
> research group is that the RFCs have no more than two editors,
> and all contributors are recorded in the contributor section.
> I also recognize my preference on this one is not the
> consensus of any document stream, and I'd rather not reopen
> that battle on this particular thread. That said, I am unclear
> on what the expectation is with regards to the author list for
> a -bis document. If the original authors are retained in the
> author list, they will be requested to respond during AUTH48.
> It may be simpler to move them to contributors, and have
> someone be assigned as an editor for the -bis document. 

Current stream and other preferences aside and without
particularly wanting to reopen the battle either, a very small
number of authors was Jon Postel's preference too and his
reasoning went well beyond the AUTH48 issue.  First, if a
document really was multi-author, e.g., with different authors
writing or taking lead responsibility for different sections,
either someone needed to take responsibility for resolving any
inconsistencies (even if the RFC Editor helped to identify them)
or the real author (or functional, decision-making, editor)
would become the RFC Editor and he (and Joyce) wanted to avoid
that situation even when they had the needed technical expertise
to make the decisions.  Second, for technical publications like
those of the RFC Series, he felt it was very important to be
sure that one person, or at most a couple of people, were
responsible as contact points for discussing the ideas,
something that is largely incompatible with having to hunt up a
whole committee and start at discussion with them (although that
one author could do that if appropriate).  The latter is the
same issue that various publications who have been pressured by
their audiences to allow long lists of authors have addressed by
designating a "lead" or "corresponding" author (or,
occasionally, both).  

The issue about original authors who are included being
responsible at AUTH48 has another implication too, one that Ned
Freed and I had to address explicitly with RFCs 4288 and 4289:
in spite of the act that much of the text and even more of the
theory of those two documents reflected Postel's ideas and
contributions, there was no possible way to verify whether he
would have considered the replacement documents acceptable.  

When revising earlier documents, I've always taken the position
that original authors should be consulted about whether they
want to be part of the team producing the revision.   If the
answer is "yes" (and they agree about what they are getting
into, including AUTH48 reviews) then they should be recognized
as authors and listed appropriately unless that would make  the
author list unwieldy (for me, as for Jon, "unwieldy" starts at
four or five), in while case I've either used Contributor
sections and, when appropriate, negotiated with the RFC Editor
about including them in the AUTH48 review or have worked out
appropriate acknowledgements.  If the answer is "no", then the
answer is Contributor or Acknowledgments sections as appropriate
for the particular document.

It seems to me that this is an issue of the integrity and
consistency of the RFC Series and hence something you should be
setting policy (or at least very strong and clear guidelines)
about rather than ending up negotiating outcomes on a
per-document basis.  One might think per-stream would work, but
I think we've seen evidence of that not working well enough to
ensure consistency in practice.  If you find that the long
author lists (whether induced by revisions of existing documents
with added authors or initial submissions that want to list
entire teams), perhaps it is time to modify the formats allow
specific designation of a lead or corresponding author.

best,
    john

---

From: "Martin Thomson" <[email-masked]>
Date: Mon, 03 Jun 2019 16:01:17 +1000

On Mon, Jun 3, 2019, at 03:59, Heather Flanagan wrote:
> *If the editors only look at changes, critical context will be missed. 
> Part of the RFC Editor job is to ensure consistency, which means 
> reviewing a document in the context of other items published in the 
> series. It is unclear how we are supposed to handle a -bis document 
> where only sections of the document are updated, potentially resulting 
> in large questions of terminology.

There is a difference between concentrating on the *changes* and concentrating on the *diff*.  Heather is right in saying that a narrow focus on a diff would be inappropriate.  However, I think that it should be possible to constrain efforts to making narrowly targeted changes.  Not in general, but often enough that this proposed change is useful.

The draft says that a diff is provided.  I think that is still useful, but it might pay to further highlight the inadequacy of reviewing by diff alone.  
 
> * I share John Klensin’s concern around what should happen with 
> normative references

I confess that I don't understand this concern.  Old documents will continue to refer to the replaced document.

More interesting is where the updated document cites replaced documents.  Like errata (as below), should it be in scope to update those references?  I'd say yes, but it will require judgment.  In many cases, the updates will only have the effect of pulling in additional errata from a similar sort of -bis update, but some changes might be inadvisable.  e.g., an update from RFC 5246 to 8446 might not be appropriate.
 
> * How should documents that span format and style guide eras be 
> handled? For example, if a -bis document is updating a document that 
> was created before there were required IANA and Security Consideration 
> sections, should those be added? If the original document was based on 
> .nroff and not XML, how much should the RFC Editor change/update with 
> regards to document formatting of the original text?

I don't see a major problem here, except perhaps a purely mechanical one.  That is, it might be hard to mechanically produce a diff that makes sense.  The new document should use the current format.  That said, this is worth writing down, because this is likely to be a real problem for the foreseeable future.

> * If there are verified editorial errata associated with sections that 
> are not otherwise being changed during the -bis process, can/should 
> they be fixed in the -bis document?

Good question.  I'd say yes, even for design errata with clear outcomes.  That increases the scope of the -bis, so I would leave the final decision with the working group.  If any errata are not fixed, we might want to suggest that those are explicitly listed in the "changes" section along with Stephen's requested list of "stuff we're not fixing".

---

From: Bob Hinden <[email-masked]>
Date: Mon, 3 Jun 2019 08:30:58 -0700

Hi,

> On Jun 2, 2019, at 1:02 PM, Eric Rescorla <[email-masked]> wrote:
> 
> 
> That said, I am unclear on what the expectation is with regards to the author list for a -bis document. If the original authors are retained in the author list, they will be requested to respond during AUTH48. It may be simpler to move them to contributors, and have someone be assigned as an editor for the -bis document. 
> 
> It seems like the easiest way to manage this particular issue is to separate out the list of people who appear at the top (whether labelled as author or editor) from those who are consulted for AUTH48. For any given document, we could allow the authors and/or the WG chairs or ADs to identify a subset of the named authors/editors to serve as point for AUTH48. I know that this isn't traditionally what we do for RFCs, but it's not uncommon practice in other settings; for instance, it's routine for a subset of the authors to be responsible for producing the "camera ready" copy of papers for conferences..
> 

I think this is a very good idea.   

I have run into this a number of times where we were doing a new version of an old specification where we wanted to keep the original authors (because they were the major contributors) but they were no longer active in the IETF and didn’t want to be involved in the process.

A list of AUTH48 authors could be added to what the w.g. chairs include in their writeup to the relevant ADs when advancing the document.

I think to do this, it’s important to make an effort to contact the authors to verify this is OK with them.   That’s what I did and they were fine without being involved in the w.g. discussion and AUTH48.

Thanks,
Bob

---

From: Adam Roach <[email-masked]>
Date: Mon, 3 Jun 2019 17:34:40 -0500

> *If the editors only look at changes, critical context will be missed. Part of the RFC Editor job is to ensure consistency, which means reviewing a document in the context of other items published…

That's a reasonable point, and it's one that I would expect the 
publication arm to make its own decisions about. I would hope that the 
unchanged parts of the document would impose significantly lower 
workload than those that have been added or changed. I can't quite tell 
from your comment whether that is a bad assumption.

> * I agree with Stephen Farrel’s concern regarding giving known issues a “free pass” - republishing them without changes implies endorsement. This is a reputational problem for the series. (I do see…

Do you have thoughts about the specific proposal that such known issues 
are at least called out if they can't be fixed? There are a lot of 
documents in the series that have been published either as informational 
documents without IETF consensus, or as part of the ISE stream, that had 
known flaws in them, such that they were published with an IESG warning 
at the top about suitability of use. My proposal includes a congruent 
mechanism, intended to address the concern you describe above. Do you 
think that the proposed approach is insufficient? If so, can you think 
of anything that would be sufficient?

> * I share John Klensin’s concern around what should happen with normative references ( "And, of course, none of that addresses the cases in which other documents exist that normatively reference th…

I really admire this problem for its complexity, but observe that it 
exists for every bis document the IETF ever publishes. There was an 
earlier effort to redefine how we progress documents, which failed (as 
far as I can tell) largely because the participants in that effort got 
stuck arguing about which specific oceans to boil. I'm trying to take 
that experience into account in defining a fairly narrow scope of fixing 
one problem. I'd like to see some effort launched at some point to 
address the different problem you just described, but am extremely 
hesitant to take it on as part of this work.

> * How should documents that span format and style guide eras be handled? For example, if a -bis document is updating a document that was created before there were required IANA and Security Conside…

I would think that you have more experience with these topics than 
anyone else on this mailing list, and would love to hear your proposals. :)

> * My preference for all RFCs that originate from a working or research group is that the RFCs have no more than two editors, and all contributors are recorded in the contributor section. I also rec…

As with the normative reference question above, I believe that this is a 
separate problem that already exists with all bis documents the IETF 
publishes; and, as with that problem, I would not like to take it on as 
part of this effort.

>   * If there are verified editorial errata associated with sections that are not otherwise being changed during the -bis process, can/should they be fixed in the -bis document?

Well, that's what I propose in section 3.1 criterion 3, but I'm happy to 
hear opinions about whether that's the right thing to do.

/a