Subject: [TOOLS-DEVELOPMENT] Draft of inline-errata SoW

From: Robert Sparks <[email-masked]>
Date: Tue, 29 Jan 2019 14:07:53 -0600

Adam's developed an initial draft for the inline-errata SoW. He started 
it as a google-doc and my initial set of feedback changes were easy 
enough to make there. Unless someone objects, I suggest we continue the 
development of this one using that tool. If you do object, for any 
reason, please let me know and I'll send a PDF while we adjust.

https://docs.google.com/document/d/1T-6eBrNPC7aIxOTChdIZE7fecbxUJ7kq-F6RhyCNUGI/edit?usp=sharing

RjS

---

From: Henrik Levkowetz <[email-masked]>
Date: Tue, 29 Jan 2019 21:11:41 +0100

> https://docs.google.com/document/d/1T-6eBrNPC7aIxOTChdIZE7fecbxUJ7kq-F6RhyCNUGI/edit?usp=sharing

Looks good as a doc, wfm.  Will have to read more thoroughly to give
feedback on the content.

Best,

	Henrik

---

From: Russ Housley <[email-masked]>
Date: Tue, 29 Jan 2019 16:01:24 -0500

I made a few edits and posted two comments in the document.

Russ

> On Jan 29, 2019, at 3:07 PM, Robert Sparks <[email-masked]> wrote:
> 
> Adam's developed an initial draft for the inline-errata SoW. He started it as a google-doc and my initial set of feedback changes were easy enough to make there. Unless someone objects, I suggest we continue the development of this one using that tool. If you do object, for any reason, please let me know and I'll send a PDF while we adjust.
>

---

From: Heather Flanagan <[email-masked]>
Date: Wed, 30 Jan 2019 09:14:38 -0800

> On Jan 29, 2019, at 12:07 PM, Robert Sparks <[email-masked]> wrote:
> 

A few comments added to the doc.

-hf

---

From: Henrik Levkowetz <[email-masked]>
Date: Wed, 30 Jan 2019 19:25:57 +0100

I've reviewed the document, fixed one typo and added supplementary text
about the python 'rfc2html' module on PyPi in one location, with an
accompanying comment.  Looks good.

	Henrik

On 2019-01-29 21:11, Henrik Levkowetz wrote:
> _______________________________________________
> TOOLS-DEVELOPMENT mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/tools-development
>

---

From: Sandy Ginoza <[email-masked]>
Date: Wed, 30 Jan 2019 18:47:30 -0800

Hi all,

I figured this comment/question would be more appropriate here rather than as feedback for the SoW.  I can’t remember if placement was decided when the IESG discussed this topic at the last IETF, so sorry if this is re-raising discussion I should already be aware of.  

The text says:

This tool will initially be used to create pages served somewhere other than the RFC Editor’s website (www.rfc-editor.org). After gaining experience and community feedback, the pages might be moved to that website. Thus, the development of the tools should assume that the way the results are deployed will change over time.

The RFC Editor has been talking about creating an experimental space on our site.  I think it’s worth considering having these annotated documents live in an experimental space on the RFC Editor site so they’re on the site from the beginning.  This seems like a perfect use for an experimental space.  Also, I believe that once these documents live somewhere, that is where users will look for them; if they become the de facto RFCs, I think we want them to be on our site. 

Thanks,
Sandy

---

From: Heather Flanagan <[email-masked]>
Date: Thu, 31 Jan 2019 09:28:16 -0800

Hi Sandy,

You know I like the idea of a sandbox space - the RFC Editor needs a better way to explore ideas in a visible way. That said, there is concern about any hint of normative-ness to the annotated docs, and hosting them on the RFC Ed website might suggest some amount of officialness. I think we can potentially mitigate that by including something in the CSS that THESE ARE NOT NORMATIVE DOCUMENTS, but other ideas are welcome.

-HEather

