Subject: [rfc-i] acknowledging reviewers name in RFCs

From: Michael Richardson <[email-masked]>
Date: Thu, 30 May 2019 15:06:34 -0400

I wrote this back on May 8, but I don't see it in the archives via IMAP.
A recent change to spam filtering means I've fallen off many lists, so I am
reposting.   I had CC'ed this to IESG.  It seems I emailed
[email-masked], which was wrong, even though it's all hosted on ietf servers.

Benjamin wrote an email email to tools-discuss awhile ago about how to find
who did a review reminded me of some things that I'd like to have in
published RFCs. I believe that it will help with getting more non-authoring
volunteers into our process if we more publically and formally acknowledge them.

I'd like to have a standard way to show who was:
 1) WG chair and AD stick-handling of a document.
 2) Document Shepherd
 3) Area reviews, and detailed individual reviews

While many authors put many of these things into Acknowledgements, it's not
in a standard format, and it's not easily pulled out in the XML.
(Such as by Jari's scripts)

I know that overall RFC version 3 format is done in RFC7991.
I looked through 7991, wondering if there is a way to do this simply, but
my naive eyes don't see anything that can be abused or extended.
It seems like we want to have additional "author"-like sections in the
<back>.  It seems that we would need a new section equivalent to references.

But, before offering a specific solution, I'd like to find out how we would
get consensus that this is a correct thing to do.  rfc-interest is not a wG.
Yes, I can write an Internet Draft, and having a clear problem statment is
probably a good thing.
I'm not sure who would approve: would it be the IESG/GenAD?

--
Michael Richardson <[email-masked]>, Sandelman Software Works
 -= IPv6 IoT consulting =-
_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: Paul Kyzivat <[email-masked]>
Date: Thu, 30 May 2019 16:47:22 -0400

> (Such as by Jari's scripts)

Please keep in mind that some people are very concerned with being 
mentioned. If this isn't well defined they may try to game the system. 
Thoroughness of reviews varies widely. I don't know how to draw a line 
regarding what is sufficient to get a reference.

	Thanks,
	Paul

---

From: "Andrew G. Malis" <[email-masked]>
Date: Thu, 30 May 2019 17:27:37 -0400

Michael,

This sounds reasonable to me, it's useful information about an RFC's
development. And it would be less ad-hoc than the current Acknowledgements
section.

Much of this information is already in the Datatracker. Perhaps the
generation of this section can be at least partially automated by pulling
information from there?

Cheers,
Andy

---

From: Heather Flanagan <[email-masked]>
Date: Thu, 30 May 2019 15:03:04 -0700

Sent from my iPad
> On May 30, 2019, at 12:06, Michael Richardson <[email-masked]> wrote:
> 
> 

I don’t think I saw the message either. Apologies if it got lost in the swarm of spam messages that get filtered by mailman!

> I'm not sure who would approve: would it be the IESG/GenAD?

Are you thinking of something that would appear 

A) in the document
B) in the metadata for the document (so, on the info pages or in the data tracker)
C) in the index
D) All or some combination of the above
?

Is what you’re looking for already on the data tracker pages for RFCs? I know that shows things like doc shepherd, but I don’t recall if it shows GenART or SecDir reviewers.

Thanks!
Heather

---

From: Sarah B <[email-masked]>
Date: Thu, 30 May 2019 17:41:47 -0700

Hi Heather,
	I think you can get some of this info today. For example, RFC7654 is mine. When I click on it, I get the option to look at the draft. When I click on the draft, I can then click on Tracker. Once there, I can see who submitted the reviews (I see that there is a GENDIR and a SECDIR review), who the Doc Shep was, and who the responsible AD was. 

To Michaels original question, I personally don't believe we should require this information. Who reviewed a doc becomes a "what constitutes a review" discussion point, is it a long list that I as the author has to maintain? What happens if someone's name doesn't show up and we publish, but they want it included, do we generate an errata for this? etc etc. I think we all have enough to do today, including the RPC, and I don't need another mandatory section for me to have to maintain. What's wrong with the ad hoc way it is?

