workflow for reviewing changes

[btel]

IMHO there is one advantage of using "Track changes" in WYSYWIG software over the version control systems - it allows to review (accept or reject) manuscript changes at a single change level. This is very useful when several authors work on the same manuscript and need to review each others changes.

Although in theory it is possible to accept/reject individual changes using git and similar VCS (through diff and its derivatives) in practice word-based diffs (such as wdiff) are still in their infancy and give very unpredictable results. In addition, although diff interfaces allowing to accept reject individual lines are quite common (vimdiff, kompare etc.), interfaces for word-based diffs are rare or non-existent.

Of course, one could always do a single commit per change, but this is inpractical for most real-world problems.

Systems such as Authorea, Google Docs or Etherpad can ease collaborative editing, but they require that one stays always online. And how many of us finish the drafts on the train or plane? Some of them offer possibilities to work offline (even with git working copy like in Authorea), but in practice configuring and using this functionality is a nightmare.

To sum up, I haven't yet found any reasonable system for tracking and reviewing changes using VCS. For the time being, I depend on latexrtf and "Track changes" of OpenOffice (which requires to integrate the changes back by hand, but this is a smallish price for being able to connect to all co-authors).

[wking]

On Wed, Feb 10, 2016 at 01:12:30PM -0800, Bartosz Telenczuk wrote:

Of course, one could always do a single commit per change, but this is inpractical for most real-world problems.

I think it is possible ;). If nothing else, breaking the changes up into per-paragraph (or whatever) chunks (e.g. 1 in swcarpentry/git-novice#229) makes it easy for the maintainer to say “actually, I liked the paragraph the way it was, so I'm cherry-picking the other commits but not that one” or “that's close, but how about rerolling your commit to use $ALTERNATIVE_WORDING?”. Part of the workflow issue is figuring out how finely grained the maintainer's rejection threshold is, and scoping your commits accordingly.

And you can always get back to the per-word workflow by reading a word diff side by side while working up your adjusted commit.

And there's tooling for per-word merging in Emacs with things like ediff-regions-wordwise 2, although Emacs is a big enough shift that I don't suggest introducing it here (maybe worth a mention though, in case the reader is already an Emacs user).

[sprossiter]

But isn't what's in your (@btel's) first two paragraphs already implied? I think very few people think managing WYSIWYG documents in a VCS at a diff/change-level is better than using "Track changes"---that's the issue with binary formats (and what Greg's text says about no-one having developed a robust 'Word-diff'). Though see also issue #9 and issue #24.

Or are you talking about text-based documentation source as well (which your later paragraphs seem to hint at)? In that case, I agree that, unless a 'WYSIWYG switcher' is already managing code in a VCS, they will find the switch to using a VCS for document change management an uncrossable gulf for multi-author documents (with some outstanding difficulties even for the VCS-literate along the lines of what you mention). Since Software Carpentry sells the 'whole package' that is not a major problem per se, but I'd personally be wary of implying in the documentation lessons that VCS-managed-changes-for-documentation is an easy thing to switch to. I can see the logic in @wking's comment but that's a significantly higher level of VCS sophistication IMO.

[wking]

On Wed, Feb 10, 2016 at 03:16:15PM -0800, Stuart Rossiter wrote:

I think very few people think managing WYSIWYG documents in a VCS at a diff/change-level is better than using "Track changes"…

Yeah, which is presumably why Microsoft went with the “Track changes” UI. The DVCS approach wins out where you need robust, distributed collaboration, which is not a workflow requirement for most people.

… that's the issue with binary formats…

The word-diff issue seems orthogonal to the binary-ness of the formats, although both will impact the review workflow.

I can see the logic in @wking's comment but that's a significantly higher level of VCS sophistication IMO.

Scoping commits and rerolling submissions seem like pretty standard VCS workflows to me. At least, I rarely succeeded in landing the first version of a large commit when I contribute to a project, so I've tried to stop making them ;).

[btel]

Thanks for the feedback.

To clarify a little, I meant "Track changes" in WYSYWIG vs. VCS in text-based documents. In my definition a single change could be re-wording of a sentence or entire paragraphs. Single-change commits might indeed save the day for VCS but would require a lot of discipline and context-switching (between revising the document and using the VCS). This works well for source code, probably because it's usually quite terse and has rigid syntax, but for prose might prove to be very difficult.

On the other hand with the right tools (VCS-aware editors and merge tools providing easy interface for commit scopping/rerolling described by @sprossiter) this may become much easier. If you have any recommendations, please let me know.

My main concern was rather that I often get a corrected LaTeX document, which I try (and invariably fail) to merge at a single-change level with my VCS. If my collaborators adapted the VCS, this might become easier, but I don't have yet the luxury of having VCS-competent collaborators.

I think I am diverging off topic now. My point is that in the lesson one might describe the workflow for making/merging changes in VCS (probably in later chapters) that might replace "Track changes" of WYSIWYG editors.

[sprossiter]

My point is that in the lesson one might describe the workflow for making/merging changes in VCS (probably in later chapters) that might replace "Track changes" of WYSIWYG editors.

I definitely agree with this.

[wking]

On Wed, Feb 10, 2016 at 04:16:23PM -0800, Bartosz Telenczuk wrote:

Single-change commits might indeed save the day for VCS but would require a lot of discipline and context-switching (between revising the document and using the VCS).

The issue here is probably not switching terminals (or exiting your editor, or calling Magit, or whatever) to create the commit, but thinking at both the “what change do I want to make to the source” and “how do I motivate that change in my commit message” levels. Figuring out the former often involves a lot of rambly, creative thinking. Figuring out the latter involves going back and boiling that creativity down into a sales pitch that someone else will understand.

My main concern was rather that I often get a corrected LaTeX document, which I try (and invariably fail) to merge at a single-change level with my VCS. If my collaborators adapted the VCS, this might become easier, but I don't have yet the luxury of having VCS-competent collaborators.

I still think tooling like ediff-regions-wordwise will help with this, assuming the changes are compact enough that you can actually find text where word-diffed merges are useful. If the contributor has reshuffled the whole project, merge tooling won't be much help, and hopefully they warned everyone else to keep their hands off before they changed everything ;).

My point is that in the lesson one might describe the workflow for making/merging changes in VCS (probably in later chapters) that might replace "Track changes" of WYSIWYG editors.

+1.

[btel]

@wking @sprossiter Thanks for your inputs. Based on our discussion I would like to learn about the following topics in the "authoring" lesson:

• workflow for making/merging changes in text-based documents in (D)VCS and how it compares to "Track changes" of WYSIWG,
• tools (editors, merge tools etc.) to do/review/re-roll single-change commits,
• tools for merging changes at word-level in non-version-controlled documents (integrate changes from your VCS-ignorant colleagues).