Subject: [Ietf-and-github] RFC Editor & Github

From: Tom Pusateri <[email-masked]>
Date: Thu, 21 Feb 2019 11:54:05 -1000

Something that has occurred recently that might be a subject for discussion here is the final editing of documents during AUTH48 stage from the RFC Editor.

We had a draft enter AUTH48 that was written using kramdown-rfc2629 in Markdown format. All of the work was done on github and the markdown version as well as the XML version was tracked during the whole process. Once the document hit AUTH48, the RFC editor starting emailing back and forth copies of proposed changes to the XML directly.

Since they started with a modified XML changing the source document from markdown to XML, we created a new document in our github repository and made our changes and resubmitted it to them only to go back to emailing copies back and forth.

One outcome of this group could incorporate the RFC Editor into the process so that we can avoid emailing versions back and forth and not have to spend a lot of time tracking changes in our source repository.

The markdown to XML source change is a separate unfortunate problem for which I don’t have a solution. I realize we can’t expect the RFC Editor to support any XML pre-processor that comes along. It makes me want to only use the same format that is supported by the RFC Editor instead of using various pre-processor tools. Is the RFC Editor open to using any pre-processors or are they only willing to use XML?

Thanks,
Tom

---

From: "Andrew G. Malis" <[email-masked]>
Date: Thu, 21 Feb 2019 17:00:35 -0500

Tom,

This is also relevant to the rfc-interest email list, and the RFC Editor
lurks there (but not, to my knowledge, on the ietf-and-github list).

Cheers,
Andy

On Thu, Feb 21, 2019 at 4:55 PM Tom Pusateri <[email-masked]> wrote:

> Something that has occurred recently that might be a subject for
> discussion here is the final editing of documents during AUTH48 stage from
> the RFC Editor.
>
> We had a draft enter AUTH48 that was written using kramdown-rfc2629 in
> Markdown format. All of the work was done on github and the markdown
> version as well as the XML version was tracked during the whole process.
> Once the document hit AUTH48, the RFC editor starting emailing back and
> forth copies of proposed changes to the XML directly.
>
> Since they started with a modified XML changing the source document from
> markdown to XML, we created a new document in our github repository and
> made our changes and resubmitted it to them only to go back to emailing
> copies back and forth.
>
> One outcome of this group could incorporate the RFC Editor into the
> process so that we can avoid emailing versions back and forth and not have
> to spend a lot of time tracking changes in our source repository.
>
> The markdown to XML source change is a separate unfortunate problem for
> which I don’t have a solution. I realize we can’t expect the RFC Editor to
> support any XML pre-processor that comes along. It makes me want to only
> use the same format that is supported by the RFC Editor instead of using
> various pre-processor tools. Is the RFC Editor open to using any
> pre-processors or are they only willing to use XML?
>
> Thanks,
> Tom
>
> _______________________________________________
> Ietf-and-github mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/ietf-and-github
>

---

From: "Andrew G. Malis" <[email-masked]>
Date: Thu, 21 Feb 2019 17:03:10 -0500

Also, in case you're not already on it, I should have included the full
email address for the rfc-interest list, as it's not at ietf.org:
[email-masked]  .

Cheers,
Andy

---

From: "Andrew G. Malis" <[email-masked]>
Date: Thu, 21 Feb 2019 17:05:01 -0500

Darn autocorrect: it's [email-masked]

---

From: Mike Bishop <[email-masked]>
Date: Thu, 21 Feb 2019 22:06:44 +0000

Ideally, I'd see AUTH48 as a PR (perhaps from a private repo). One of the things we'll need to work out is to what extent that's feasible for the RFC Editor.

Sent from Nine<http://www.9folders.com/>
________________________________
From: "Andrew G. Malis" <[email-masked]>
Sent: Thursday, February 21, 2019 2:03 PM
To: Tom Pusateri
Cc: [email-masked]
Subject: Re: [Ietf-and-github] RFC Editor & Github

Also, in case you're not already on it, I should have included the full email address for the rfc-interest list, as it's not at ietf.org<http://ietf.org>: [email-masked]<mailto:[email-masked]>  .

Cheers,
Andy

On Thu, Feb 21, 2019 at 5:00 PM Andrew G. Malis <[email-masked]<mailto:[email-masked]>> wrote:
Tom,

This is also relevant to the rfc-interest email list, and the RFC Editor lurks there (but not, to my knowledge, on the ietf-and-github list).

Cheers,
Andy

On Thu, Feb 21, 2019 at 4:55 PM Tom Pusateri <[email-masked]<mailto:[email-masked]>> wrote:
Something that has occurred recently that might be a subject for discussion here is the final editing of documents during AUTH48 stage from the RFC Editor.

Thanks,
Tom

_______________________________________________
Ietf-and-github mailing list
[email-masked]<mailto:[email-masked]>
https://www.ietf.org/mailman/listinfo/ietf-and-github

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 21 Feb 2019 23:08:22 +0100

On Feb 21, 2019, at 22:54, Tom Pusateri <[email-masked]> wrote:
> 
> The markdown to XML source change is a separate unfortunate problem for which I don’t have a solution.

That is indeed an interesting issue.

One would hope that the AUTH48 work is limited, so this is not a big problem (it has not been in the 8+ years I have been using kramdown-rfc now).

One mode of usage of kramdown-rfc2629 is that small snippets can be entered in markdown and translated to RFCXML by the tool.  That of course requires some basic proficiency in an XML editor to call an external tool.  (As in !}kramdown-rfc2629 in vim, IIRC.)
(I have even used that for collaborating on documents authored in RFCXML, but I simply don’t do that any more.)

One other useful tool here can be an upconverter, but that requires some of the markdown formatting to survive the XML editing if it is not to cause massive deltas in the source code revision control.  (I have an upconverter, but haven’t found the time or need to make that foolproof.)

> I realize we can’t expect the RFC Editor to support any XML pre-processor that comes along. It makes me want to only use the same format that is supported by the RFC Editor instead of using various pre-processor tools.

I think that the advantages of using markdown in the creation and gestation phase outweigh some small discontinuity in the AUTH48 phase.  If AUTH48 becomes massive, maybe you are doing it wrong :-)

Grüße, Carsten

---

From: Tom Pusateri <[email-masked]>
Date: Thu, 21 Feb 2019 12:09:58 -1000

> On Feb 21, 2019, at 12:06 PM, Mike Bishop <[email-masked]> wrote:
> 

It would be nice to have the changes in one place from the beginning to end (especially with regards to errata and bis documents).

And as a side benefit, I would like to have access to the XML versions of all the published documents so that external tools can be easily built for searching, categorizing, etc directly from the XML source instead of screen scraping the TXT or HTML formats. I’ve asked the RFC Editor about this in the past and they said it is something they want to do but aren’t there yet.

Tom

---

