You are viewing a plain text version of this content. The canonical link for it is here.
Posted to user@accumulo.apache.org by Christopher <ct...@apache.org> on 2015/06/10 20:32:16 UTC
CHANGES files
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
Re: CHANGES files
Posted by Eric Newton <er...@gmail.com>.
+1
Without the manual filtering of the tickets, the CHANGES file is pretty
worthless. However that work falls on the Release Manager. I'm all for
making the Release Manager's job easy.
On Wed, Jun 10, 2015 at 2:32 PM, Christopher <ct...@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.
>
> 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
>
Re: CHANGES files
Posted by Sean Busbey <bu...@cloudera.com>.
On Wed, Jun 10, 2015 at 1:54 PM, Mike Drob <ma...@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)"
>
>
>
-1 no definitely not this approach. This is what Hadoop does and it's a
nightmare of inconsistency.
--
Sean
Re: CHANGES files
Posted by Josh Elser <jo...@gmail.com>.
Sean Busbey wrote:
>
>
> On Wed, Jun 10, 2015 at 3:06 PM, Josh Elser <josh.elser@gmail.com
> <ma...@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)
>
>
>
> What if we added a list of all jiras to the end of the release notes and
> then included those in the distribution?
>
>
> --
> Sean
That would work, but I'm not sure if it really addresses Christopher's
initial irritation (maintaining the list of issues for a release).
It would also be a little more painful in practice since we tend to
write the release notes after we have an RC staged (during the down-time).
Re: CHANGES files
Posted by Christopher <ct...@apache.org>.
On Wed, Jun 10, 2015 at 4:13 PM, Sean Busbey <bu...@cloudera.com> wrote:
>
>
> On Wed, Jun 10, 2015 at 3:06 PM, Josh Elser <jo...@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)
>>
>
>
> What if we added a list of all jiras to the end of the release notes and
> then included those in the distribution?
>
I definitely do not like that. Part of the value of the release notes
is that we can make changes to it as we find typos or errors, or even
new bugs that we find which we'd want to warn any newcomers to that
release of.
It also doesn't solve half the problems I mentioned about it being
tedious to maintain or generate or format or ensure correctness, and
it makes it worse, because it'd apply to the entire release notes, not
just the list of JIRAs.
Re: CHANGES files
Posted by Sean Busbey <bu...@cloudera.com>.
On Wed, Jun 10, 2015 at 3:06 PM, Josh Elser <jo...@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)
>
>
What if we added a list of all jiras to the end of the release notes and
then included those in the distribution?
--
Sean
Re: CHANGES files
Posted by Christopher <ct...@apache.org>.
Yes, the idea would be to replace the CHANGES file with a link to JIRA
in the release notes on the site where you download.
--
Christopher L Tubbs II
http://gravatar.com/ctubbsii
On Wed, Jun 10, 2015 at 5:30 PM, Marc Reichman
<mr...@pixelforensics.com> wrote:
> I'm not sure if this has been covered already, but the Jetbrains family of
> products (IntelliJ, TeamCity, etc.) uses this mechanism for their detailed
> release notes, linked right from their download pages:
> https://confluence.jetbrains.com/display/TW/TeamCity+9.0.4+%28build+32407%29+Release+Notes
>
> Can the Accumulo JIRA be linked to in such a public way? If so that can take
> care of most of the requirements, I'd wager.
>
> Marc
>
> On Wed, Jun 10, 2015 at 4:28 PM, Christopher <ct...@apache.org> wrote:
>>
>> On Wed, Jun 10, 2015 at 5:21 PM, Sean Busbey <bu...@cloudera.com> wrote:
>> >
>> >
>> > On Wed, Jun 10, 2015 at 4:14 PM, Christopher <ct...@apache.org>
>> > wrote:
>> >>
>> >>
>> >>
>> >> 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.
>> >
>> >
>> >
>> > The reason I heard Josh give is accessibility for folks who use our
>> > software
>> > but do not have access to our web pages, jira, nor our git repository.
>> >
>> > I think that's a legitimate benefit, but like Josh I don't know how much
>> > the
>> > file effectively gets used in those spaces currently.
>> >
>>
>> True. That's a good point. But... even if that were true for some
>> users (we're obviously lacking data on that), there's still the
>> concern about its accuracy, and whether an issue number and summary is
>> adequate to convey anything meaningful to those users. And, even if it
>> were minimally meaningful and 100% accurate (which they aren't), does
>> this benefit outweigh the burden? In any case, these individuals
>> (presuming they exist) can likely just as easily generate a static
>> up-to-date report, as needed, from JIRA at the time they download the
>> release.
>
>
Re: CHANGES files
Posted by Marc Reichman <mr...@pixelforensics.com>.
I'm not sure if this has been covered already, but the Jetbrains family of
products (IntelliJ, TeamCity, etc.) uses this mechanism for their detailed
release notes, linked right from their download pages:
https://confluence.jetbrains.com/display/TW/TeamCity+9.0.4+%28build+32407%29+Release+Notes
Can the Accumulo JIRA be linked to in such a public way? If so that can
take care of most of the requirements, I'd wager.
Marc
On Wed, Jun 10, 2015 at 4:28 PM, Christopher <ct...@apache.org> wrote:
> On Wed, Jun 10, 2015 at 5:21 PM, Sean Busbey <bu...@cloudera.com> wrote:
> >
> >
> > On Wed, Jun 10, 2015 at 4:14 PM, Christopher <ct...@apache.org>
> wrote:
> >>
> >>
> >>
> >> 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.
> >
> >
> >
> > The reason I heard Josh give is accessibility for folks who use our
> software
> > but do not have access to our web pages, jira, nor our git repository.
> >
> > I think that's a legitimate benefit, but like Josh I don't know how much
> the
> > file effectively gets used in those spaces currently.
> >
>
> True. That's a good point. But... even if that were true for some
> users (we're obviously lacking data on that), there's still the
> concern about its accuracy, and whether an issue number and summary is
> adequate to convey anything meaningful to those users. And, even if it
> were minimally meaningful and 100% accurate (which they aren't), does
> this benefit outweigh the burden? In any case, these individuals
> (presuming they exist) can likely just as easily generate a static
> up-to-date report, as needed, from JIRA at the time they download the
> release.
>
Re: CHANGES files
Posted by Christopher <ct...@apache.org>.
On Wed, Jun 10, 2015 at 5:21 PM, Sean Busbey <bu...@cloudera.com> wrote:
>
>
> On Wed, Jun 10, 2015 at 4:14 PM, Christopher <ct...@apache.org> wrote:
>>
>>
>>
>> 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.
>
>
>
> The reason I heard Josh give is accessibility for folks who use our software
> but do not have access to our web pages, jira, nor our git repository.
>
> I think that's a legitimate benefit, but like Josh I don't know how much the
> file effectively gets used in those spaces currently.
>
True. That's a good point. But... even if that were true for some
users (we're obviously lacking data on that), there's still the
concern about its accuracy, and whether an issue number and summary is
adequate to convey anything meaningful to those users. And, even if it
were minimally meaningful and 100% accurate (which they aren't), does
this benefit outweigh the burden? In any case, these individuals
(presuming they exist) can likely just as easily generate a static
up-to-date report, as needed, from JIRA at the time they download the
release.
Re: CHANGES files
Posted by Sean Busbey <bu...@cloudera.com>.
On Wed, Jun 10, 2015 at 4:14 PM, Christopher <ct...@apache.org> wrote:
>
>
> 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.
>
The reason I heard Josh give is accessibility for folks who use our
software but do not have access to our web pages, jira, nor our git
repository.
I think that's a legitimate benefit, but like Josh I don't know how much
the file effectively gets used in those spaces currently.
--
Sean
Re: CHANGES files
Posted by Christopher <ct...@apache.org>.
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 <jo...@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<ma...@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<ke...@deenlo.com> wrote:
>>>>
>>>>
>>>>
>>>> On Wed, Jun 10, 2015 at 2:32 PM, Christopher<ct...@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
>>>>
>>>>
>
Re: CHANGES files
Posted by Josh Elser <jo...@gmail.com>.
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<ma...@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<ke...@deenlo.com> wrote:
>>>
>>>
>>> On Wed, Jun 10, 2015 at 2:32 PM, Christopher<ct...@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
>>>
Re: CHANGES files
Posted by Christopher <ct...@apache.org>.
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 <ma...@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 <ke...@deenlo.com> wrote:
>>
>>
>>
>> On Wed, Jun 10, 2015 at 2:32 PM, Christopher <ct...@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
>>
>>
>
Re: CHANGES files
Posted by Mike Drob <ma...@cloudera.com>.
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 <ke...@deenlo.com> wrote:
>
>
> On Wed, Jun 10, 2015 at 2:32 PM, Christopher <ct...@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
>>
>
>
Re: CHANGES files
Posted by Keith Turner <ke...@deenlo.com>.
On Wed, Jun 10, 2015 at 2:32 PM, Christopher <ct...@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
>