Subject: [Edm] A modest proposal (?) for archiving code

From: Vijay Gurbani <[email-masked]>
Date: Fri, 28 Aug 2020 10:12:01 -0500

All: I proposed what I write below in the WG Chairs list; the list saw a
good amount of discussion, ranging from summary dismissal to exploring the
issue further.  One feedback from there was to engage EDM.  So here we go.

Let me provide some context below, including links to the postings on the
WG chairs list for those of you who may be interested in exploring that
discussion further.

The genesis of what I am trying to affect is simple: We produce standards
that describe protocols. As a protocol is being defined in an I-D, there
are often implementers implementing the protocol or portions of it. These
implementations are important, enough that RFC 7942 [1] recognizes the
import of these implementations and exhorts I-D authors to create
an"Implementation Section" to document these implementations. RFC 7942 also
asks I-D authors to remove this section before the I-D becomes an RFC. My
question is if there are implementations that are worthy of being mentioned
in an "Implementation Section" of a I-D, why don't we preserve these
implementations in an IETF repository and link the repository in the
RFC.This way, new implementers of the protocol can quickly bootstrap their
implementations, leading to a diversity of implementations, which can only
be good for a protocol that is trying to find its footing.

Why is this important? Simple: Reaching out to developers outside of those
of us who are already in the IETF is my biggest incentive. They are the
ultimate consumers of what we produce.

When I talk to developers at companies and students at universities, if
they have heard of IETF at all, it is mostly through knowing that
someorganization called IETF produces these things called RFCs. That's
it.Perhaps for them that is enough. And if you buy that argument, then the
corollary is that we should do everything in our power to make sure that
they have all of the information they need to implement the protocol from
the RFC itself. Consider the errata we maintain in an RFC. Imagine instead
of us providing the errata, we simply told implementers that it is out
there, go find it. The errata is important, so we list it in an RFC.When a
protocol is finding its footing, early implementations that allow other
developers to understand its behaviour and derive their own implementations
from it is also important. So why not formalize the process of archiving
implementations that are worthy of being listed as per RFC 7942?

People have pointed out that we have WG pages, Wikis, datatrackers, and
other such accoutrements for this purpose? WG pages, WG Wiki pages,
datatrackers, all make sense to you and me. Many people will like to
implement our protocols without burying themselves deep into IETF to know
the difference between a WG page and datatracker. Their visibility into the
IETF is through the RFC. So, put as much information in there that will
make a developer productive.

I don't claim that this will be easy; the length of thread discussion in
the WG chairs list indicates the passion of the participants around the
issue. However, I don't think that the issues raised are insurmountable.
The fact that an entire RFC [1] was standardizes around the issue leads
credence to the fact that it is an issue deserving some sustained attention.

My initial email that started this discussion in the WG chairs list is in
[3]. It has more information and context, including how organizations like
IEEE and ACM have dealt with similar issues.

[1] https://tools.ietf.org/html/rfc7942
[2]
https://mailarchive.ietf.org/arch/msg/wgchairs/AGHRTKsDoSF3GJVhB4K2bKYjdWU/
[3]
https://mailarchive.ietf.org/arch/msg/wgchairs/8_Or3U-Wwjw35VmLy_uTPID9sTU/

Thanks,

- vijay

---

From: Mirja Kuehlewind <[email-masked]>
Date: Mon, 31 Aug 2020 12:25:01 +0200

Hi Vijay,

Thanks for bringing this discussion to this list!

I agree with the goal to make it easier or easy for implementors to find reference implementation or any kind of existing code. However, I'm not sure if putting this information in the RFC is the right approach. As you mentioned errata below, this are actually also not part of the RFC itself but only the metadata and it depends on the page that you look at if you see them or not. That a separate problem but I just wanted to underline that putting more information in the metadata might not be the right/only solution. I guess as a first step it would be nice get a better understand about how people usually find and use RFCs and maybe also how to redirect people to the right page then.

Mirja