From: Tom Pusateri <[email-masked]>
Date: Thu, 21 Feb 2019 12:15:27 -1000

> On Feb 21, 2019, at 12:08 PM, Carsten Bormann <[email-masked]> wrote:
> 

The RFC Editor team is really good at their job and they seem to find things that no one else does, mostly with consistency. So the bigger the document, the more they seem to find.

The job of writing a technical document and editing one are quite different and the skill sets are also quite different so we both need each other. :)

Tom

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 21 Feb 2019 23:18:13 +0100

> It would be nice to have the changes in one place from the beginning to end (especially with regards to errata and bis documents).

That’s maybe an argument for developing the upconverter to industrial strength.
(I already need it to start with the published version for -bis documents; sometimes I’m too lazy and just rfcdiff the outputs and redo the few auth48 changes in the source though.)
Of course, one of the things that are also done when moving up to a -bis document is getting rid of the bindings to specific versions of the I-D.* references again — some of which have turned into RFCs which requires some manual editing anyway.

> And as a side benefit, I would like to have access to the XML versions of all the published documents so that external tools can be easily built 

That comes with switching to XML as the primary publishing format, no?

Grüße, Carsten

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 21 Feb 2019 23:32:19 +0100

> The RFC Editor team is really good at their job and they seem to find things that no one else does, mostly with consistency. So the bigger the document, the more they seem to find.

Certainly (and I have been on the authors’ side for documents such as RFC 3095, so I have fully experienced what you mean).

> The job of writing a technical document and editing one are quite different and the skill sets are also quite different so we both need each other. :)

Right.  I’m just wondering what the incremental benefit of integrating their work into my source code control is: I can live with the discontinuity — finding a way to avoid that would certainly be even better, but not that necessary.

Grüße, Carsten

---

From: Martin J. Dürst <[email-masked]>
Date: Fri, 22 Feb 2019 02:25:26 +0000

> Ideally, I'd see AUTH48 as a PR (perhaps from a private repo). One of the things we'll need to work out is to what extent that's feasible for the RFC Editor.

I'm of course not in any way speaking for the RFC Editor. Also, I'm 
myself still struggling with git and github, so I don't want to push 
(sic) it on anybody else.

But I think it would be highly beneficial for the RFC Editor to try to 
slowly move to (also use) git(hub). They may take quite some time 
because they have other things on their plate, and have to make sure 
they move carefully, and establish a process that works for them.

But compared to the OLD-NEW style of talking about diffs, pull requests 
are way more precise, and that's what matters for their work. If they 
can reduce the number of hickups in the back-and-forth with the editors 
in Auth48, that may help them quite a bit.

Regards,   Martin.

---

From: Martin J. Dürst <[email-masked]>
Date: Fri, 22 Feb 2019 02:31:29 +0000

On 2019/02/22 06:54, Tom Pusateri wrote:

> The markdown to XML source change is a separate unfortunate problem for which I don’t have a solution. I realize we can’t expect the RFC Editor to support any XML pre-processor that comes along.

Yes indeed.

> It makes me want to only use the same format that is supported by the RFC Editor instead of using various pre-processor tools. Is the RFC Editor open to using any pre-processors or are they only willing to use XML?

They are still working on getting everything to work with XML, and 
Unicode, and HTML and CSS and SVG.

Once they have done that, they may be willing to look at a earlier-stage 
format. Please note the singular here. That means that the IETF would 
have to be able to agree on a single format, the way we managed to agree 
on XML as the central format. That may not be impossible, but my guess 
is that it will at least take a lot of time.

Regards,   Martin.

---

From: Brian E Carpenter <[email-masked]>
Date: Fri, 22 Feb 2019 15:41:27 +1300

> are way more precise,

Really? I absolutely don't understand that assertion. 

Regards
   Brian

On 2019-02-22 15:25, Martin J. Dürst wrote:
> rfc-interest mailing list
> [email-masked]
> https://www.rfc-editor.org/mailman/listinfo/rfc-interest
> .
>

---

From: "Joel M. Halpern" <[email-masked]>
Date: Thu, 21 Feb 2019 22:03:56 -0500

The RFC Editor (more specifically the production center) already 
conducted an experiment in using github in conjunction with the editing 
process.  While I will leave it to Heather to provide details, the 
simple result was that it turned out to be VERY painful.

Please do not assume that using github / git for that part of the 
process is a trivial or easy step for us to take.

Yours,
Joel

---

From: Martin J. Dürst <[email-masked]>
Date: Fri, 22 Feb 2019 03:06:14 +0000

Hello Brian,

> Really? I absolutely don't understand that assertion.

The OLD-NEW style requires a description of location/context in natural 
language. That's imprecise. Also, to create it from an actual document 
and to apply it to an actual document requires human work. That can also 
lead to imprecision.

Of course, if you (or the RFC editor) has some tools that produce 
OLD-NEW style diff descriptions from actual document changes or the 
other way round, my argument would fall apart. I haven't heard about 
such tools, but I'm ready to be surprised.

Regards,   Martin.

---

From: Eric Rescorla <[email-masked]>
Date: Thu, 21 Feb 2019 20:10:30 -0800

> process is a trivial or easy step for us to take.

As one of the main people involved in that experiment, I have mixed feelings
about it.

On the one hand, it was quite painful. On the other hand, in many respects,
it was quite a bit easier for me than previous experiences with AUTH48
because
it made it possible to precisely localize and respond to every proposed
change.

A full analysis of the situation is certainly out of scope for this WG, but
in short,
one difficulty with the AUTH48 process is the intermixture of different
kinds of
changes, for instance:

- Boilerplate-type changes
- Reformatting
- Copy-editing
- Pagination/typesetting
- Semi-substantive changes by the AD and editors

Having to work with these all at the same time makes it quite difficult to
properly
assess and manage each change. This is the kind of thing that can be
improved
by tooling, but it also requires a certain level of discipline about
dividing up each
type of change that we didn't do in the previous github experiment, so I
think that
any future experiment would need some more planning along these lines.

-Ekr

Yours,
> >> Ideally, I'd see AUTH48 as a PR (perhaps from a private repo). One of
> the things we'll need to work out is to what extent that's feasible for the
> RFC Editor.
> >

---

From: Kent Watsen <[email-masked]>
Date: Fri, 22 Feb 2019 04:34:34 +0000

