Mailing-List: contact user-help@accumulo.apache.org; run by ezmlm
Precedence: bulk
Reply-To: user@accumulo.apache.org
Received-SPF: pass (nike.apache.org: domain of josh.elser@gmail.com designates
 209.85.192.51 as permitted sender)
Message-ID: <557898B8.2050003@gmail.com>
Date: Wed, 10 Jun 2015 16:06:16 -0400
From: Josh Elser <josh.elser@gmail.com>
User-Agent: Postbox 3.0.11 (Macintosh/20140602)
MIME-Version: 1.0
To: user@accumulo.apache.org
Subject: Re: CHANGES files
References: 
 <CAL5zq9b7sdSX6WOzCeiwoQV=W2jZ6U2Gz-kJTGDo8CHMkGGqUQ@mail.gmail.com>
 <CAGUtCHrEHW8LfBXOKg31ookGHUD4xjzfF2GjvpzVsJHXn0mfdA@mail.gmail.com>
 <CAFAMeYKKRGyxzg2RcKLKqEuyTezCqrVHYEkqEHC759wdyPXVtQ@mail.gmail.com>
 <CAL5zq9Zc2vurfMSxrmQ3PSFV+KrsewVwQJPT+2Om76ByvzqNEA@mail.gmail.com>
In-Reply-To: 
 <CAL5zq9Zc2vurfMSxrmQ3PSFV+KrsewVwQJPT+2Om76ByvzqNEA@mail.gmail.com>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit

I think I was one who argued for this file in the past.

Personally, I like having a static file that always follows the release. 
If I'm following the community (I see JIRA issues that are important and 
that are relevant), I find it much easier to `grep ACCUMULO-XYZ CHANGES` 
to know "do I have this fix".

At the same time, I know the irritation behind creating the file 
(although I find it much less egregious than you do, Christopher). The 
issue to me is not creating the file (vim makes formatting easy), but 
making sure JIRA is actually accurate to how we want: is resolution 
correct, right fixVersion, etc.

I'm guessing that it will be hard to actually get a response from those 
whom it actually benefits -- those who don't primarily operate online.

I guess officially I'm 0 on it. I really don't think it's as terrible to 
maintain as you think it is, but it is unarguably more work for an RM to 
do. I think there are those who benefit from its existence, but I don't 
know how important it actually is (and I'm not one of those people)

Christopher wrote:
> I don't see the utility in having it at all. So, changing the
> procedure to create it (which, honestly, seems more complicated than
> today's tedious JIRA/copy/paste/prettify) doesn't seem helpful to me.
> Before discussing procedure improvements, I'd like to justify the
> utility of having it at all.
>
> Besides, adding a procedure that is guaranteed to create a merge
> conflict on every merge forward (even if there's not a conflict, it
> will almost certainly be merged to the wrong place in the CHANGES
> file) seems like a terrible idea.
>
> --
> Christopher L Tubbs II
> http://gravatar.com/ctubbsii
>
>
> On Wed, Jun 10, 2015 at 2:54 PM, Mike Drob<madrob@cloudera.com>  wrote:
>> Why not ask committers add a line to the CHANGES file about the change when
>> committing? Good place to highlight contributors too. Instead of an
>> auto-generated one or sticking the RM with it, we build it up over the
>> course of development.
>>
>> Individual subtasks could be ignored, larger tasks could be included by
>> discretion of the author.
>>
>> Ex: "ACCUMULO-21224 Add more metrics to the monitor. (Jim Contributor via
>> Mike Drob)"
>>
>> On Wed, Jun 10, 2015 at 1:43 PM, Keith Turner<keith@deenlo.com>  wrote:
>>>
>>>
>>> On Wed, Jun 10, 2015 at 2:32 PM, Christopher<ctubbsii@apache.org>  wrote:
>>>> Okay Accumulators, I have a minor rant about the CHANGES files in
>>>> Accumulo, and I want to get feedback on this file from the user@ and
>>>> dev@ lists.
>>>>
>>>> The summary is:
>>>>
>>>> * I think this CHANGES file is nearly worthless, and a release manager
>>>> shouldn't have to bother with it. We should just delete it.
>>>
>>> +1
>>>
>>> We could drop the file from releases and have a link to a jira query in
>>> the release notes on the web site.
>>>
>>>>
>>>> The justification is:
>>>>
>>>> * The CHANGES file is tedious to prepare (requires manual copy/paste
>>>> from JIRA, after clicking the right buttons in the right order).
>>>> * We now have release notes which compliment the full JIRA search and
>>>> git history, to highlight particular changes, which is far more
>>>> useful.
>>>> * The file is just so big and contains material of questionable
>>>> utility (do we really need to enumerate all sub-tasks for each issue,
>>>> especially when they aren't even grouped with the parent issue?)
>>>> * It's very easy for the CHANGES file to be wrong, by either including
>>>> a JIRA issue which was incorrectly marked, or by omitting an issue
>>>> which was inadvertently left open. The release manager can triage
>>>> these things, but that's a lot of extra work, and it doesn't seem to
>>>> matter whether it is actually wrong or not (it has been wrong in the
>>>> past, and nobody has ever voiced a complaint or indicated any concern
>>>> at all).
>>>> * The CHANGES file is ugly. It follows no markup standard to render it
>>>> in a presentable way (Markdown, APT, asciidoc, etc.). Any
>>>> prettification must be done manually.
>>>> * Issue numbers and subject lines rarely convey adequate information
>>>> to satisfy curious readers wishing to inform themselves of what
>>>> changed. Looking at the actual JIRA issues is necessary to do that,
>>>> and these links are not clickable.
>>>> * Because it is generated from the fixVersion in JIRA, it's often the
>>>> case that we must omit useful fixVersions from JIRA in order to avoid
>>>> confusing inclusions in the CHANGES file (like the JIRA pertaining to
>>>> the release itself). And sometimes people add/remove the wrong
>>>> fixVersion. We can fix this later when we discover it, but it's
>>>> usually too late for the CHANGES file already bundled in a release.
>>>> * Updating the CHANGES file creates unnecessary commits which are
>>>> tedious and painful to merge forward (and usually risky, because it
>>>> would involve -sours type merges) and pollute the git history without
>>>> much use.
>>>> * The convention for a CHANGES file seems to be born of an era prior
>>>> to ubiquitous version control, and I don't think having one is
>>>> required in any way.
>>>>
>>>> Sure, we could automate generating this file (maybe?), which would
>>>> alleviate some of the burden. However, many of these problems would
>>>> still exist, and in the end, I'm not really sure what the benefits
>>>> are. It doesn't seem to be that useful, and especially not compared to
>>>> the amount of work it takes to maintain it. Instead of deleting it, we
>>>> could leave it in place with a generic comment referring the user to
>>>> JIRA and git. But, even that seems to be unnecessary (these resources
>>>> are already prominently linked on the Accumulo site and in the project
>>>> pom.xml in the official source release, and it is already well
>>>> understood that a project is going to have an SCM history and an issue
>>>> tracker).
>>>>
>>>> But, what do you think? Is this file really useful to anybody? Does
>>>> its utility outweigh the burden it places on release managers, which
>>>> can slow down and complicate the release process?
>>>>
>>>> --
>>>> Christopher L Tubbs II
>>>> http://gravatar.com/ctubbsii
>>>