

Diffscuss – Code reviews in plain text - nazri1
https://github.com/hut8labs/diffscuss

======
amdt
I like the interleaved comments with the header and body format. I wonder if
the authors knew that unidiffs already support comment lines? From the
PATCH(1) man page:

"After removing indenting or encapsulation, lines beginning with # are
ignored, as they are considered to be comments."

~~~
tomheon
Good question, we did consider using #, the main benefit of which would have
been that diffscuss files were still legal diffs.

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

~~~
hrjet
IDK if it's too late to discuss this, but a third possibility could have been
to use the second character or more of a # comment as a marker for diffscuss.

Something like: #%%%

You get standard diffs and parsability.

~~~
coreyja
I like this idea. And how I see it this isn't really mixing comments and
functional stuff, since the code reviews and replies are really just comments
on the diff, which is the intended purpose of the # comment

~~~
tomheon
But the diffscuss modes parse the comments into functional structures--threads
--to decide where to insert replies, etc., which is in fact functional--just
not functional for the diff part.

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.

------
michaelmior
Curious why you resorted to email diffs around instead of using pull requests
on GitHub? It would be cool to see this integrated with the GitHub API so I
could push out my comments to GitHub after editing.

~~~
tomheon
Hey there, one of the diffscuss authors here.

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!

~~~
michaelmior
If the tricky part is that comments are a picture of PR comments and diff
comments, it seems like that would be more of a problem for import than
export.

~~~
tomheon
It's tricky to figure out where replies should go, especially if, e.g.,
there's multiple comments from different sources on the same line.

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.

------
scrollaway
This is a fantastic idea! I love it and I'm completely sold. If you manage to
get Github to let you export diff comments as this format, you'll really have
something there!

~~~
tomheon
Hey, one of the authors of diffscuss here.

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.

------
JoshTriplett
This looks promising. I'd love to see this integrated with gerrit and similar,
to provide a two-way bridge between Gerrit change comments and email.