I appreciate that folks (including myself) are enthusiastic about using GitHub and Markdown, but it would be a mistake to change the publishing process to incorporate such things.   For one, it begs the question as to how many variants might be allowed (since GitHub/Markdown wouldn't ever be mandated) and, with each variant, the overhead to understand and maintain support for it.  I think the IETF rightly defines a single interface for getting work done.

Kent

> On Feb 21, 2019, at 10:03 PM, Joel M. Halpern <[email-masked]> wrote:
> 
> The RFC Editor (more specifically the production center) already conducted an experiment in using github in conjunction with the editing process.  While I will leave it to Heather to provide details, the simple result was that it turned out to be VERY painful.
> 
> Please do not assume that using github / git for that part of the process is a trivial or easy step for us to take.
> 
> Yours,
> Joel
>

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 22 Feb 2019 06:51:02 +0100

> and to apply it to an actual document requires human work. That can also 

So what?  They are not applied mindlessly.  After each round, I can go ahead and diff the updated .txt files, which is exactly what I’m doing in an AUTH48 process.

Not all changes are done in OLD/NEW format; there are also more pervasive instructions such as “Capitalize all instances of foo unless used in the English sense”.

Grüße, Carsten

---

From: Ted Lemon <[email-masked]>
Date: Fri, 22 Feb 2019 07:52:46 -0800

On Feb 21, 2019, at 8:10 PM, Eric Rescorla <[email-masked]> 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.

---

From: Eric Rescorla <[email-masked]>
Date: Fri, 22 Feb 2019 07:56:06 -0800

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 <[email-masked]> wrote:

> 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.
>
>

---

From: Bret Jordan <[email-masked]>
Date: Fri, 22 Feb 2019 10:54:10 -0700

<inline>

Thanks,
Bret
PGP Fingerprint: 63B4 FC53 680A 6B7D 1447  F2C0 74F8 ACAE 7415 0050
"Without cryptography vihv vivc ce xhrnrw, however, the only thing that can not be unscrambled is an egg."

> On Feb 21, 2019, at 7:25 PM, Martin J. Dürst <[email-masked]> wrote:
> 

I like git for source code work, but I am still having a hard time using it for document work. The number of extra steps and the learning curve can be just hard for people.  Also, the difference between authoring and editing are huge and pushing this on people that are not super familiar with Git can be a show stopper.  

The goal of this WG, IMHO, is to document how we can make this easy for people so we can get MORE people involved in reading, working on, and contributing to the work we do here in the IETF not less.  If we make a solution that drives people away, and our overall attrition rate continues to go up, then we become less and less relevant over time. 

Bret

---

From: Bret Jordan <[email-masked]>
Date: Fri, 22 Feb 2019 10:56:40 -0700

<inline>
Thanks,
Bret

> On Feb 21, 2019, at 8:03 PM, Joel M. Halpern <[email-masked]> wrote:
> 

For other SDOs that I work with, that use Git, I can attest to this and doing editorial work via Git can just be a show stopper for many.

Bret

---

From: Heather Flanagan <[email-masked]>
Date: Fri, 22 Feb 2019 09:57:58 -0800

> On Feb 22, 2019, at 7:52 AM, Ted Lemon <[email-masked]> wrote:
> 
> On Feb 21, 2019, at 8:10 PM, Eric Rescorla <[email-masked] <mailto:[email-masked]>> wrote:
> _

ekr has posted his impressions of the GitHub experiment with the RFC Editor, which I’ve seen and is useful feedback. From the point of view of the editors, however, the experience of what worked and what didn’t was somewhat different. We posted our feedback to the IESG and the tls-chairs list.

One other point - we need to continue this conversation about how to improve AUTH48 for the authors. In much the same way that when I first started, the majority of input I received was that the format was the biggest pain point that needed attention, what I’m hearing now is that AUTH48 is the next big area to target. While I'm not ready to revive the experiment given where things stand with the format work (more on that in the next few weeks) this is definitely something that I’m hearing as both urgent and important.

-Heather

—
Hi all,

This is the consolidated feedback from the RFC Editor regarding the experiment in using GitHub to process the TLS 1.3 document. Please note that this feedback focuses entirely on the GitHub experience; all comments regarding editorial changes are off topic. Also, the markdown conversation (i.e., editing in markdown, choosing a particular flavor of markdown) is also outside the scope of the experiment and this feedback.

tl;dr
GitHub did not improve anything for the RFC Editor, and seemed to replicate and over-complicate the AUTH48 process where the authors and the RPC exchange updated XML files.

What Went Well:
* The author seemed happier with the interactions with the RFC Editor.

* It was easy for the RFC Editor to download a copy of the revised XML files.

What Was Challenging:
* This was not a good choice of documents to do an experiment with; the length, criticality, and number of early questions that had to be held until AUTH48 made the overall experience more complicated than it would have been otherwise (from the RFC Editor's perspective). In particular, typically a set of questions would be sent during AUTH state (earlier in the process); for this document, all questions were held for AUTH48 state, and this added to the perceived excessive number of initial changes.

* While the discrete list in GitHub of each change seemed to make the review easier for the author, it proved to be significantly more difficult for the RPC editor. Rather than have the changes all in one place, this required a lot of clicking to each individual change to review the comments. It was very time consuming.

* Being on the "Watch" list resulted in a great deal of noise that the RPC editor had to work through. It was difficult to determine if comments and proposed changes were being directed to the RFC Editor or to the author.

* The RPC editor's AQs (Author Query) are often truncated in GitHub, which introduced some confusion on both the part of the author and the RPC editor.

* In a document that has a large number of AQs (as this one did), the GitHub UI will hide the majority of those questions, along with some of the comments from authors and other reviewers (e.g., "120 hidden conversations"); one has to manually "unhide" them, 20 at a time. This process needs to be repeated every time you leave/return to that page.

* There was definitely confusion about how the RPC editors actually edit a document reflected in a request to receive intermediate diff files that show one type of change (header changes only, whitespace changes only, editorial changes only, etc). That is not how documents are edited, and trying to do that would definitely increase the level or work required on the part of the RPC editor.

* "Reflowed" text within the XML file is a common result of making editorial changes or inserting questions into the XML file. Typically, this has not been a concern for authors or the RPC, as such changes aren't reflected in the publication output, and the only diffs reviewed are text file vs. text file. In the case of this document, when reviewing XML diffs generated by GitHub, this introduced a number of changes that were noise. In the future, one way to avoid this would be careful editing of the source file to avoid reflowing the text or inserting comments mid-paragraph; however that seems like a lot of work for little return given the purpose behind the XML file. (As an aside to this one, in the future, improved XML diffing might not display changes to reflowed text in the XML -- the xmldiff tool is under development as part of the format work.)

Proposed Changes to the next stage of the GitHub Experiment (JSEP draft)
Full detail of the process is here: https://www.rfc-editor.org/rse/wiki/doku.php?id=github_auth48_experiment <https://www.rfc-editor.org/rse/wiki/doku.php?id=github_auth48_experiment>
* change to step 5 - rather than having the RFC Editor subscribe to all notifications, have the author(s) add an @mention when the RFC Editor needs to do something. (Assuming this feature will work if the account is not actually watching the repository.)

* change to step 10- rather than the RFC Editor emailing the link to the latest XML file to the author, the RPC editor will submit it directly to GitHub.

---

From: Eric Rescorla <[email-masked]>
Date: Fri, 22 Feb 2019 10:32:42 -0800

On Fri, Feb 22, 2019 at 9:55 AM Bret Jordan <[email-masked]> wrote:

> Ideally, I'd see AUTH48 as a PR (perhaps from a private repo). One of the
> things we'll need to work out is to what extent that's feasible for the RFC
> Editor.
>
>
> I like git for source code work, but I am still having a hard time using
> it for document work. The number of extra steps and the learning curve can
> be just hard for people.  Also, the difference between authoring and
> editing are huge and pushing this on people that are not super familiar
> with Git can be a show stopper.
>
> The goal of this WG, IMHO, is to document how we can make this easy for
> people so we can get MORE people involved in reading, working on, and
> contributing to the work we do here in the IETF not less.  If we make a
> solution that drives people away, and our overall attrition rate continues
> to go up, then we become less and less relevant over time.
>

No, I don't think so. The goal of this WG is to streamline the existing
workflows that people are already using and have already determined to be
convenient for their use cases. You may think that that's less convenient,
but that's not really a discussion for the GIT WG.

-Ekr

---

From: Bret Jordan <[email-masked]>
Date: Fri, 22 Feb 2019 11:49:49 -0700

Thanks,
Bret

> No, I don't think so. The goal of this WG is to streamline the existing workflows that people are already using and have already determined to be convenient for their use cases. You may think that that's less convenient, but that's not really a discussion for the GIT WG.
> 

So we should not be looking at the collateral damage that sanctioning this work might bring?  Further, we should not be looking at how to make things easier and better for the IETF community at large?   

Keep in mind I am not against using Git or Github for SDO work.  I mentioned that in the meeting in Bangkok.  What I want to help ensure is that we do this in such a way that it makes things easier for people and does not attribute to more attrition.  

Bret

---

From: "Joel M. Halpern" <[email-masked]>
Date: Fri, 22 Feb 2019 13:52:03 -0500

Trimmed and top posted.

My understanding of the goal ws to define a set of precedure for working 
groups that wanted to use github as part of the IETF.

As such, those proedures need to work for the entire working group, not 
just for the people in the working group who live and breath github.

It is, as I understand it, about enabling another way for the IEtF to 
work well.

Yours,
Joel

On 2/22/19 1:32 PM, Eric Rescorla wrote:
...
> workflows that people are already using and have already determined to 
> be convenient for their use cases. You may think that that's less 
> convenient, but that's not really a discussion for the GIT WG.
> 
> -Ekr

---

From: Bret Jordan <[email-masked]>
Date: Fri, 22 Feb 2019 11:58:28 -0700

I fully agree Joel.

Thanks,
Bret

> On Feb 22, 2019, at 11:52 AM, Joel M. Halpern <[email-masked]> wrote:
> 
> Trimmed and top posted.
> 
> My understanding of the goal ws to define a set of precedure for working groups that wanted to use github as part of the IETF.
> 
> As such, those proedures need to work for the entire working group, not just for the people in the working group who live and breath github.
> 
> It is, as I understand it, about enabling another way for the IEtF to work well.
> 
> Yours,
> Joel
> 
> ....

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 22 Feb 2019 21:28:41 +0100

> For other SDOs that I work with, that use Git, I can attest to this and doing editorial work via Git can just be a show stopper for many.

<CS snob hat>

Maybe that’s not a bug, but a feature.

</CS snob hat>

More seriously speaking, we need to be more inclusive than that.
(Please also note that using RFCXML as our primary submit format is a much taller “you have to be this tall to ride” than requiring Git would be.)

It is almost always a bad idea to force tools on someone.
(It is, however, often beneficial for both parties when the more experienced one exerts heavy nudging.)

I would expect that a process that would have the RPC use Git would still provide a “manual” interface like the one that we use now.  Participating in the Git-based process as an author would be an option that is more natural to take for the repeat author than required of everybody.  As Ekr noted, exposing editing steps in individual commits can be highly useful — both to the authors and to chairs/shepherds/ADs/WG members watching the process.  (This would be a model where the RPC “owns” the document during AUTH48 and the authors are the reviewers and occasional PR submitters.)

(I’m using “author” here to distinguish that role from the “editor” at the RPC side; we have the strange habit of calling authors “editors” in the IETF, which I’m not trying to bring up for discussion here.)

Grüße, Carsten

---

From: Heather Flanagan <[email-masked]>
Date: Fri, 22 Feb 2019 12:53:39 -0800

> On Feb 22, 2019, at 12:28 PM, Carsten Bormann <[email-masked]> wrote:
> 

While a bit of an apples-to-oranges comparison, the point is accurate. We (the RFC Editor and the community) are depending on community authoring tools and the id2xml tool to make this easier.

> I would expect that a process that would have the RPC use Git would still provide a “manual” interface like the one that we use now.  Participating in the Git-based process as an author would be an…

Keep in mind that the more interfaces that the RPC has to maintain, the more challenging our work becomes, and the more costly in terms of time and resources to do it. It raises the level of training required to bring on new editorial staff, something that is already a known challenge given the tools and editing style the community requires. It potentially requires jumping from one style to another depending on the preference of one author to the next. 

All that said, this isn’t a “no” but it is a “costs need to be considered.” Is the community ready to pay in time/money to develop tools, and/or pay in time/money to keep the rate of publication what it is today (or allow for slower, require faster, and so on)?

> (I’m using “author” here to distinguish that role from the “editor” at the RPC side; we have the strange habit of calling authors “editors” in the IETF, which I’m not trying to bring up for discuss…

(Also not opening up the discussion, but in case it helps: You could refer to the RPC editors as copyeditors. It’s more accurate than the generic editor term.)

-Heather

---

From: Brian E Carpenter <[email-masked]>
Date: Sat, 23 Feb 2019 13:33:35 +1300

> Not all changes are done in OLD/NEW format; there are also more pervasive instructions such as “Capitalize all instances of foo unless used in the English sense”.

Yes. And a human can make an error in composing a PR or in accepting one that shouldn't be accepted.

Of course, if all the participants in an AUTH48 are happy to use PRs, or sed commands, or whatever tool they agree on, that's perfectly fine. But OLD/NEW has the advantage that no arcane knowledge is needed to use it.

    Brian

---

From: Eric Rescorla <[email-masked]>
Date: Sat, 23 Feb 2019 04:23:27 -0800

> groups that wanted to use github as part of the IETF.

Here's that the charter has to say:

"Many IETF working groups use external code repository services, primarily
GitHub, in managing their work. Individual working groups, while continuing
to operate within IETF guidelines for working group activity, have
developed their own policies and practices for how they use these services.
These policies and practices cover aspects such as: managing discussion
between working group mailing lists and GitHub issues and pull requests;
how text contributions are expected to be made; labeling and naming
conventions; maintaining readable draft snapshots; using tooling and
automation; informing participants about IETF policies; and others.

The GitHub Integration and Tooling (GIT) working group will select a set of
such practices and document policies that support those practices. The
policies will each detail how work is conducted by working groups that opt
to follow the work practice. The goal is to provide both process and
tooling support for working groups that choose to adopt the practices."

...

The documents produced by this group will not alter the Internet Standards
Process (BCP 9). They will describe how to work within it. Whether working
groups choose to use GitHub or the documented policies to support their
work will remain entirely at their discretion."

>From my perspective, there are two take-home messages from this charter.

1. The question of whether Github is good or bad for IETF work is not in
scope for this WG. The charter presumes that it's good for at least some
groups. If you think Github in general is bad, then the appropriate place
to raise that issue is somewhere else, perhaps the IETF WG.

2. The output of this WG must work reasonably well for the groups which
already use Github. Otherwise, they will simply exercise their discretion
to ignore it and continue with their current processes (as described above).

> just for the people in the working group who live and breath github.

I never said otherwise.

-Ekr

---

From: "Joel M. Halpern" <[email-masked]>
Date: Sat, 23 Feb 2019 11:52:28 -0500

I do not disagree with either of your conclusions EKR.  But I do think 
you have missed an additional point.

The procedures recommend need to be good for the IETF participants in 
the working groups that choose to use them.  As a simple example, any 
procedure which does not include email confirmation of decisions would 
not pas the second condition of the charter.

I am not asserting that anyone is trying to make such changes.  But your 
chacterization seemed to miss that aspect.  Which is why we all worked 
so hard to find charter wording that addressed everyone's concerns.

Yours,
Joel

On 2/23/19 7:23 AM, Eric Rescorla wrote:
> Fri, Feb 22, 2019 at 10:52 AM Joel M. Halpern <[email-masked] 
> <mailto:[email-masked]>> wrote:
> 
>     Trimmed and top posted.
> 
> "Many IETF working groups use external code repository services, 
> primarily GitHub, in managing their work. Individual working groups, 
> while continuing to operate within IETF guidelines for working group 
> activity, have developed their own policies and practices for how they 
> use these services. These policies and practices cover aspects such as: 
> managing discussion between working group mailing lists and GitHub 
> issues and pull requests; how text contributions are expected to be 
> made; labeling and naming conventions; maintaining readable draft 
> snapshots; using tooling and automation; informing participants about 
> IETF policies; and others.
> 
> The GitHub Integration and Tooling (GIT) working group will select a set 
> of such practices and document policies that support those practices. 
> The policies will each detail how work is conducted by working groups 
> that opt to follow the work practice. The goal is to provide both 
> process and tooling support for working groups that choose to adopt the 
> practices."
> 
> ...
> 
> The documents produced by this group will not alter the Internet 
> Standards Process (BCP 9). They will describe how to work within it. 
> Whether working groups choose to use GitHub or the documented policies 
> to support their work will remain entirely at their discretion."
> 
> 
> groups. If you think Github in general is bad, then the appropriate 
> place to raise that issue is somewhere else, perhaps the IETF WG.
> 
> already use Github. Otherwise, they will simply exercise their 
> discretion to ignore it and continue with their current processes (as 
> described above).
> 
>

---

From: Benjamin Kaduk <[email-masked]>
Date: Sat, 23 Feb 2019 16:21:21 -0600

> ekr has posted his impressions of the GitHub experiment with the RFC Editor, which I’ve seen and is useful feedback. From the point of view of the editors, however, the experience of what worked an…

I was also paying close attention to that experiment, and from what I saw
it definitely seemed like the high-volume stream of github notifications
was somewhere near overwhelming for the RPC staff that were on the
receiving end.  The internal discussions amongst authors, chairs, and AD
were all going into that email stream, and it became hard to tell when an
issue was resolved, and what the resolution was (at least some of the
time).

So I'm not terribly gung-ho about bringing the copyeditors directly into a
github workflow unless they have other reasons to be working with git
and/or pull requests, since the added burden doesn't give them particularly
great benefits in return.

That said, github can still provide great value during AUTH48 to the
authors/chairs/ADs that are used to it, for their internal discussions.  I
think we just saw that for draft-ietf-acme-acme (I saw the emails go by but
didn't get to actually look at the pull requests), but it seemed to be
preserving the benefits of the github workflow without drowning the
copyeditors in notifications.

> One other point - we need to continue this conversation about how to improve AUTH48 for the authors. In much the same way that when I first started, the majority of input I received was that the fo…

Thank you for hearing this and reporting back.

-Ben

---

From: Ted Lemon <[email-masked]>
Date: Sun, 24 Feb 2019 11:42:11 -0500

So the theme I’m hearing here is that the github problem tracking tools suck for RFC editing, which is no surprise to me.   Am I hearing that correctly?   What about the actual revision control system?   Was that a problem, or was it the other stuff that didn’t work?

---

From: Phillip Hallam-Baker <[email-masked]>
Date: Sun, 24 Feb 2019 14:02:39 -0500

If people want to continue to revise an RFC after it has been submitted,
the correct way to go about it is to take the XML2RFC of the RFC and
convert it to whatever tool you want to use. I do have such a tool and it
supports Markdown, HTML, XML2RFC and Microsoft Word.

The reason the tool isn't yet available is because 1) I have been waiting
for the new RFC format to be supported, 2) I have been finishing the design
of my Mathematical Mesh project and 3) I have spent much of the past 18
months chasing a bunch of very very stupid criminals round the net who
constantly advertise their next action on Twitter, Instagram, Facebook etc.

I use Github for my code. As with much else from Linux world, it is a tool
that demands that people adopt the same mental model as the original
designer. Since I find that mental model to be confused, arbitrary and
arcane, I refuse to do that and only make use of the simplest features
because after over forty years of working with computer systems my
experience tells me that I will not see any return on the time investment
required to learn it.

Trying to make Git do what it is supposed to is painful. Trying to adopt it
to other purposes is going to be an exercise in sadomasochism.

Take the term 'pull request'. What is that supposed to be? The only way I
can interpret the term is that it is a request that I make to access the
code in the repository. Obviously it is not that but what it is, I forget
shortly after being told.

---

From: Ted Lemon <[email-masked]>
Date: Sun, 24 Feb 2019 14:27:07 -0500

On Feb 24, 2019, at 2:02 PM, Phillip Hallam-Baker <[email-masked]> wrote:
> Take the term 'pull request'. What is that supposed to be? The only way I can interpret the term is that it is a request that I make to access the code in the repository. Obviously it is not that but what it is, I forget shortly after being told.

It’s an automatically-generated patch.

---

From: Hector Santos <[email-masked]>
Date: Sun, 24 Feb 2019 15:09:03 -0500

> It’s an automatically-generated patch.

I am still on CVS for products vcs. I did do a small exploration and 
migration to SVN, even played with Google Projects at time, but for 
the last few years exploring Git/Hub as I considered the final years 
of my extensive software development years and moving stuff to GitHub. 
Why?  Because that's where the "Kids" (and VCs) are at today.

I am with Phillip, its an odd idea.   I found SVN easier from a CLI 
terminology standpoint.  GIT doesn't even have a common sense "list" 
CLI command.

I am not posting to argue/debate about the Git tool under 
consideration. A CVS should be part of the SUBMISSION process which it 
is already, technically, because you can see the diffs when you submit 
new drafts.

But why do authors need to consider GIT for their IETF I-D work?  It 
is an another learning curve and if you are not using it yet, its not 
a piece of cake at the CLI level.  The presumption for ease of usage 
would be a GUI, i.e. http://GitHub.Com

Anyway, more importantly, for submitting I-Ds, when it is not yet, if 
ever, part of a WG consideration,  do I need to use GIT (locally) in 
anticipation that it might be part of a WG and I can then "Git Push" 
to github?

Personally, today,  it should all be interactive and online using an 
IETF HTML5-based GUI Editor & Outliner for I-D creation and submission 
with automated backend diff/git maintenance. That would be great tool 
for the future of the IETF recruitment of new participanting engineers 
world wide and also promoting the usage of IETF style technical 
specifications for documenting new Internet Methods.

-- 
HLS

---

From: Carsten Bormann <[email-masked]>
Date: Sun, 24 Feb 2019 21:47:52 +0100

> It’s an automatically-generated patch.

And “pull request” is a github term, not a git term, and a very inaccurate one.  The github clone gitlab uses a saner term, “merge request” (as in requesting the curator of the main line to merge the offered patch into mainline).

I wouldn’t think to defend the arcana of git (*).  This could have been done much better, but it wasn’t.  But then, I’m not going to defend the arcana of the English language, either.  

I need to know both English and git to be a functioning member of the professional environment I’m part of.  

To the people who use contempt to rationalize their bad decisions about not learning essentials:  Get over it, and also please stop canvassing for foolishness.

But this is off-topic.  

I find the diagnosis plausible that it is much more beneficial for the RPC to use git than to use the non-git github functions.  Maybe we can re-evaluate the experiment under this lens.

Grüße, Carsten

(Well, OK, I refused to learn TeX mainly because I know how much better it could have been done, so I’m a member of that foolishness club, too.  But at least I’m not asking others to join.)

(*) https://xkcd.com/1597/ was mentioned — but please remember that this web comic is humor, which benefits from comic exaggeration.

---

From: Ted Lemon <[email-masked]>
Date: Sun, 24 Feb 2019 15:58:30 -0500

Well, indeed, I’ve worked both with Atlassian’s bitbucket product and with github, and the way that atlassian handles merges is highly preferable, despite that they also call them pull requests.   Unfortunately Atlassian is not free, but it’s also not very expensive.   Possibly there is an open source alternative that’s similarly good—I just don’t know the market well enough to be able to say.

---

From: Eric Rescorla <[email-masked]>
Date: Sun, 24 Feb 2019 14:15:14 -0800

On Sun, Feb 24, 2019 at 8:42 AM Ted Lemon <[email-masked]> wrote:

> So the theme I’m hearing here is that the github problem tracking tools
> suck for RFC editing, which is no surprise to me.   Am I hearing that
> correctly?

Perhaps. The premise behind this WG (and I think experience) is that at
least for some WGs, the Github tools are pretty good -- or at least better
than what people were using before -- for developing the IDs that are the
input for RFCs. I recognize that there are people who don't seem to feel
that way, but I don't think that that's useful to debate here.

As a number of people have noted, I don't think the way we used Github for
the final copy-editing and typesetting phase of the RFCs worked that well
the one time we tried it. From my perspective, there were a number of
problems there, but the main one was intermixing copy-editing changes
(initiated by the RPC) with substantive changes (initiated by the author,
WG chairs, and ADs). The result was that the RPC was exposed to a lot of
churn as we worked through those issues. With that said, I did find that
having a tool which allowed one to track every change initiated by RPC and
respond to it was very helpful. At present, we do this by using two tools
together (diffs plus NEW/OLD), but this is a fairly clumsy system compared
to a tool like Pull Requests, let alone a top-tier tool like Phabricator.
As an analogy, open source projects used to mostly do code review by
examining diffs and then commenting on them, and most systems have now
moved to integrated diff and review tools instead.

-Ekr

 What about the actual revision control system?   Was that a problem, or
> was it the other stuff that didn’t work?
>

---

From: Mark Nottingham <[email-masked]>
Date: Mon, 25 Feb 2019 09:22:01 +1100

Hi Heather,

> On 23 Feb 2019, at 4:57 am, Heather Flanagan <[email-masked]> wrote:
...
> * "Reflowed" text within the XML file is a common result of making editorial changes or inserting questions into the XML file. Typically, this has not been a concern for authors or the RPC, as such…

This makes me wonder if the experiment was viewed as unsuccessful because we only partially adopting the GitHub(+) toolchain.

For example, no one keeps issues on their code (or specs) in GitHub by putting comments in the source; they open issues for them. Adopting GitHub issues as a way to ask the authors questions would avoid the associated reflows.

Many projects use CI to assure that changes adhere to a chosen style, so that whitespace and similar formatting changes don't cause unnecessary diffs.

It seems to me that to be successful, we need to design a *new* workflow that's appropriate to the (proposed) tools, rather than try to graft the old one onto the new tools. Of course, that's a lot more work. If you're willing to give it another go, perhaps folks on ietf-and-github could help.

Cheers,

--
Mark Nottingham   https://www.mnot.net/

---

From: Heather Flanagan <[email-masked]>
Date: Sun, 24 Feb 2019 15:16:02 -0800

> On Feb 24, 2019, at 2:22 PM, Mark Nottingham <[email-masked]> wrote:
> 
> Hi Heather,
> 

I do think we need to give this another go, though not right now. One of my biggest concerns is that we (the RFC Editor) could end up with multiple paths for AUTH48. Not everyone (either at the individual or working group level) will want to use GitHub, and we could end up in a position where we are either a) duplicating significant effort, b) disaccommodating a significant number of authors, and/or c) becoming a GitHub help desk for those authors that are not familiar with GitHub.

