Subject: [Ietf-and-github] Doing a diff - and providing guidance on how structure files in a repo

From: Dan York <[email-masked]>
Date: Fri, 26 Oct 2018 17:45:56 +0000

Yesterday I had a question from someone new to Github (and to git) that pointed out a couple of places where we might want to provide some documentation and/or guidance.

The person had been asked to review a new *unsubmitted* version of a draft that is in a Github repo. From their perspective, all they wanted to do was get a diff of what had changed in the file since the previous version (that had been submitted). They would then provide feedback back to the authors.

This turned out to be quite challenging to do within the Github web interface - and also because of the way this particular repo was structured.

Now, I know how this *can* work.  If you use tags then you can use GH’s “Compare” tool (by just appending “/compare” to the repo’s URL, you can get something workable like:
https://github.com/danyork/draft-deploying-dnssec-crypto-algs/compare/v03...master

In that particular repo, I also have only one source file that I modify for each version. I therefore can have a commit history going back to when I initially put it in the repo.

However, in the repo the person was being asked to review:

1. Tags were not used consistently for each version. Tags had initially been used, but then with later versions the people committing did not tag the repo for new versions. There wasn’t an easy way I could figure out how to get back to the particular past version to compare (I probably could have dug through the commit history to find the specific commit for the version I thought was final for the past version… and then used /compare/ with that… but that didn’t occur to me at the time.)

2. A new file was added for each new version.  Instead of having one source file where the text was changed, the author added a new file to the repo for each version. So you had:
   draft-ietf-whatever-00.xml
   draft-ietf-whatever-01.xml
   draft-ietf-whatever-02.xml
   draft-ietf-whatever-03.xml
   …

The challenge is that “draft-ietf-whatever-03.xml” is now a completely new addition to the repo, so the /compare/ feature is not very useful because it just shows you the new file. There’s no linkage to the old file.

Now, if the author took “draft-ietf-whatever-02.xml”, renamed it to “-03” and *immediately* committed it to the repo, then you could see from that point forward any changes that were made in -03.  However, it’s more likely to me that the author would take the “-02”, rename it, make a bunch of changes, and THEN commit the “-03” to the repo.

[What I ultimately suggested to the person was to clone the repo to their local system and then just do a command-line diff between the two recent versions.  Maybe one of you all has a better suggestion?]

3. The repo only contained XML files. The repo author only included the XML source file, which does make sense. But then someone reviewing the changes has to either: A) enjoy reading through XML files; or B) use xml2rfc to process the XML file into txt so that they can read it that way.   (This is obviously less of an issue if people write drafts in Markdown, but many may still use XML (or have older drafts still in XML).)

—————————

The whole experience left me with several thoughts/suggestions:

1. it would be great if the mythical “someone” wrote up instructions or a tutorial about how to easily see a “diff” between versions using the Github web interface (IF a repo is structured in a way this will work).  Or if there are other tools / sites that can do this easier. (And if such documents are already out there, it would be great to know.)

2. Some recommendations around the best way to use tags would be useful.

3. Some recommendations around the best way to structure files in a repo would be useful. (for example, using one file versus a new one for each version)

4. Perhaps the suggestion to think about also committing txt versions to a repo to aid reviewers or others interested in the document.  (I’ve done this in my own repos so that whenever I generate new XML and TXT files from my markdown file, I can just commit them all and have them up there in the repo.)

Thoughts / comments/ feedback / better-ways-to-do-this-that-I-don’t-know-about are all welcome,
Dan

P.S. All of these suggestions require that “someone” to pull together some text in a form that could be useful. Unfortunately I don’t see myself having enough time to work on this to the level needed, although I would be willing to help.

--
Dan York
Director, Content & Web Strategy, Internet Society
[email-masked]<mailto:[email-masked]>   +1-802-735-1624
Jabber: [email-masked]<mailto:[email-masked]>  Skype: danyork   http://twitter.com/danyork

http://www.internetsociety.org/

---

From: Brian E Carpenter <[email-masked]>
Date: Sat, 27 Oct 2018 08:35:12 +1300

Dan,

