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

Heather Flanagan rse at rfc-editor.org
Sun Feb 24 15:16:02 PST 2019

> On Feb 24, 2019, at 2:22 PM, Mark Nottingham <mnot at mnot.net> wrote:
> Hi Heather,
>> On 23 Feb 2019, at 4:57 am, Heather Flanagan <rse at rfc-editor.org> 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. (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.)
> 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.

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.


More information about the rfc-interest mailing list