On Wed, Jun 10, 2015 at 2:32 PM, Christopher <[email protected]> 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 >