I have a few other ideas percolating that I’m testing out with another organization (so, not wearing my RSE hat) that may end up being useful here. The premise there is a wiki-style front end for edits and a GitHub back end to store all the changes (and mirror any GitHub changes back into the wiki). No idea yet if that idea will fly.

-Heather

---

From: Mark Nottingham <[email-masked]>
Date: Mon, 25 Feb 2019 10:19:31 +1100

> On 25 Feb 2019, at 10:16 am, Heather Flanagan <[email-masked]> wrote:
> 

That sounds like a very reasonable concern.

> I have a few other ideas percolating that I’m testing out with another organization (so, not wearing my RSE hat) that may end up being useful here. The premise there is a wiki-style front end for e…

Ooh, that sounds interesting!

FWIW Github wikis are backed by git -- although they may not do what you want to do (since their source is markdown). See "Clone this wiki locally", e.g., on :
  https://github.com/httpwg/wiki/wiki

Cheers,

---

From: Eric Rescorla <[email-masked]>
Date: Sun, 24 Feb 2019 16:30:25 -0800

On Sun, Feb 24, 2019 at 3:19 PM Mark Nottingham <[email-masked]> wrote:

> > I do think we need to give this another go, though not right now. One of
> my biggest concerns is that we (the RFC Editor) could end up with multiple
> paths for AUTH48. Not everyone (either at the individual or working group
> level) will want to use GitHub, and we could end up in a position where we
> are either a) duplicating significant effort, b) disaccommodating a
> significant number of authors, and/or c) becoming a GitHub help desk for
> those authors that are not familiar with GitHub.
>
> > I have a few other ideas percolating that I’m testing out with another
> organization (so, not wearing my RSE hat) that may end up being useful
> here. The premise there is a wiki-style front end for edits and a GitHub
> back end to store all the changes (and mirror any GitHub changes back into
> the wiki). No idea yet if that idea will fly.
>

