accumulo-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Christopher <ctubb...@apache.org>
Subject Re: CHANGES files
Date Wed, 10 Jun 2015 21:14:57 GMT
Consider this:

I just updated the CHANGES files for the 1.5.3 and 1.6.3 release. That
involved 13 total commits (including merges) for two edits.

I had to navigate to 8 different "release notes" pages in JIRA, each
time switching from the default "html" to "text" to scroll to the very
bottom and copy and paste into VIM, where I think "prettified" it by
removing redundant blank lines between sections, ultimately resulting
in over 1000 lines of text.

After doing that, I noticed that of those 1000 lines of text, 148 of
them changed in the sections covering 1.5.0, 1.5.1, and 1.5.2 (because
they were wrong in previous releases). The results for 1.6.3 was
similar.

I could have just done it for 1.5.3 and not even gone back to look at
1.5.2, 1.5.1, and 1.5.0, but that seems half-assed, and propagates bad
information which we now know to be incorrect (and has been updated in
JIRA).

If we're going to keep doing this, I'd like to have a really good
reason for why we should (which is more convincing than a preference
for grep over JIRA). I'm not coming up with such a reason.

--
Christopher L Tubbs II
http://gravatar.com/ctubbsii


On Wed, Jun 10, 2015 at 4:06 PM, Josh Elser <josh.elser@gmail.com> wrote:
> 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
>>>>
>>>>
>

Mime
View raw message