Thanks
Sarah

> On May 30, 2019, at 3:03 PM, Heather Flanagan <[email-masked]> wrote:
> 
> 
> 
> 
> Sent from my iPad

---

From: Michael Richardson <[email-masked]>
Date: Fri, 31 May 2019 11:06:20 -0400

> mentioned. If this isn't well defined they may try to game the
    > system. Thoroughness of reviews varies widely. I don't know how to draw a
    > line regarding what is sufficient to get a reference.

yes, I'm aware that some people really want/need that entry in
Acknowledgments.  It would be nice to have some psychological understanding
of if there are differing motivations for this, but...

Authors do this based upon a variety of criteria, and I'm not suggesting a
specific set of rules for these kinds of acknowledgements.  So it's only
really "detailed individual reviews" that are at stake here.

I care about getting the details out in a mechanical way.
I think that making it easier for an AD or WG chair to point at a list of
documents produced under the "guidance" will make it easier to get ongoing support.

---

From: Michael Richardson <[email-masked]>
Date: Fri, 31 May 2019 11:09:56 -0400

> generation of this section can be at least partially automated by pulling

That would definitely be trivial if we decided to not just accept XML to the
DT and inserted this directly.  A halfway point would be to have a way to get
the right XML out of the DT to be added by the author automatically
(#include), or via copy/paste/edit.

I hadn't really envisioned anything like the above; just that we make the
section less adhoc.  I agree that the much of the review info is already
available now.

---

From: Michael Richardson <[email-masked]>
Date: Fri, 31 May 2019 11:17:45 -0400

> D) All or some combination of the above

(D), probably not much in (C).

    > Is what you’re looking for already on the data tracker pages for RFCs?
    > I know that shows things like doc shepherd, but I don’t recall if it
    > shows GenART or SecDir reviewers.

It needs to be in the document.
The official rfc-editor (info/XYZ) pages do not contain all the DT info, and of
course, mirrors of RFCs often do not even know to point at those pages,
although we now have that URL in the abstract.

GenART and SecDIR reviews are stored on the DT, assuming that the review
uploades them that way and does it that way.  I'm not sure if the DT can
handle more than one slot.   And it doesn't cover non-directorate reviews.

It's not currently possible from the DT page for an RFC to find out who the
WG chair was when the document was published.  We keep track of who was AD
and who the Shephard was. (Often a WG chair is a shepherd, so some info is there)

---

From: Michael Richardson <[email-masked]>
Date: Fri, 31 May 2019 11:26:58 -0400

Sarah B <[email-masked]> wrote:
    > To Michaels original question, I personally don't believe we should
    > require this information.

I am not taking a stand about *requiring* any controversial information.

I'm asking, if the information is present, that it be structured to be more
easily collected.

I don't think the WG chairs, AD and public reviewers are controversial, but
I'm open to opinions about what to actually include.

    > Who reviewed a doc becomes a "what
    > constitutes a review" discussion point, is it a long list that I as the
    > author has to maintain? What happens if someone's name doesn't show up
    > and we publish, but they want it included, do we generate an errata for
    > this? etc etc. I think we all have enough to do today, including the
    > RPC, and I don't need another mandatory section for me to have to
    > maintain. What's wrong with the ad hoc way it is?

1) The question of being left out is a question that can occur right now.
   Some automation would mean not leaving out things the DT knows about,
   so that would be good.

2) right now, we don't do any kind of validation of the names.  Names can
   show up without people's permission.... I can anything I like.  I could put:

            The authors would like to thank S. Banks for an extensive review
            of the benchmarking that went into justifying this work.

in my Acknowledgements of an obscure draft in an area you don't work in, an
appeal to your authority, and unless someone thought to ask you if you did
that, you'd probably never know.  If the Acknwowledgement is structured, then
the DT could link them all together, and let you know.