I'd have to see this, but one thing that I think is very important is to be
able to see precisely what changes are under consideration, and wikis
aren't necessarily that great about that.

-Ekr

> FWIW Github wikis are backed by git -- although they may not do what you
> want to do (since their source is markdown). See "Clone this wiki locally",
> e.g., on :

---

From: Heather Flanagan <[email-masked]>
Date: Sun, 24 Feb 2019 17:30:15 -0800

> On Feb 24, 2019, at 16:30, Eric Rescorla <[email-masked]> wrote:
> 
> 
> 
> I'd have to see this, but one thing that I think is very important is to be able to see precisely what changes are under consideration, and wikis aren't necessarily that great about that.

Absolutely agree. If I can’t get that, it really has limited utility. But, if it’s doing some intelligent, user friendly front ending for GitHub, the changes would be fairly easily seen in the repository. I think. If it works. 

There are many reasons I’m looking into this in a smaller environment with fewer existing constraints. If it works like I’m hoping, I’ll let this group know.

-Heather

---

From: Eric Rescorla <[email-masked]>
Date: Sun, 24 Feb 2019 17:33:14 -0800

On Sun, Feb 24, 2019 at 5:30 PM Heather Flanagan <[email-masked]> wrote:

>> > I do think we need to give this another go, though not right now. One
>> of my biggest concerns is that we (the RFC Editor) could end up with
>> multiple paths for AUTH48. Not everyone (either at the individual or
>> working group level) will want to use GitHub, and we could end up in a
>> position where we are either a) duplicating significant effort, b)
>> disaccommodating a significant number of authors, and/or c) becoming a
>> GitHub help desk for those authors that are not familiar with GitHub.
>>
> I'd have to see this, but one thing that I think is very important is to
> be able to see precisely what changes are under consideration, and wikis
> Absolutely agree. If I can’t get that, it really has limited utility. But,
> if it’s doing some intelligent, user friendly front ending for GitHub, the
> changes would be fairly easily seen in the repository. I think. If it
> works.
>

