I've started leaning towards a hybrid approach: I put everything I want to say, including some code changes, and sometimes complex argumentation into comments the branch. I differentiate these into two categories:
1. Literal comments, to remain for posterity - typically things I agree with, but for which it wasn't immediately clear I would at the outset; and 2. Queries/suggestions for the author, to be removed once they're resolved Then on JIRA, I make sure to raise explicitly for outside input, and for non-code-literate readers for posterity, any more major decisions that need consideration / discussion. Ideally, comments of type 2 would be replaced by summary comments of type 1, also for posterity. You can never have too many comments (so long as they're explanatory, not just restating the code, obviously).... I think this probably leads to better JIRA and comments, as we: 1. Avoid the higgledypiggledy JIRA messes that can be very hard to unpick, consciously limiting discussion to high level decisions about approach, or unexpected complexities, etc. The things readers of JIRA care about. 2. Keep decisions about low level minutiae commented directly where they matter, to influence future authors without reference to JIRA On Wed, Jul 8, 2015 at 8:21 PM, Josh McKenzie <jmcken...@apache.org> wrote: > As some of you might have noticed, Tyler and I tossed around a couple of > thoughts yesterday regarding the best way to perform larger reviews on > JIRA. > > I've been leaning towards the approach Benedict's been taking lately > w/putting comments inline on a branch for the initial author to inspect as > that provides immediate locality for a reviewer to write down their > thoughts and the same for the initial developer to ingest them. One > downside to that approach is that the extra barrier to entry makes it more > of a 1-on-1 conversation rather than an open discussion via JIRA comments. > Also, if one deletes branches from github we then lose our discussion > history on the review process which is a big problem for digging into why > certain decisions were made or revised during the process. > > On the competing side, monster comments like this > < > https://issues.apache.org/jira/browse/CASSANDRA-6477?focusedCommentId=14617221&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-14617221 > > > (which > is one of multiple to come) are burdensome to create and map into a JIRA > comment and, in my experience, also a burden to map back into the code-base > as a developer. Details are lost in translation; I'm comfortable labeling > this a sub-optimal method of communication. > > So what to do? > > -- > Joshua McKenzie >
