Gerrit update - diff in comment notification emails

[Simon Marchi]

Hi!

In the last few days, I have tackled the problem of making the Gerrit
comment notification emails show comments in a diff context.

Previously, we would show some context, but that context would only
include lines from the version of the file that was commented on.  This
means that if the commenter had put a comment on the left pane in the
web UI, the comment would be placed in a context containing lines from
the "before" version of the file.  If the commenter had put a comment on
the right pane, the context would show lines from the "after" version of
the file.

This was already an improvement compared to Gerrit's normal behavior of
showing just one line of context (or the multiple lines of the range,
if the comment was placed on a range), but it still was lacking the
information to understand what was actually changed.

The new format shows a portion of the diff around each comment,
resulting in something like this:

  https://sourceware.org/ml/gdb-patches/2019-11/msg00239.html

I made the output look as much as possible like "git diff" output to
make people feel at home, but we are not limited to that.  I hope that
this is a welcome change.  If you have some ideas on how to improve it
further, I would be happy to hear your suggestions.  I am sure we will
hit some corner cases for which the script doesn't give a good output,
so please report any problem you see.

This is all implemented using a Python script [1] that uses Gerrit's
REST API, so the idea is that if you'd like to propose something, you
can actually try it out yourself and propose a code change.  You can run
the script on any batch of already published comments to see what the
result would be.

If the generated email doesn't contain any of the comments on the code,
such as this:

  https://sourceware.org/ml/gdb-patches/2019-11/msg00238.html

it's probably because the script failed.  It's then possible to just
run it locally, point it to the change, and see what happens.

Note that while this shows the comments in the context of the diffs, it
doesn't show the comment you are replying to, if you were commenting in
reply to another comment.  So if we just reply "Done" in the web UI, we
will only see "Done" in the notification email, which is not very
enlightening.  So please try to use "Quote" instead of "Reply" and quote
the relevant portion of what you are replying to (just like you would by
email), so that it appears in the notification email.

Simon

[1] https://gnutoolchain-gerrit.osci.io/r/gitweb?p=gerrit.git;a=blob;f=resources/com/google/gerrit/pgm/init/generate-comment-diff.py;hb=refs/heads/stable-3.0-gnu