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

Martin J. Dürst duerst at it.aoyama.ac.jp
Mon Feb 25 01:15:42 PST 2019


Hello Heather, Mark, others,

On 2019/02/25 07:22, Mark Nottingham 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.

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.

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

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 more work. If you're willing to give it another go, perhaps folks on ietf-and-github could help.

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.


More information about the rfc-interest mailing list