> On 28. Aug 2020, at 17:12, Vijay Gurbani <[email-masked]> wrote:
> 
> All: I proposed what I write below in the WG Chairs list; the list saw a good amount of discussion, ranging from summary dismissal to exploring the issue further.  One feedback from there was to engage EDM.  So here we go.
> 
> Let me provide some context below, including links to the postings on the WG chairs list for those of you who may be interested in exploring that discussion further.
> 
> The genesis of what I am trying to affect is simple: We produce standards that describe protocols. As a protocol is being defined in an I-D, there are often implementers implementing the protocol or portions of it. These implementations are important, enough that RFC 7942 [1] recognizes the import of these implementations and exhorts I-D authors to create an"Implementation Section" to document these implementations. RFC 7942 also asks I-D authors to remove this section before the I-D becomes an RFC. My question is if there are implementations that are worthy of being mentioned in an "Implementation Section" of a I-D, why don't we preserve these implementations in an IETF repository and link the repository in the RFC.This way, new implementers of the protocol can quickly bootstrap their implementations, leading to a diversity of implementations, which can only be good for a protocol that is trying to find its footing.
> 
> Why is this important? Simple: Reaching out to developers outside of those of us who are already in the IETF is my biggest incentive. They are the ultimate consumers of what we produce.
> 
> When I talk to developers at companies and students at universities, if they have heard of IETF at all, it is mostly through knowing that someorganization called IETF produces these things called RFCs. That's it.Perhaps for them that is enough. And if you buy that argument, then the corollary is that we should do everything in our power to make sure that they have all of the information they need to implement the protocol from the RFC itself. Consider the errata we maintain in an RFC. Imagine instead of us providing the errata, we simply told implementers that it is out there, go find it. The errata is important, so we list it in an RFC.When a protocol is finding its footing, early implementations that allow other developers to understand its behaviour and derive their own implementations from it is also important. So why not formalize the process of archiving implementations that are worthy of being listed as per RFC 7942?
> 
> People have pointed out that we have WG pages, Wikis, datatrackers, and other such accoutrements for this purpose? WG pages, WG Wiki pages, datatrackers, all make sense to you and me. Many people will like to implement our protocols without burying themselves deep into IETF to know the difference between a WG page and datatracker. Their visibility into the IETF is through the RFC. So, put as much information in there that will make a developer productive.
> 
> I don't claim that this will be easy; the length of thread discussion in the WG chairs list indicates the passion of the participants around the issue. However, I don't think that the issues raised are insurmountable.  The fact that an entire RFC [1] was standardizes around the issue leads credence to the fact that it is an issue deserving some sustained attention.
> 
> My initial email that started this discussion in the WG chairs list is in [3]. It has more information and context, including how organizations like IEEE and ACM have dealt with similar issues.
> 
> [2] https://mailarchive.ietf.org/arch/msg/wgchairs/AGHRTKsDoSF3GJVhB4K2bKYjdWU/
> [3] https://mailarchive.ietf.org/arch/msg/wgchairs/8_Or3U-Wwjw35VmLy_uTPID9sTU/
> 
> Thanks,
> 
> - vijay
> -- 
> Edm mailing list
> [email-masked]
> https://www.iab.org/mailman/listinfo/edm

---

From: Tommy Pauly <[email-masked]>
Date: Mon, 31 Aug 2020 14:57:51 -0700

RFC 7942 does mention the direction of adding metadata to an RFC in the tools view:

"Later, the IETF Tools may support this
   functionality, e.g., by including such a link in the HTML file of the
   document, similar to the IPR link.”

It certainly is frustrating that different views of RFCs show different metadata, but if we had more formal repositories of implementation information, I think we’d want to be able to link to them.

A step can be figuring out how it would make sense present implementer information in a standard location and format, and we can figure out how to best tie it to documents next.

Tommy

> On Aug 31, 2020, at 3:25 AM, Mirja Kuehlewind <[email-masked]> wrote:
> 
> Hi Vijay,
>