New candidate JEP: 369: Migrate to GitHub

[Andrew Dinn]

On 12/11/2019 16:00, mark.reinhold at oracle.com wrote:
> https://openjdk.java.net/jeps/369
Firstly, thanks to Joe and Erik for producing a very comprehensive JEP
that addresses so many important questions. There are many aspects of
this proposed move that are very appealing. However, I am afraid I am
still going to start by expressing my severe reservations about one
proposed change: replacing email review with GitHub PRs (sorry guys :-/).

The JEP has this laudable goal:

"Ensure that workflows structurally similar to the existing e-mail and
webrev based workflows are supported."

and further qualifies that with:

"Today, OpenJDK contributors collaborate via mailing lists, they push
changes to Mercurial repositories, they test changes via the jdk/submit
service, and they file bug reports via the JDK Bug System (JBS).
Contributors can also make use of several command-line interface (CLI)
tools, primarily jcheck, webrev, and defpath. This is a workflow that
many experienced contributors enjoy and find productive. It's therefore
critical to preserve as much of this workflow as possible if we move to
an external provider."

which one cannot really disagree with.

The JEP then explains that:

"Reviewers can now discuss the changes in the PR, using multiple workflows:

    By replying to the RFR email sent to the mailing list(s), in which
case the contents of replies are copied into the PR on GitHub (no GitHub
account is required);
   . . .
Any comment made in any of the workflows is reflected in all of the
workflows. One reviewer can add a comment via the mailing list, another
via the web browser, and a third via the command-line and they will all
see each others' comments."

My experience of GitHub use in the Graal project suggest that this is
not entirely the full picture. My view derived from that experience is
that the GitHub PR is very much an inferior medium for review
discussion. In particular, it definitely fails to be "structurally
similar to the existing e-mail and webrev based workflows".

Firstly, I'll note that email discussions consist of a tree of dependent
commentary. That commentary often contains quoted material which,
especially when carefully edited (as it normally is), tracks relevant
context. The structuring that results from this use of the reply
hierarchy and quoting permits a given discussion to split into a group
of related subordinate discussions where required while still retaining
a continued thread of relevance to a specific review. Crucially, most
email readers allow such branching discussions to be followed and
extended in /parallel/.

By contrast discussions in GitHub PRs are essentially linearized (modulo
a single level of nesting of commentary on top level comments). Worse,
the presentation forces all commentary to be flattened into a single
browser pane view. This linear mode of presentation results in a severe
hindrance to separation of, and attention to, separate concerns. It also
fails to preserve and display source relationships that clarify the
provenance and relevance of quoted text i.e. it not only fails to record
but actually obfuscates important context.

Of course, discussions that remain in email may continue to profit from
the multi-focus aspect of the current workflow. However, I believe that
contributions to the discussion via a GitHub PR will inevitably bypass
and, therefore, invalidate any such structuring contributed via the
email workflow. Not only do I currently see that effect with Graal PRs
but I also see the damage it imposes on flow and quality of discussion.

Secondly, email reviews are conventionally directed to readers with
different domains of interest and expertise. That sometimes requires
re-routing a discussion to a different list from the one on which it was
first initiated. It also sometimes requires posting comments to multiple
lists, either when discussion is initiated or in mid-stream as the scope
of discussion develops. Managing distribution when using emails lists is
both easily achieved and well understood (n.b. that's not to imply that
deciding which list to send to is easy).

The JEP suggests that discussions raised via PRs will be routed to lists
1) derived from the affected files and/or 2) specified by whoever raises
the PR. It doesn't explain how (whether) target lists are to be (may be)
updated as review progresses. It also doesn't state clearly whether
whoever raises the PR or comments on it will have the ability to
override those default choices (I fully expect that option will be
necessary in some cases).

I need to stress that these concerns should not be considered as minor
details of how the project operates. Easy management of the flow and
direction of discussion is critical to being able to consume and respond
to commentary at the rate needed to keep up with a project as large and
rapidly changing as OpenJDK currently is. Given the central importance
of our review process to ensuring the health of the project and its
products I think it is right to be very concerned about the potential
for problems caused by this switch of medium.

regards,


Andrew Dinn
-----------
Senior Principal Software Engineer
Red Hat UK Ltd
Registered in England and Wales under Company Registration No. 03798903
Directors: Michael Cunningham, Michael ("Mike") O'Neill