> 1. it would be great if the mythical “someone” wrote up instructions or a tutorial about how to easily see a “diff” between versions using the Github web interface (IF a repo is structured in a way…

I don't think that github's rather old fashioned way of showing diffs is very helpful. IMHO, for our purposes, an 'rfcdiff' is by far the most useful format. So personally in such a case I generate a .txt file from the latest .xml, and run rfcdiff against the previous version. Some tooling to do that would be great.

   Brian

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 26 Oct 2018 21:41:39 +0200

> I don't think that github's rather old fashioned way of showing diffs is very helpful. IMHO, for our purposes, an 'rfcdiff' is by far the most useful format. So personally in such a case I generate…

Please see Martin Thomson’s template and the way we generate diffs from the README, e.g., in

https://github.com/core-wg/multipart-ct

This also works for revisions in branches.

Grüße, Carsten

---

From: Brian E Carpenter <[email-masked]>
Date: Sat, 27 Oct 2018 14:51:02 +1300

> This also works for revisions in branches.

"Compare Editor's Copy to Working Group Draft" is perfect.

However, IMHO https://github.com/martinthomson/i-d-template/blob/master/doc/SETUP.md
sets the bar quite high, especially the need to rely on cygwin for Windows users.
In my experience that is not a happy dependency.

    Brian

---

From: Carsten Bormann <[email-masked]>
Date: Sat, 27 Oct 2018 10:55:27 +0200

On Oct 27, 2018, at 03:51, Brian E Carpenter <[email-masked]> wrote:
> 
> the need to rely on cygwin for Windows users

The modern way to run open source software on a Windows laptop seems to be the “Windows subsystem for Linux” [WSL] (which really is a Linux subsystem for Windows, go figure).
I don’t have any experience with this (I stopped working with Windows in 2003), but maybe people who have Windows can share some war stories.

We could also try to find Windows ports of all tools — that’s easy for Python and Ruby, but the template is based on GNU make, which indeed seems easiest to run based on Cygwin or WSL.  Maybe “someone” should port the template to Python or Ruby (e.g., it should be “easy” to convert the Makefiles from Make to Rake, which would also get rid of the Makefile cruft)…

Grüße, Carsten

[WSL]: https://docs.microsoft.com/en-us/windows/wsl/install-win10

---

From: Spencer Dawkins at IETF <[email-masked]>
Date: Mon, 29 Oct 2018 10:41:54 -0500

Well, warning, technical insight from an AD incoming, but ...

On Sat, Oct 27, 2018 at 3:55 AM Carsten Bormann <[email-masked]> wrote:

> The modern way to run open source software on a Windows laptop seems to be
> the “Windows subsystem for Linux” [WSL] (which really is a Linux subsystem
> for Windows, go figure).
> I don’t have any experience with this (I stopped working with Windows in
> 2003), but maybe people who have Windows can share some war stories.
>

I had my USB stick IN MY HAND to set my Dell Win10 box up for dual-boot
Ubuntu about a year ago, and googled one more thing, and tripped over WSL.

WSL works well enough for me to use it to install the kramdown-rfc2329 and
XML2RFC toolsets and do my draft for PANRG, and I've done enough work to
think I'm past the biggest dumb mistakes I could make (he said
optimistically).

For anyone who's also using Win10, searching for "Linux" in the Microsoft
Store pops you up Debian, Ubuntu, two flavors of SUSE, and Kali
distributions (I use Ubuntu).

When I did my first install, there were a bunch of manual steps I had to
trace down, but the way things are now, if you can install Microsoft
Office, you can install some Linux distribution pretty much the same way.

I'm probably bringing an Ubuntu netbook to Thailand, just because it's
really cheap and I would care less if anything happened to it, but WSL is
pretty serviceable for me.

And what I'd REALLY like to do, is get a version of Linux that's stable
enough to use on my Chromebook - that's why I got one with 32 GB of memory
and 4 GB of RAM. I haven't checked in a couple of weeks, but it's not quite
there yet, last time I checked.

Maybe in Prague ...

Spencer

>
> We could also try to find Windows ports of all tools — that’s easy for
> Python and Ruby, but the template is based on GNU make, which indeed seems
> easiest to run based on Cygwin or WSL.  Maybe “someone” should port the
> template to Python or Ruby (e.g., it should be “easy” to convert the
> Makefiles from Make to Rake, which would also get rid of the Makefile
> cruft)…
>
> Grüße, Carsten
>
> _______________________________________________
> Ietf-and-github mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/ietf-and-github
>