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

Mark Nottingham mnot at mnot.net
Sun Feb 24 14:22:01 PST 2019

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.


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

More information about the rfc-interest mailing list