Hmm... The critical point is *proposed* changes, not change history. I
don't think Github's wiki provides a review tool, for instance.

-Ekr

> There are many reasons I’m looking into this in a smaller environment with
> fewer existing constraints. If it works like I’m hoping, I’ll let this
> group know.
>
> -Heather
>
>
> -Ekr
>
>>

---

From: Benjamin Kaduk <[email-masked]>
Date: Sun, 24 Feb 2019 22:09:55 -0600

> Perhaps. The premise behind this WG (and I think experience) is that at

I can't answer Ted's question because I'm not sure I'm interpreting it
properly.  Are the "github problem tracking tools" supposed to be "github
issues", "github pull requests", both, or neither?  (We did use pull
requests during the aforementioned experiment, but I would describe that as
just being an easy way to get a webpage that we can attach comments to and
not a normal github pull request workflow.

> that way, but I don't think that that's useful to debate here.

I agree -- I think the premise here is that we assume as a precondition
that there is some WG for which github is a useful way to work on I-Ds, and
we ignore the other WGs.

-Ben

---

From: Ted Lemon <[email-masked]>
Date: Sun, 24 Feb 2019 23:25:27 -0500

I’m mostly whining about the issue tracker, which I don’t find all that useful.   It’s better than nothing, but easy to understand why it didn’t fit into the RFC editor workflow. We haven’t actually used the github pull request workflow in the documents I’ve edited.   If it’s similar to the atlassian workflow, it’s possible that it’s perfectly fine and I should shut up. :)

