Diffscuss – Code reviews in plain text
github.com
github.com
"After removing indenting or encapsulation, lines beginning with # are ignored, as they are considered to be comments."
Against that benefit was the consideration that there could have been comments that weren't diffscuss threads in a diff, and that would have meant that you could have legal diffs that would have terribly confused any diffscuss parsing.
Add to that the fact that you can get a legal diff back just by piping a diffscuss file through a single grep -v, and we decided not to use # (which I think was probably the right call--overloading comment syntax for functional stuff always creeps me out a bit anyway).
Something like: #%%%
You get standard diffs and parsability.
Here's another way to think about it:
It sounds exciting to think that "all legal diffscuss files are also legal diff files!" In fact, very few diffscuss files will be used as diff files, and those that are can be trivially transformed.
It's not awesome on the other hand if "not all legal diff files are legal diffscuss files," which is where piggybacking on the diff comment syntax gets you, because every diffscuss file starts its life as a pure diff file and there's no way to transform an offensive (but legal) diff file into a legal diffscuss file without data loss.
I still think allowing for a state of "perfectly legal diff that would have to be altered to allow for diffscuss parsing" is a tough sell...
We'll make the change.
Besides, code reviews essentially are comments.
We were working for a client who used self-hosted svn and had no code review system.
As for GitHub API: there's a (beta-ish) import from a pull request into a diffscuss file ("diffscuss github-import" for more), but currently nothing to push it back, which is a tricky problem (since what's displayed on a github pull request is actually a mixture of pull request comments and comments made directly on the commit diffs). But if there's sufficient interest we'll take a look!
There's also the whole "what if there are comments from multiple authors to write back" problem, since you're presumably only going to have access to the API on behalf of one user.
I came away from the time I spent looking at this thinking that you'd probably be better off implementing a separate mode that talked more or less synchronously to GH as you replied etc., rather than working on an import / export cycle.
But there might be a better way.
Just FYI, there's a "diffscuss github-import" command (which is beta-ish, but should work) that can import a pull request (or series of pull requests) into diffscuss format.