accumulo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Christopher <ctubb...@apache.org>
Subject CHANGES files
Date Wed, 10 Jun 2015 18:32:16 GMT
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.

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