---

From: Martin J. Dürst <[email-masked]>
Date: Mon, 25 Feb 2019 09:15:42 +0000

Hello Heather, Mark, others,

On 2019/02/25 07:22, Mark Nottingham wrote:
>> * "Reflowed" text within the XML file is a common result of making editorial changes or inserting questions into the XML file. Typically, this has not been a concern for authors or the RPC, as such changes aren't reflected in the publication output, and the only diffs reviewed are text file vs. text file. In the case of this document, when reviewing XML diffs generated by GitHub, this introduced a number of changes that were noise. In the future, one way to avoid this would be careful editing of the source file to avoid reflowing the text or inserting comments mid-paragraph; however that seems like a lot of work for little return given the purpose behind the XML file.

Not reflowing documents on a whim would make a lot of sense. O the other 
hand, I totally agree that being extremely careful to never ever 
introduce any kind of format change would be useless overkill. See more 
below.

> (As an aside to this one, in the future, improved XML diffing might not display changes to reflowed text in the XML -- the xmldiff tool is under development as part of the format work.)

Such XML diffing tools already exist, but some of them may cost money or 
may not do exactly what we want.

> Many projects use CI to assure that changes adhere to a chosen style, so that whitespace and similar formatting changes don't cause unnecessary diffs.

I think this is an issue that should be looked in independently of 
github, in the context of moving to XML as the core format.

I think adapting an IETF-wide style for formatting/indenting XML would 
be very tough.

So I think the RFC Production Center should be able to work with various 
different styles, which means that they have to use tools that do not 
reflow everything. I think it's totally okay if a line or two, or a 
paragraph, around the edits they do get reflowed, but anything more just 
obscures the actual changes.

But that then also would mean that editors and authors do not use tools 
that reflow everything. Even if they work hard to keep the style while 
writing a document, once it's in the hands of the RFC Editor, they 
should make sure they stop enforcing that for changes from the RFC Editor.