> On Jan 30, 2019, at 6:47 PM, Sandy Ginoza <[email-masked]> wrote:
> 
> Hi all,
> 
> This tool will initially be used to create pages served somewhere other than the RFC Editor’s website (www.rfc-editor.org <http://www.rfc-editor.org/>). After gaining experience and community feedback, the pages might be moved to that website. Thus, the development of the tools should assume that the way the results are deployed will change over time.
> 
>> On Jan 29, 2019, at 12:07 PM, Robert Sparks <[email-masked] <mailto:[email-masked]>> wrote:
>> 
>> https://docs.google.com/document/d/1T-6eBrNPC7aIxOTChdIZE7fecbxUJ7kq-F6RhyCNUGI/edit?usp=sharing <https://docs.google.com/document/d/1T-6eBrNPC7aIxOTChdIZE7fecbxUJ7kq-F6RhyCNUGI/edit?usp=sharing>
>> 
>> RjS
>>

---

From: Eric Rescorla <[email-masked]>
Date: Thu, 31 Jan 2019 11:29:03 -0800

Hmm... I'm not sure that that's quite the desirable outcome.

Let's take the example of a clear (and minor) technical error: in the body
of the text, the RFC says that we use code point X and in the IANA
considerations it says code point Y and the code point that people use is
actually "Y". So, someone files an erratum that changes the body of the
text to read Y. In this case, we absolutely do want people to think that
the annotated version is the one with normative force.

-Ekr

On Thu, Jan 31, 2019 at 9:28 AM Heather Flanagan <[email-masked]> wrote:

> Hi Sandy,
>
> You know I like the idea of a sandbox space - the RFC Editor needs a
> better way to explore ideas in a visible way. That said, there is concern
> about any hint of normative-ness to the annotated docs, and hosting them on
> the RFC Ed website might suggest some amount of officialness. I think we
> can potentially mitigate that by including something in the CSS that THESE
> ARE NOT NORMATIVE DOCUMENTS, but other ideas are welcome.
>
> -HEather
>
> I figured this comment/question would be more appropriate here rather than
> as feedback for the SoW.  I can’t remember if placement was decided when
> the IESG discussed this topic at the last IETF, so sorry if this is
> re-raising discussion I should already be aware of.
>
> The text says:
>
> This tool will initially be used to create pages served somewhere other
> than the RFC Editor’s website (www.rfc-editor.org). After gaining
> experience and community feedback, the pages might be moved to that
> website. Thus, the development of the tools should assume that the way the
> results are deployed will change over time.
>
> The RFC Editor has been talking about creating an experimental space on
> our site.  I think it’s worth considering having these annotated documents
> live in an experimental space on the RFC Editor site so they’re on the site
> from the beginning.  This seems like a perfect use for an experimental
> space.  Also, I believe that once these documents live somewhere, that is
> where users will look for them; if they become the de facto RFCs, I think
> we want them to be on our site.
>
> Thanks,
> Sandy
>
>
> Adam's developed an initial draft for the inline-errata SoW. He started it
> as a google-doc and my initial set of feedback changes were easy enough to
> make there. Unless someone objects, I suggest we continue the development
> of this one using that tool. If you do object, for any reason, please let
> me know and I'll send a PDF while we adjust.
>
>

---

From: Heather Flanagan <[email-masked]>
Date: Thu, 31 Jan 2019 12:20:12 -0800

Hi ekr, 

I understand your point, but must disagree - these documents will not be fully archived, and the verification process is outside the consensus process (which I think is important for IETF documents). 

-Heather

> On Jan 31, 2019, at 11:29 AM, Eric Rescorla <[email-masked]> wrote:
> 
> Let's take the example of a clear (and minor) technical error: in the body of the text, the RFC says that we use code point X and in the IANA considerations it says code point Y and the code point that people use is actually "Y". So, someone files an erratum that changes the body of the text to read Y. In this case, we absolutely do want people to think that the annotated version is the one with normative force. 
> 
> -Ekr
> 
> 
> On Thu, Jan 31, 2019 at 9:28 AM Heather Flanagan <[email-masked] <mailto:[email-masked]>> wrote:
> Hi Sandy,
> 
>> On Jan 30, 2019, at 6:47 PM, Sandy Ginoza <[email-masked] <mailto:[email-masked]>> wrote:
>> 
>> Hi all,
>> 
>>> [email-masked] <mailto:[email-masked]>
>>> https://www.ietf.org/mailman/listinfo/tools-development <https://www.ietf.org/mailman/listinfo/tools-development>
>>> 
>> 
>> [email-masked] <mailto:[email-masked]>
>> https://www.ietf.org/mailman/listinfo/tools-development <https://www.ietf.org/mailman/listinfo/tools-development>
> 
> [email-masked] <mailto:[email-masked]>
> https://www.ietf.org/mailman/listinfo/tools-development <https://www.ietf.org/mailman/listinfo/tools-development>

---

From: Eric Rescorla <[email-masked]>
Date: Thu, 31 Jan 2019 12:44:24 -0800

On Thu, Jan 31, 2019 at 12:20 PM Heather Flanagan <[email-masked]>
wrote:

> Hi ekr,
>
> I understand your point, but must disagree - these documents will not be
> fully archived,
>

I don't see how this is relevant. In my hypothetical, the version which is
"fully archived" is simply wrong (and in fact, self-contradictory), so it's
not sensible to talk about having normative status on that point.

and the verification process is outside the consensus process (which I
> think is important for IETF documents).
>

This seems like an interesting point, but is actually mitigated by the fact
that if the approver makes a mistake, we can change the erratum again.

Taking a step back: an RFC -- at least a protocol specification --  is a
set of instructions for how to implement a protocol. And what people need
to know is how to actually implement the protocol. And when there is a
clear error in the specification that doesn't match how the specification
is being interpreted in practice, then it isn't helpful to act as if the
error has normative force. The question is what the best interpretation of
the RFC is at a given time.

-Ekr

>> I figured this comment/question would be more appropriate here rather
>> than as feedback for the SoW.  I can’t remember if placement was decided
>> when the IESG discussed this topic at the last IETF, so sorry if this is
>> it as a google-doc and my initial set of feedback changes were easy enough
>> to make there. Unless someone objects, I suggest we continue the
>> development of this one using that tool. If you do object, for any reason,
>> please let me know and I'll send a PDF while we adjust.
>>
>>

---

From: Heather Flanagan <[email-masked]>
Date: Thu, 31 Jan 2019 15:17:58 -0800

> On Jan 31, 2019, at 12:44 PM, Eric Rescorla <[email-masked]> wrote:
> 
> 
> 
> On Thu, Jan 31, 2019 at 12:20 PM Heather Flanagan <[email-masked] <mailto:[email-masked]>> wrote:
> Hi ekr, 
> 
> I understand your point, but must disagree - these documents will not be fully archived,
> 
> I don't see how this is relevant. In my hypothetical, the version which is "fully archived" is simply wrong (and in fact, self-contradictory), so it's not sensible to talk about having normative status on that point.

It is relevant because the RFC Series is as much about archiving formally approved documents as it is making those documents available. The archived documents may include information which has proven to be wrong, but the information is not corrected until we have a new document published. 

> 
> and the verification process is outside the consensus process (which I think is important for IETF documents). 
> 
> This seems like an interesting point, but is actually mitigated by the fact that if the approver makes a mistake, we can change the erratum again.

Yes, true, but that is isn’t required to flow through any kind of consensus process. 

> 
> Taking a step back: an RFC -- at least a protocol specification --  is a set of instructions for how to implement a protocol. And what people need to know is how to actually implement the protocol. And when there is a clear error in the specification that doesn't match how the specification is being interpreted in practice, then it isn't helpful to act as if the error has normative force. The question is what the best interpretation of the RFC is at a given time.

I get that, and am very sympathetic to that point. That’s why I’m in favor of creating these annotated RFCs in the first place, as an aid to both implementers and future -bis authors. But the annotated RFCs are a moving target with an insufficient consensus process for change, making them something I’m not willing to include as an official, normative output within the RFC Series.

-Heather

> 
> -Ekr
> 
> 
> 
> -Heather
> 
>> On Jan 31, 2019, at 11:29 AM, Eric Rescorla <[email-masked] <mailto:[email-masked]>> wrote:
>>

---

From: Eric Rescorla <[email-masked]>
Date: Thu, 31 Jan 2019 17:01:42 -0800

On Thu, Jan 31, 2019 at 3:18 PM Heather Flanagan <[email-masked]> wrote:

> It is relevant because the RFC Series is as much about archiving formally
> approved documents as it is making those documents available.
>

I don't agree that it's as much about that -- though I agree it's partly
about it -- but I suppose we can leave this for another day.

The archived documents may include information which has proven to be
> wrong, but the information is not corrected until we have a new document
> published.
>

This doesn't seem entirely accurate. The information *is* corrected in that
we file errata and have them approved and available, and those errata have
wha What we're talking about now is exactly how we present those errata.

> This seems like an interesting point, but is actually mitigated by the
> fact that if the approver makes a mistake, we can change the erratum again.
>
>
>

Well, this is true, but it's also the case that these kinds of changes are
regularly made in AUTH48 without going through any kind of consensus
process, with only the IESG and the authors serving as the arbiters of
whether a change needs consensus. The level of consensus isn't materially
different just because the RFC has been published.

> I get that, and am very sympathetic to that point. That’s why I’m in favor
> of creating these annotated RFCs in the first place, as an aid to both
> implementers and future -bis authors. But the annotated RFCs are a moving
> target with an insufficient consensus process for change, making them
> something I’m not willing to include as an official, normative output
> within the RFC Series.
>

It seems to me that the questions of what has normative force is really a
question for the IETF, not the RFC Editor. The IETF (with consensus, of
course) could decide tomorrow to mint a new class of documents that had
normative force and send them through some entirely separate publication
process (Github, Web pages, engraved on the face of the moon) and they
would still have whatever normative force one ascribes to the IETF
consensus process. Of course, that's a separate question from what goes in
the RFC Series.

All in all, I think this suggests that it would be better to have this
material on the IETF site and let IETF make whatever statements it wants to
about the status of the errata.

-Ekr

>> Let's take the example of a clear (and minor) technical error: in the
>> body of the text, the RFC says that we use code point X and in the IANA