[rfc-i] [Ietf-and-github] RFC Editor & Github

Eric Rescorla ekr at rtfm.com
Fri Feb 22 07:56:06 PST 2019


Here's my writeup of my thoughts after the experiment.

We experimented with using Github for the publication of TLS 1.3.
The overall process was that Github was used primarily for feedback:

1. The RFC Editor supplied iterative versions of the XML files.
2. The draft editor put them up on Github (initially as PRs
   and later just as commits)
3. We used Github's review tool to refine proposed changes both
   from the RPC and from the editor/chairs/AD
4. The editor provided updated XML from the editor/chair/AD changes
   in three ways:
   (a) patches
   (b) new XML files
   (c) OLD/NEW format


WHAT WENT WELL
I found Github very useful for refining the precise content of what
we plan to ship. Specifically:

- The RPC makes a lot of changes in their first pass, and so
  Github reviews allowed me to individually see, accept, or reject
  each one.

- As the editor/chair/AD team made our final changes, PRs structured
  that interaction and let us only ship when we had refined text.

Having each XML revision in Github also made it possible to do
incremental diffs, which is inconvenient with the current practice
of updating the XML and TXT files on the FTP site with every revision.
In one case, it let us track down when a particular error was
introduced, which was helpful.


WHAT WENT BADLY
The initial AUTH48 version from the RFC Editor included both textual
changes and whitespace changes. This produced a very large diff which
was difficult to work with. In future, it would work better to have as
many intermediate versions of the XML file as possible (one for each
stage of the process) so that they can be individually reviewed.

Having the RPC email out new XML files and then the editor upload
them is clunky. It would work better if the RPC uploaded them directly
(probably as PRs, though this is TBD). We adopted this strategy to
minimize overhead for the RPC, but it's easy to get lost. Conversely,
having the editor mail new XML to the RPC is clunky. This would
work better if Github were the master copy, which is how we do
things in WGs.



THOUGHTS FOR FUTURE EXPERIMENTS
This was valuable for me. In previous RFCs I have done it has been
quite hard to keep track of all the changes and this was a bigger
project. As noted above, I found it very useful to be able to
individually see address each change that was made in AUTH48.
However, this hybrid approach where the editor is the interface
between the RPC and Github is awkward.

If we try this again -- and I think we should -- I think we should do
one of two things:

(a) Go full Github and use it the way WGs do.
(b) Limit the RPC's use of Github to seeing the editor comments on
    their changes.

>From the document editor perspective, (a) would be better, but it
seems like a big jump for the RPC, so we should probably look at (b).
I think the easiest way to do (b) would just be to have two repos:

(a) the master repo which is used just to integrate the RPC's changes
(b) a second repo (the editor's fork) which is used to workshop
    the changes.

Then we could treat the RPC's changes as PRs against the repo (as
I had originally intended) but they wouldn't have to deal with the
noise from the editor/chair/AD discussion.

Ben also observed that because so much of the value of the RPC-editor
Github interaction is the first set of changes from the RPC (because
that's where most of the comments need to be made) that we could
skip Github entirely for that and just do the comments in Phabricator.
That seems like yet another tool people have to learn, though, so
I tend to think we should stick with Github for that.


-Ekr


On Fri, Feb 22, 2019 at 7:53 AM Ted Lemon <mellon at fugue.com> wrote:

> On Feb 21, 2019, at 8:10 PM, Eric Rescorla <ekr at rtfm.com> wrote:
>
> On the one hand, it was quite painful.
>
>
> You’re the second person to say this, so I assume it’s true, but it’s also
> surprising.   It would be helpful if (perhaps this has already been done)
> there could be a writeup of what about the process of using github was
> painful.   We aren’t constrained to either choosing to use github or do
> nothing to improve the process, and your point about auth48 changes
> resonates for me too.   If we understood why Github didn’t make things
> better, or what things about Github made things enough worse that the
> things Github made better weren’t enough, that would be helpful.
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.rfc-editor.org/pipermail/rfc-interest/attachments/20190222/90fa04cf/attachment.html>


More information about the rfc-interest mailing list