> It seems to me that to be successful, we need to design a *new* workflow that's appropriate to the (proposed) tools, rather than try to graft the old one onto the new tools. Of course, that's a lot…

Yes indeed. git (and also github, but less so) is so flexible that it 
allows for many different workflows. Each WG that uses github so far had 
to figure out how to do that; the current WG is (at least in part) about 
making that easier for future WGs.

Regards,   Martin.

---

From: Phillip Hallam-Baker <[email-masked]>
Date: Mon, 25 Feb 2019 10:18:12 -0500

What worries me about the Github workflow is that it is really really easy
to respond to an email. Learning how to use a tool that was not well
thought out in the first place for a purpose it was not intended to serve
is not easy.

My experience of the OpenPGP working group was that the contributions were
quickly reduced to the set of people who were familiar with Git and that
set of people wasn't enough to sustain the group.

Workflow tools are great. We can surely do better than email for workflow.
But if people want to use Github, They have to be prepared to at the very
least write up a description of how to use it.

On Sun, Feb 24, 2019 at 11:25 PM Ted Lemon <[email-masked]> wrote:

> I’m mostly whining about the issue tracker, which I don’t find all that
> useful.   It’s better than nothing, but easy to understand why it didn’t
> fit into the RFC editor workflow. We haven’t actually used the github pull
> request workflow in the documents I’ve edited.   If it’s similar to the
> atlassian workflow, it’s possible that it’s perfectly fine and I should
> shut up. :)
>

---

From: Benjamin Kaduk <[email-masked]>
Date: Mon, 25 Feb 2019 09:20:32 -0600

> least write up a description of how to use it.

And thus, here we are, with a WG chartered to write up a description of how
to use it.

Maybe we should switch gears and focus on working on that...

-Ben

---

From: Eric Rescorla <[email-masked]>
Date: Mon, 25 Feb 2019 09:02:18 -0800

> thought out in the first place for a purpose it was not intended to serve

Note that you can actually respond to Github comments in email.

-Ekr

---

From: Phillip Hallam-Baker <[email-masked]>
Date: Mon, 25 Feb 2019 15:43:16 -0500

On Mon, Feb 25, 2019 at 12:02 PM Eric Rescorla <[email-masked]> wrote:

>
>
> On Mon, Feb 25, 2019 at 7:18 AM Phillip Hallam-Baker <
> [email-masked]> wrote:
>
>> What worries me about the Github workflow is that it is really really
>> easy to respond to an email. Learning how to use a tool that was not well

Which I did and the response was 'make a pluto requerst' or something.

The problem was a bit more than that. The conversation ended up fragmented
across the two systems. So what was supposed to help the process meant that
the discussion and the process went out of sync.

---

From: heather flanagan <[email-masked]>
Date: Mon, 25 Feb 2019 12:47:35 -0800

> On Feb 25, 2019, at 7:20 AM, Benjamin Kaduk <[email-masked]> wrote:
> 
> Maybe we should switch gears and focus on working on that…

I think that’s a good plan (and will remove rfc-interest from additional discussion; it was good to include that list initially, but I think the focus needs to shift to the ietf-and-github list). I’ll be subscribing to the ietf-and-github list shortly, and encourage others to do so as well if they are curious/interested in how GitHub might impact future workflow for IETF working groups.

I’ve moved rfc-interest to bcc.

-Heather

---

From: Eric Rescorla <[email-masked]>
Date: Mon, 25 Feb 2019 12:55:10 -0800

> Which I did and the response was 'make a pluto requerst' or something.

I don't know what you did, but I regularly respond to comments via e-mail
and it works fine; the email gets incorporated into the thread.

-Ekr

---

From: Mark Nottingham <[email-masked]>
Date: Tue, 26 Feb 2019 09:55:15 +1100

> On 25 Feb 2019, at 8:15 pm, Martin J. Dürst <[email-masked]> wrote:
> 

Perhaps, but where XML hits a GitHub workflow (or any other context where non-specialist tools like diff are used), we'd benefit from some documented conventions that authors can choose (or not) to adopt.

Often, these can be imposed by the CI toolchain, and/or editors, e.g.:
  https://editorconfig.org

Cheers,

---

From: Martin J. Dürst <[email-masked]>
Date: Tue, 26 Feb 2019 01:20:35 +0000

Hello Mark,

> Perhaps, but where XML hits a GitHub workflow (or any other context where non-specialist tools like diff are used), we'd benefit from some documented conventions that authors can choose (or not) to…

This helps as long as people editing XML documents with different 
formatting conventions don't reflow the whole document.

> Often, these can be imposed by the CI toolchain, and/or editors, e.g.:

Would you care to propose a .editorconfig file for xml2rfc? Or even 
better, can the RFC Editor/Production Center describe the conventions 
they are using? Maybe the creation of such a file (and/or the 
description of the conventions in prose) can be part of the outcome of 
this WG.

But as I have stated earlier in this thread, I'm still skeptical, 
because the IETF is large, and it's minor issues such as indenting 
conventions that easily can lead to huge discussions without conclusions 
(except to agree to disagree).

Regards,   Martin.

---

From: Bret Jordan <[email-masked]>
Date: Mon, 25 Feb 2019 19:19:30 -0700

> I have a few other ideas percolating that I’m testing out with another organization (so, not wearing my RSE hat) that may end > up being useful here. The premise there is a wiki-style front end for edits and a GitHub back end to store all the changes (and > mirror any GitHub changes back into the wiki). No idea yet if that idea will fly.

This is what I brought up a few weeks back.  The ideal solution IMHO would be something like Google Docs that everyone could easily comment and provide suggestions in via a browser, where every comment and suggestion was backed by a git transaction.  The document itself would also be in Git, just rendered in something like Google Docs.  

This would allow some very interesting and easy work.

Bret

---

From: Bret Jordan <[email-masked]>
Date: Mon, 25 Feb 2019 19:24:56 -0700

Thanks,
Bret

> On Feb 25, 2019, at 1:43 PM, Phillip Hallam-Baker <[email-masked]> wrote:
> 
> 
> 
> On Mon, Feb 25, 2019 at 12:02 PM Eric Rescorla <[email-masked] <mailto:[email-masked]>> wrote:
> 
> 
> On Mon, Feb 25, 2019 at 7:18 AM Phillip Hallam-Baker <[email-masked] <mailto:[email-masked]>> wrote:
> What worries me about the Github workflow is that it is really really easy to respond to an email. Learning how to use a tool that was not well thought out in the first place for a purpose it was not intended to serve is not easy. 
> 
> The problem was a bit more than that. The conversation ended up fragmented across the two systems. So what was supposed to help the process meant that the discussion and the process went out of sync.

I have seen this as well.  You start getting the conversation taking places all over the place.

Bret