You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@accumulo.apache.org by Josh Elser <jo...@gmail.com> on 2014/02/19 22:30:32 UTC
[DISCUSS] CHANGES Documents
The CHANGES document that is included in an Accumulo release contains
some set of changes from a previous release which presently contain the
following information:
1) Issue Type (Task, Bug, Feature, etc)
2) Issue Number (ACCUMULO-1234)
3) Issue Subject
There have been various preferences expressed, primarily over IRC, on
which changes should be contained and how they should be formatted. The
largest consensus, and what I believe we should do, is as follows:
Entries in a CHANGES file should contain issues, delimited by minor
version within the major version[1], grouped by issue type. The minor
version changes sorted be sorted in reverse order (e.g. 1.5.2, 1.5.1,
then 1.5.0). Changes from the previous major version (e.g. 1.4.x) would
*not* be included in this CHANGES file.
Opinions? The results of this discussion will be documented on the
release-making page[2] of the website for future reference.
- Josh
[1] Major and minor version here is referred to as Y and Z of version
strings of the form: X.Y.Z (not as prescribed by semver, proper)
[2] http://accumulo.apache.org/releasing.html
Re: [DISCUSS] CHANGES Documents
Posted by Keith Turner <ke...@deenlo.com>.
On Thu, Feb 20, 2014 at 12:31 PM, Josh Elser <jo...@gmail.com> wrote:
> On 2/20/14, 9:09 AM, Keith Turner wrote:
>
>> footnote reference to SCM/JIRA for the full list of changes. But, is
>>> >there another role the CHANGES file is expected to play which I'm
>>> >overlooking?
>>> >
>>>
>> I think one value of whats currently in the CHANGES file is that by
>> scanning it you may find out about something thats very important to you.
>> No one else thought it was important and it was not included in the nice
>> user friendly summary.
>>
>>
>>
> I have definitely had that happen to me perusing the HDFS CHANGES file
> before. That's why I'm a fan of keeping a "complete" CHANGES file.
>
Me too. I can't think of a good reason to make choosing between user
friendly release notes and the exhaustive list from jira an XOR. The only
argument that slightly concerned me was Christophers predicition of a huge
changes file (but it would compress nicely). I think thats a bridge we
could cross later and make decisions about like ageing off older data. We
do not need to make decisions about that now.
Re: [DISCUSS] CHANGES Documents
Posted by Josh Elser <jo...@gmail.com>.
On 2/20/14, 9:09 AM, Keith Turner wrote:
>> footnote reference to SCM/JIRA for the full list of changes. But, is
>> >there another role the CHANGES file is expected to play which I'm
>> >overlooking?
>> >
> I think one value of whats currently in the CHANGES file is that by
> scanning it you may find out about something thats very important to you.
> No one else thought it was important and it was not included in the nice
> user friendly summary.
>
>
I have definitely had that happen to me perusing the HDFS CHANGES file
before. That's why I'm a fan of keeping a "complete" CHANGES file.
Re: [DISCUSS] CHANGES Documents
Posted by Keith Turner <ke...@deenlo.com>.
On Wed, Feb 19, 2014 at 11:33 PM, Christopher <ct...@apache.org> wrote:
> I agree with that a short list would be more valuable to readers.
> Further, I do not think a comprehensive history of changes would be in
> any way beneficial, nor do I think sub-tickets, tests, or tasks, are
>
I would love to drop sub-task from the list.
> beneficial to report. By including this comprehensive list, we're also
> making a lot of assumptions about the value of the issue summary to
> users, and I'm not so certain that's enough information, in the
> general case, to be meaningful to users without requiring them to
> cross-reference JIRA anyway.
>
> For example, consider these two examples of things labeled "New Feature":
> 1. [ACCUMULO-1488] - support BigDecimal encoding for basic built-in
> combiners
> 2. [ACCUMULO-1960] - agitator should support sudo as well
>
> Aside from the fact that these are probably improvements, not actual
> new features, can anybody honestly say that an average user will know
> what these are referring to without actually looking them up in JIRA?
>
We could probably do better here. Issues serve multiple purposes. For us
the developers they help us track work that needs to be done. Once that
work is done they serve as a way to communicate with users. I know
personally I usually write tickets with the former purpose in mind.
Sometimes though I will step back and think about the latter purpose and
create a better subject and description.
> I suspect not... and these are listed prominently in the "New Feature"
> section... something a user would care about.
>
> However, that said, I think Keith's idea of prepending to the CHANGES
> list generated by the tool (perhaps without tasks/tests/sub-tickets),
> for each released version, is the simplest way to generate and include
> them. (That's what I used for 1.5.0).
>
> It's true that 1.5.0 replaced this file, rather than prepended to
> it... I'm not sure if that's something we should follow as a precedent
> always, or for significant (non-bugfix) version jumps, or not at all.
> I would be concerned about carrying on this practice of always
> prepending, especially as we approach 1MB in size or larger. Our
> tickets are now in the thousands, and the file size could easily grow
> out of control. This file certainly won't be of much value if it's too
> large to open in a minimal text editor like Notepad.exe (which, in
> some versions has a limit of 54KB file size).
>
> However, every 1.5.0 release candidate replaced this file instead of
> preserving the history of prior release changes, and nobody noticed
> until within this last week, so that might say something about the
> value people are actually getting from this file. I strongly suspect
>
One thing to note is that we are elevating the importance of this file by
linking to it on our downloads page. We are encouraging users to look at
it right away. This is why I was concerned when it seemed the file did
not make sense.
> that, if anything, people just want to know the simple answers "What's
> New?" and "Does this fix my bug yet?" questions, and I don't think
> this file answers either of those questions well in any of the
> previous releases. Nor do I think this format lends itself easily to
> answering those questions. A per-release "Release Notes" section on
>
the website would probably be more useful for that purpose, with a
>
I also think release notes should be in the source tar bar because of
reasons Sean stated and because of the link rot issue I mentioned.
> footnote reference to SCM/JIRA for the full list of changes. But, is
> there another role the CHANGES file is expected to play which I'm
> overlooking?
>
I think one value of whats currently in the CHANGES file is that by
scanning it you may find out about something thats very important to you.
No one else thought it was important and it was not included in the nice
user friendly summary.
>
> --
> Christopher L Tubbs II
> http://gravatar.com/ctubbsii
>
>
> On Wed, Feb 19, 2014 at 4:53 PM, Eric Newton <er...@gmail.com>
> wrote:
> > I think generated CHANGES files are a disservice to the reader.
> >
> > A short list of the major differences from the last release should be
> given.
> >
> > For a bug release, a short list of the critical bugs should be given
> after
> > the .0 release.
> >
> > So, 1.4.1 would list the 1.4.0 features, and the critical bugs that
> caused
> > the 1.4.1 release to be made.
> > 1.4.2 would list 1.4.0 features, 1.4.1 and 1.4.2 critical bug fixes.
> >
> > Basically, I want to quickly understand if I should upgrade (or not).
> >
> > If people want the full list, they can get it from JIRA.
> >
> > I would also be fine with a CHANGES file with a URL reference to JIRA.
> >
> > I personally would not down-vote a release because it has an accurate
> > CHANGES file, but not the content I think it should have.
> >
> > -Eric
> >
> >
> >
> > On Wed, Feb 19, 2014 at 4:30 PM, Josh Elser <jo...@gmail.com>
> wrote:
> >
> >> The CHANGES document that is included in an Accumulo release contains
> some
> >> set of changes from a previous release which presently contain the
> >> following information:
> >>
> >> 1) Issue Type (Task, Bug, Feature, etc)
> >> 2) Issue Number (ACCUMULO-1234)
> >> 3) Issue Subject
> >>
> >> There have been various preferences expressed, primarily over IRC, on
> >> which changes should be contained and how they should be formatted. The
> >> largest consensus, and what I believe we should do, is as follows:
> >>
> >> Entries in a CHANGES file should contain issues, delimited by minor
> >> version within the major version[1], grouped by issue type. The minor
> >> version changes sorted be sorted in reverse order (e.g. 1.5.2, 1.5.1,
> then
> >> 1.5.0). Changes from the previous major version (e.g. 1.4.x) would
> *not* be
> >> included in this CHANGES file.
> >>
> >> Opinions? The results of this discussion will be documented on the
> >> release-making page[2] of the website for future reference.
> >>
> >> - Josh
> >>
> >> [1] Major and minor version here is referred to as Y and Z of version
> >> strings of the form: X.Y.Z (not as prescribed by semver, proper)
> >> [2] http://accumulo.apache.org/releasing.html
> >>
>
Re: [DISCUSS] CHANGES Documents
Posted by Josh Elser <jo...@gmail.com>.
If we need to, I can. I'd prefer to not have to call a vote, though.
On 2/20/14, 10:38 AM, Mike Drob wrote:
> I'd prefer just notes from the latest major release in the CHANGES file.
> You could always call for a vote on this. :)
>
>
> On Thu, Feb 20, 2014 at 1:35 PM, Josh Elser <jo...@gmail.com> wrote:
>
>> On 2/20/14, 10:23 AM, Keith Turner wrote:
>>
>>>>> There have been a lot of good ideas mentioned. What do we want to do
>>>>> for
>>>>>
>>>>>>>>> 1.5.1? I would not be opposed to waiting a few days on the 1.5.1
>>>>>> release
>>>>>>>>> if someone wants to create nice user friendly release notes. Or for
>>>>>>>>> 1.5.1
>>>>>>>>> we could just continue to do what was done for 1.4.X releases. For
>>>>>>>>> 1.6.0
>>>>>>>>> I think we should create a user friendly summary of whats important
>>>>>> in
>>>>>>>>> the
>>>>>>>>> release.
>>>>>>>>>
>>>>>>>>>
>>>>>>
>>>>>>> I'd prefer to not hold up 1.5.1 for something like this, and would
>>>>> rather
>>>>>>> just follow suite with 1.4. By this, you mean having all CHANGES from
>>>>> 1.4.X
>>>>>>> and 1.5.0 in addition to the 1.5.1 changes, correct? Is this
>>>>> acceptable to
>>>>>>> everyone? I know there were other suggestions made and don't want to
>>>>>>> prematurely squash discussion.
>>>>>>>
>>>>>
>>>>>
>>>>> I was thinking taking the 1.5.0 changes file and adding the 1.5.1 stuff
>>>> to
>>>>> it. If we did anything w/ 1.4, we would would only want to take 1.4.0
>>>>> changes and add that after 1.5.0. Not all changes in 1.4.[1.2.3.4] are
>>>> in
>>>>> 1.5 series and any changes that are in both are hopefully marked
>>>> properly
>>>>> in jira and already in the 1.5.X list. Since the 1.4.0 changes were not
>>>>> listed in 1.5.0, I am not neutral on adding that in 1.5.1.
>>>>>
>>>>
>>> s/not neutral/not not neutral/
>>>
>>>
>>>
>> Because that clarification makes things simpler :P
>>
>> I'm still unsure if 1.5.0 did not contain 1.4 changes intentionally or by
>> omission. I feel like Christopher had said that was unintentional, but I'm
>> not sure anymore. I'm not super opinionated on whether or not 1.5 contains
>> 1.4 changes. I can see arguments for and against doing it and am fine
>> seeing it either way.
>>
>> Overall, I'd rather just get to some consensus on the subject.
>>
>
Re: [DISCUSS] CHANGES Documents
Posted by Mike Drob <ma...@cloudera.com>.
I'd prefer just notes from the latest major release in the CHANGES file.
You could always call for a vote on this. :)
On Thu, Feb 20, 2014 at 1:35 PM, Josh Elser <jo...@gmail.com> wrote:
> On 2/20/14, 10:23 AM, Keith Turner wrote:
>
>> >> There have been a lot of good ideas mentioned. What do we want to do
>>>> for
>>>>
>>>>> >>>1.5.1? I would not be opposed to waiting a few days on the 1.5.1
>>>>> release
>>>>> >>>if someone wants to create nice user friendly release notes. Or for
>>>>> >>>1.5.1
>>>>> >>>we could just continue to do what was done for 1.4.X releases. For
>>>>> >>>1.6.0
>>>>> >>>I think we should create a user friendly summary of whats important
>>>>> in
>>>>> >>>the
>>>>> >>>release.
>>>>> >>>
>>>>> >>>
>>>>>
>>>> >>I'd prefer to not hold up 1.5.1 for something like this, and would
>>>> rather
>>>> >>just follow suite with 1.4. By this, you mean having all CHANGES from
>>>> 1.4.X
>>>> >>and 1.5.0 in addition to the 1.5.1 changes, correct? Is this
>>>> acceptable to
>>>> >>everyone? I know there were other suggestions made and don't want to
>>>> >>prematurely squash discussion.
>>>> >>
>>>>
>>> >
>>> >I was thinking taking the 1.5.0 changes file and adding the 1.5.1 stuff
>>> to
>>> >it. If we did anything w/ 1.4, we would would only want to take 1.4.0
>>> >changes and add that after 1.5.0. Not all changes in 1.4.[1.2.3.4] are
>>> in
>>> >1.5 series and any changes that are in both are hopefully marked
>>> properly
>>> >in jira and already in the 1.5.X list. Since the 1.4.0 changes were not
>>> >listed in 1.5.0, I am not neutral on adding that in 1.5.1.
>>> >
>>>
>> s/not neutral/not not neutral/
>>
>>
>>
> Because that clarification makes things simpler :P
>
> I'm still unsure if 1.5.0 did not contain 1.4 changes intentionally or by
> omission. I feel like Christopher had said that was unintentional, but I'm
> not sure anymore. I'm not super opinionated on whether or not 1.5 contains
> 1.4 changes. I can see arguments for and against doing it and am fine
> seeing it either way.
>
> Overall, I'd rather just get to some consensus on the subject.
>
Re: [DISCUSS] CHANGES Documents
Posted by Josh Elser <jo...@gmail.com>.
On 2/20/14, 10:23 AM, Keith Turner wrote:
>>> >> There have been a lot of good ideas mentioned. What do we want to do for
>>>> >>>1.5.1? I would not be opposed to waiting a few days on the 1.5.1 release
>>>> >>>if someone wants to create nice user friendly release notes. Or for
>>>> >>>1.5.1
>>>> >>>we could just continue to do what was done for 1.4.X releases. For
>>>> >>>1.6.0
>>>> >>>I think we should create a user friendly summary of whats important in
>>>> >>>the
>>>> >>>release.
>>>> >>>
>>>> >>>
>>> >>I'd prefer to not hold up 1.5.1 for something like this, and would rather
>>> >>just follow suite with 1.4. By this, you mean having all CHANGES from 1.4.X
>>> >>and 1.5.0 in addition to the 1.5.1 changes, correct? Is this acceptable to
>>> >>everyone? I know there were other suggestions made and don't want to
>>> >>prematurely squash discussion.
>>> >>
>> >
>> >I was thinking taking the 1.5.0 changes file and adding the 1.5.1 stuff to
>> >it. If we did anything w/ 1.4, we would would only want to take 1.4.0
>> >changes and add that after 1.5.0. Not all changes in 1.4.[1.2.3.4] are in
>> >1.5 series and any changes that are in both are hopefully marked properly
>> >in jira and already in the 1.5.X list. Since the 1.4.0 changes were not
>> >listed in 1.5.0, I am not neutral on adding that in 1.5.1.
>> >
> s/not neutral/not not neutral/
>
>
Because that clarification makes things simpler :P
I'm still unsure if 1.5.0 did not contain 1.4 changes intentionally or
by omission. I feel like Christopher had said that was unintentional,
but I'm not sure anymore. I'm not super opinionated on whether or not
1.5 contains 1.4 changes. I can see arguments for and against doing it
and am fine seeing it either way.
Overall, I'd rather just get to some consensus on the subject.
Re: [DISCUSS] CHANGES Documents
Posted by Keith Turner <ke...@deenlo.com>.
On Thu, Feb 20, 2014 at 1:21 PM, Keith Turner <ke...@deenlo.com> wrote:
>
>
>
> On Thu, Feb 20, 2014 at 1:10 PM, Josh Elser <jo...@gmail.com> wrote:
>
>> On 2/20/14, 10:00 AM, Keith Turner wrote:
>>
>>> On Thu, Feb 20, 2014 at 1:10 AM, Sean Busbey<busbey+lists@cloudera.com
>>> >wrote:
>>>
>>> >On Wed, Feb 19, 2014 at 10:33 PM, Christopher<ct...@apache.org>
>>>> wrote:
>>>> >
>>>>
>>>>> > >
>>>>> > >value people are actually getting from this file. I strongly suspect
>>>>> > >that, if anything, people just want to know the simple answers
>>>>> "What's
>>>>> > >New?" and "Does this fix my bug yet?" questions, and I don't think
>>>>> > >this file answers either of those questions well in any of the
>>>>> > >previous releases. Nor do I think this format lends itself easily to
>>>>> > >answering those questions. A per-release "Release Notes" section on
>>>>> > >the website would probably be more useful for that purpose, with a
>>>>> > >footnote reference to SCM/JIRA for the full list of changes. But, is
>>>>> > >there another role the CHANGES file is expected to play which I'm
>>>>> > >overlooking?
>>>>> > >
>>>>>
>>>> >
>>>> >
>>>> >The main one I can think of is "Will this break my already working
>>>> system
>>>> >in some other way?"
>>>> >
>>>> >So in addition to your two above major areas, I'd say a section on
>>>> known
>>>> >backwards incompatible changes[1] would cover things.
>>>> >
>>>>
>>> I would really like to see this type of information called out in release
>>> notes.
>>>
>>
>> Agreed
>>
>>
>>
>> There have been a lot of good ideas mentioned. What do we want to do for
>>> 1.5.1? I would not be opposed to waiting a few days on the 1.5.1 release
>>> if someone wants to create nice user friendly release notes. Or for
>>> 1.5.1
>>> we could just continue to do what was done for 1.4.X releases. For
>>> 1.6.0
>>> I think we should create a user friendly summary of whats important in
>>> the
>>> release.
>>>
>>>
>> I'd prefer to not hold up 1.5.1 for something like this, and would rather
>> just follow suite with 1.4. By this, you mean having all CHANGES from 1.4.X
>> and 1.5.0 in addition to the 1.5.1 changes, correct? Is this acceptable to
>> everyone? I know there were other suggestions made and don't want to
>> prematurely squash discussion.
>>
>
> I was thinking taking the 1.5.0 changes file and adding the 1.5.1 stuff to
> it. If we did anything w/ 1.4, we would would only want to take 1.4.0
> changes and add that after 1.5.0. Not all changes in 1.4.[1.2.3.4] are in
> 1.5 series and any changes that are in both are hopefully marked properly
> in jira and already in the 1.5.X list. Since the 1.4.0 changes were not
> listed in 1.5.0, I am not neutral on adding that in 1.5.1.
>
s/not neutral/not not neutral/
>
>
>>
>> For 1.6.0, I would be happy to play around with some static-content
>> generation tools (I like jekyll[1], personally, but I'll have to try out a
>> few for our needs. We could even try to reuse the ASF CMS codebase) and see
>> if we can get a markdown-generated document going that we can create a nice
>> release-notes page from.
>>
>> [1] http://jekyllrb.com/
>>
>
>
Re: [DISCUSS] CHANGES Documents
Posted by Keith Turner <ke...@deenlo.com>.
On Thu, Feb 20, 2014 at 1:10 PM, Josh Elser <jo...@gmail.com> wrote:
> On 2/20/14, 10:00 AM, Keith Turner wrote:
>
>> On Thu, Feb 20, 2014 at 1:10 AM, Sean Busbey<busbey+lists@cloudera.com
>> >wrote:
>>
>> >On Wed, Feb 19, 2014 at 10:33 PM, Christopher<ct...@apache.org>
>>> wrote:
>>> >
>>>
>>>> > >
>>>> > >value people are actually getting from this file. I strongly suspect
>>>> > >that, if anything, people just want to know the simple answers
>>>> "What's
>>>> > >New?" and "Does this fix my bug yet?" questions, and I don't think
>>>> > >this file answers either of those questions well in any of the
>>>> > >previous releases. Nor do I think this format lends itself easily to
>>>> > >answering those questions. A per-release "Release Notes" section on
>>>> > >the website would probably be more useful for that purpose, with a
>>>> > >footnote reference to SCM/JIRA for the full list of changes. But, is
>>>> > >there another role the CHANGES file is expected to play which I'm
>>>> > >overlooking?
>>>> > >
>>>>
>>> >
>>> >
>>> >The main one I can think of is "Will this break my already working
>>> system
>>> >in some other way?"
>>> >
>>> >So in addition to your two above major areas, I'd say a section on known
>>> >backwards incompatible changes[1] would cover things.
>>> >
>>>
>> I would really like to see this type of information called out in release
>> notes.
>>
>
> Agreed
>
>
>
> There have been a lot of good ideas mentioned. What do we want to do for
>> 1.5.1? I would not be opposed to waiting a few days on the 1.5.1 release
>> if someone wants to create nice user friendly release notes. Or for 1.5.1
>> we could just continue to do what was done for 1.4.X releases. For 1.6.0
>> I think we should create a user friendly summary of whats important in the
>> release.
>>
>>
> I'd prefer to not hold up 1.5.1 for something like this, and would rather
> just follow suite with 1.4. By this, you mean having all CHANGES from 1.4.X
> and 1.5.0 in addition to the 1.5.1 changes, correct? Is this acceptable to
> everyone? I know there were other suggestions made and don't want to
> prematurely squash discussion.
>
I was thinking taking the 1.5.0 changes file and adding the 1.5.1 stuff to
it. If we did anything w/ 1.4, we would would only want to take 1.4.0
changes and add that after 1.5.0. Not all changes in 1.4.[1.2.3.4] are in
1.5 series and any changes that are in both are hopefully marked properly
in jira and already in the 1.5.X list. Since the 1.4.0 changes were not
listed in 1.5.0, I am not neutral on adding that in 1.5.1.
>
> For 1.6.0, I would be happy to play around with some static-content
> generation tools (I like jekyll[1], personally, but I'll have to try out a
> few for our needs. We could even try to reuse the ASF CMS codebase) and see
> if we can get a markdown-generated document going that we can create a nice
> release-notes page from.
>
> [1] http://jekyllrb.com/
>
Re: [DISCUSS] CHANGES Documents
Posted by Josh Elser <jo...@gmail.com>.
On 2/20/14, 10:00 AM, Keith Turner wrote:
> On Thu, Feb 20, 2014 at 1:10 AM, Sean Busbey<bu...@cloudera.com>wrote:
>
>> >On Wed, Feb 19, 2014 at 10:33 PM, Christopher<ct...@apache.org> wrote:
>> >
>>> > >
>>> > >value people are actually getting from this file. I strongly suspect
>>> > >that, if anything, people just want to know the simple answers "What's
>>> > >New?" and "Does this fix my bug yet?" questions, and I don't think
>>> > >this file answers either of those questions well in any of the
>>> > >previous releases. Nor do I think this format lends itself easily to
>>> > >answering those questions. A per-release "Release Notes" section on
>>> > >the website would probably be more useful for that purpose, with a
>>> > >footnote reference to SCM/JIRA for the full list of changes. But, is
>>> > >there another role the CHANGES file is expected to play which I'm
>>> > >overlooking?
>>> > >
>> >
>> >
>> >The main one I can think of is "Will this break my already working system
>> >in some other way?"
>> >
>> >So in addition to your two above major areas, I'd say a section on known
>> >backwards incompatible changes[1] would cover things.
>> >
> I would really like to see this type of information called out in release
> notes.
Agreed
> There have been a lot of good ideas mentioned. What do we want to do for
> 1.5.1? I would not be opposed to waiting a few days on the 1.5.1 release
> if someone wants to create nice user friendly release notes. Or for 1.5.1
> we could just continue to do what was done for 1.4.X releases. For 1.6.0
> I think we should create a user friendly summary of whats important in the
> release.
>
I'd prefer to not hold up 1.5.1 for something like this, and would
rather just follow suite with 1.4. By this, you mean having all CHANGES
from 1.4.X and 1.5.0 in addition to the 1.5.1 changes, correct? Is this
acceptable to everyone? I know there were other suggestions made and
don't want to prematurely squash discussion.
For 1.6.0, I would be happy to play around with some static-content
generation tools (I like jekyll[1], personally, but I'll have to try out
a few for our needs. We could even try to reuse the ASF CMS codebase)
and see if we can get a markdown-generated document going that we can
create a nice release-notes page from.
[1] http://jekyllrb.com/
Re: [DISCUSS] CHANGES Documents
Posted by Sean Busbey <bu...@cloudera.com>.
On Feb 21, 2014 3:22 PM, "Josh Elser" <jo...@gmail.com> wrote:
>
> On 2/20/14, 2:33 PM, Christopher wrote:
>>
>> I think for 1.5.1, it is sufficient to include a section of 1.5.1
>> changes, followed by 1.5.0 changes. I think tasks, tests, and
>> sub-tasks should be excluded from this list entirely. In the future,
>> we can devote more time to ensuring summaries are more useful, but I
>> wouldn't concern ourselves with that today, for 1.5.1. One thing I do
>> want to do for 1.5.1 (and will do immediately after composing this),
>> is update those issues I mentioned which are currently labeled as "New
>> Feature", which should be labeled "Improvement".
>
>
> Talked to Christopher on IRC to ask if he'd be ok with leaving in all
issue types (or only excluding sub-tasks) for 1.5.1 and revisiting at a
later point:
>
> "Sure. I would also accept not removing anything, at this point. While I
prefer not having any of those three things in there, I will not oppose any
RC on that basis."
>
> Given that, I believe we're in agreement to put 1.5.1 changes and then
1.5.0 changes in the CHANGES file. I'll be fixing that, while updating for
the new minor fixes that came out of RC2 and try to prep an RC3.
Sounds good to me.
Re: [DISCUSS] CHANGES Documents
Posted by Josh Elser <jo...@gmail.com>.
On 2/20/14, 2:33 PM, Christopher wrote:
> I think for 1.5.1, it is sufficient to include a section of 1.5.1
> changes, followed by 1.5.0 changes. I think tasks, tests, and
> sub-tasks should be excluded from this list entirely. In the future,
> we can devote more time to ensuring summaries are more useful, but I
> wouldn't concern ourselves with that today, for 1.5.1. One thing I do
> want to do for 1.5.1 (and will do immediately after composing this),
> is update those issues I mentioned which are currently labeled as "New
> Feature", which should be labeled "Improvement".
Talked to Christopher on IRC to ask if he'd be ok with leaving in all
issue types (or only excluding sub-tasks) for 1.5.1 and revisiting at a
later point:
"Sure. I would also accept not removing anything, at this point. While I
prefer not having any of those three things in there, I will not oppose
any RC on that basis."
Given that, I believe we're in agreement to put 1.5.1 changes and then
1.5.0 changes in the CHANGES file. I'll be fixing that, while updating
for the new minor fixes that came out of RC2 and try to prep an RC3.
Re: [DISCUSS] CHANGES Documents
Posted by Christopher <ct...@apache.org>.
On Thu, Feb 20, 2014 at 1:00 PM, Keith Turner <ke...@deenlo.com> wrote:
> On Thu, Feb 20, 2014 at 1:10 AM, Sean Busbey <bu...@cloudera.com>wrote:
>
>> On Wed, Feb 19, 2014 at 10:33 PM, Christopher <ct...@apache.org> wrote:
>>
>> >
>> > value people are actually getting from this file. I strongly suspect
>> > that, if anything, people just want to know the simple answers "What's
>> > New?" and "Does this fix my bug yet?" questions, and I don't think
>> > this file answers either of those questions well in any of the
>> > previous releases. Nor do I think this format lends itself easily to
>> > answering those questions. A per-release "Release Notes" section on
>> > the website would probably be more useful for that purpose, with a
>> > footnote reference to SCM/JIRA for the full list of changes. But, is
>> > there another role the CHANGES file is expected to play which I'm
>> > overlooking?
>> >
>>
>>
>> The main one I can think of is "Will this break my already working system
>> in some other way?"
>>
>> So in addition to your two above major areas, I'd say a section on known
>> backwards incompatible changes[1] would cover things.
>>
>
> I would really like to see this type of information called out in release
> notes.
>
> There have been a lot of good ideas mentioned. What do we want to do for
> 1.5.1? I would not be opposed to waiting a few days on the 1.5.1 release
> if someone wants to create nice user friendly release notes. Or for 1.5.1
> we could just continue to do what was done for 1.4.X releases. For 1.6.0
> I think we should create a user friendly summary of whats important in the
> release.
I think for 1.5.1, it is sufficient to include a section of 1.5.1
changes, followed by 1.5.0 changes. I think tasks, tests, and
sub-tasks should be excluded from this list entirely. In the future,
we can devote more time to ensuring summaries are more useful, but I
wouldn't concern ourselves with that today, for 1.5.1. One thing I do
want to do for 1.5.1 (and will do immediately after composing this),
is update those issues I mentioned which are currently labeled as "New
Feature", which should be labeled "Improvement".
I think we should make it a point to create a release notes html page
for each release, linked on the download page instead of the CHANGES
file, since they seem to serve different purposes. I think the release
notes should contain the things which people have suggested throughout
this thread, such as: prominent features, major bug fixes, and
incompatibility notices, upgrade information, and known bugs that we
may discover shortly after release. This document does not need to be
final, and can be updated at any time (pre-release, after vote, after
we find a major bug 3 months from now, whenever).
--
Christopher L Tubbs II
http://gravatar.com/ctubbsii
Re: [DISCUSS] CHANGES Documents
Posted by Keith Turner <ke...@deenlo.com>.
On Thu, Feb 20, 2014 at 1:10 AM, Sean Busbey <bu...@cloudera.com>wrote:
> On Wed, Feb 19, 2014 at 10:33 PM, Christopher <ct...@apache.org> wrote:
>
> >
> > value people are actually getting from this file. I strongly suspect
> > that, if anything, people just want to know the simple answers "What's
> > New?" and "Does this fix my bug yet?" questions, and I don't think
> > this file answers either of those questions well in any of the
> > previous releases. Nor do I think this format lends itself easily to
> > answering those questions. A per-release "Release Notes" section on
> > the website would probably be more useful for that purpose, with a
> > footnote reference to SCM/JIRA for the full list of changes. But, is
> > there another role the CHANGES file is expected to play which I'm
> > overlooking?
> >
>
>
> The main one I can think of is "Will this break my already working system
> in some other way?"
>
> So in addition to your two above major areas, I'd say a section on known
> backwards incompatible changes[1] would cover things.
>
I would really like to see this type of information called out in release
notes.
There have been a lot of good ideas mentioned. What do we want to do for
1.5.1? I would not be opposed to waiting a few days on the 1.5.1 release
if someone wants to create nice user friendly release notes. Or for 1.5.1
we could just continue to do what was done for 1.4.X releases. For 1.6.0
I think we should create a user friendly summary of whats important in the
release.
> I agree that a section on the website would be more broadly useful than in
> the distribution (esp if we're authoring this rather than generating it via
> jira). I think it would be beneficial, however, to use Markdown in the CMS
> to author and then include that file directly in the distro as a snapshot
> for those offline. Authoring in the CMS would hopefully also encourage us
> to update the document incrementally rather than making the release manager
> handle it at the end.
>
> The more I reread this thread, the more I like the release notes described
> by Eric[2].
>
> -Sean
>
> [1]: To the public API, at a minimum. I think there are a few other things
> that practically speaking we should also call out, like changes to implicit
> configuration via defaults, the core iterators, or the Constraint
> interface.
>
> [2]: http://s.apache.org/ih9
>
Re: [DISCUSS] CHANGES Documents
Posted by Sean Busbey <bu...@cloudera.com>.
On Thu, Feb 20, 2014 at 1:20 AM, Sean Busbey <bu...@cloudera.com>wrote:
>
> On Thu, Feb 20, 2014 at 12:32 AM, Josh Elser <jo...@gmail.com> wrote:
>
>>
>>
>>> The more I reread this thread, the more I like the release notes
>>> described
>>> by Eric[2].
>>>
>>
>> While I agree that would be nice, I don't know of a quantitative way to
>> determine that. Is "critical" categorized by some Jira priority? Do we end
>> up omitting something that someone wanted? I feel like we should just
>> bundle all changes for that release or none at that point.
>>
>>
> We're the Accumulo community, we should be cognizant of what changes are
> most likely to impact downstream users. After all, isn't that part of how
> we define a public API in the first place?
>
>
As an illustrative example, consider ACCUMULO-1572. Losing all the roles
attached to a ZK server when it goes down is going to burn any production
deployment of sufficient age. Users will fall into two camps: those already
implementing a workaround (e.g. a watchdog that restarts Accumulo
processes) and those who have gotten lucky.
The latter will most definitely want to hear about this fix in consumable
release notes. Depending on the overhead caused to those in the first camp,
they likely will also be interested. Even if we just started by filtering
based on priority, picking this issue out of the 22 BLOCKER/CRITICAL is
much more reasonable then out of the full list of 144 Closed/Resolved Bug
issues included for 1.5.1.
Re: [DISCUSS] CHANGES Documents
Posted by Sean Busbey <bu...@cloudera.com>.
On Thu, Feb 20, 2014 at 12:32 AM, Josh Elser <jo...@gmail.com> wrote:
>
>
> On 2/19/14, 10:10 PM, Sean Busbey wrote:
>
>> On Wed, Feb 19, 2014 at 10:33 PM, Christopher <ct...@apache.org>
>> wrote:
>>
>>
>>> value people are actually getting from this file. I strongly suspect
>>> that, if anything, people just want to know the simple answers "What's
>>> New?" and "Does this fix my bug yet?" questions, and I don't think
>>> this file answers either of those questions well in any of the
>>> previous releases. Nor do I think this format lends itself easily to
>>> answering those questions. A per-release "Release Notes" section on
>>> the website would probably be more useful for that purpose, with a
>>> footnote reference to SCM/JIRA for the full list of changes. But, is
>>> there another role the CHANGES file is expected to play which I'm
>>> overlooking?
>>>
>>>
>>
>> The main one I can think of is "Will this break my already working system
>> in some other way?"
>>
>
> I would think that something like an UPGRADE or any sort of document would
> be better served for this. Any other time, there shouldn't be anything
> required.
>
>
We allow incompatible changes outside of the public API on minor/bugfix
versions. Some of those changes can easily impact people building on
Accumulo (such as changes to core iterators). We should call those things
out.
For incompatibilities since the previous major version, I don't really care
if we break things out in an UPGRADE document or add them to the CHANGES
file directly (provided the CHANGES file has a note that the UPGRADE
document contains those kinds of considerations).
>
> So in addition to your two above major areas, I'd say a section on known
>> backwards incompatible changes[1] would cover things.
>>
>> I agree that a section on the website would be more broadly useful than in
>> the distribution (esp if we're authoring this rather than generating it
>> via
>> jira). I think it would be beneficial, however, to use Markdown in the CMS
>> to author and then include that file directly in the distro as a snapshot
>> for those offline. Authoring in the CMS would hopefully also encourage us
>> to update the document incrementally rather than making the release
>> manager
>> handle it at the end.
>>
>> The more I reread this thread, the more I like the release notes described
>> by Eric[2].
>>
>
> While I agree that would be nice, I don't know of a quantitative way to
> determine that. Is "critical" categorized by some Jira priority? Do we end
> up omitting something that someone wanted? I feel like we should just
> bundle all changes for that release or none at that point.
>
>
We're the Accumulo community, we should be cognizant of what changes are
most likely to impact downstream users. After all, isn't that part of how
we define a public API in the first place?
Ideally, I'd say the jira priorities of CRITICAL and BLOCKER would capture
them. I wouldn't want to make that a requirement. Basically, just use lazy
consensus like we do for most other things.
Re: [DISCUSS] CHANGES Documents
Posted by Josh Elser <jo...@gmail.com>.
On 2/19/14, 10:10 PM, Sean Busbey wrote:
> On Wed, Feb 19, 2014 at 10:33 PM, Christopher <ct...@apache.org> wrote:
>
>>
>> value people are actually getting from this file. I strongly suspect
>> that, if anything, people just want to know the simple answers "What's
>> New?" and "Does this fix my bug yet?" questions, and I don't think
>> this file answers either of those questions well in any of the
>> previous releases. Nor do I think this format lends itself easily to
>> answering those questions. A per-release "Release Notes" section on
>> the website would probably be more useful for that purpose, with a
>> footnote reference to SCM/JIRA for the full list of changes. But, is
>> there another role the CHANGES file is expected to play which I'm
>> overlooking?
>>
>
>
> The main one I can think of is "Will this break my already working system
> in some other way?"
I would think that something like an UPGRADE or any sort of document
would be better served for this. Any other time, there shouldn't be
anything required.
> So in addition to your two above major areas, I'd say a section on known
> backwards incompatible changes[1] would cover things.
>
> I agree that a section on the website would be more broadly useful than in
> the distribution (esp if we're authoring this rather than generating it via
> jira). I think it would be beneficial, however, to use Markdown in the CMS
> to author and then include that file directly in the distro as a snapshot
> for those offline. Authoring in the CMS would hopefully also encourage us
> to update the document incrementally rather than making the release manager
> handle it at the end.
>
> The more I reread this thread, the more I like the release notes described
> by Eric[2].
While I agree that would be nice, I don't know of a quantitative way to
determine that. Is "critical" categorized by some Jira priority? Do we
end up omitting something that someone wanted? I feel like we should
just bundle all changes for that release or none at that point.
>
> -Sean
>
> [1]: To the public API, at a minimum. I think there are a few other things
> that practically speaking we should also call out, like changes to implicit
> configuration via defaults, the core iterators, or the Constraint interface.
>
> [2]: http://s.apache.org/ih9
>
Re: [DISCUSS] CHANGES Documents
Posted by Sean Busbey <bu...@cloudera.com>.
On Wed, Feb 19, 2014 at 10:33 PM, Christopher <ct...@apache.org> wrote:
>
> value people are actually getting from this file. I strongly suspect
> that, if anything, people just want to know the simple answers "What's
> New?" and "Does this fix my bug yet?" questions, and I don't think
> this file answers either of those questions well in any of the
> previous releases. Nor do I think this format lends itself easily to
> answering those questions. A per-release "Release Notes" section on
> the website would probably be more useful for that purpose, with a
> footnote reference to SCM/JIRA for the full list of changes. But, is
> there another role the CHANGES file is expected to play which I'm
> overlooking?
>
The main one I can think of is "Will this break my already working system
in some other way?"
So in addition to your two above major areas, I'd say a section on known
backwards incompatible changes[1] would cover things.
I agree that a section on the website would be more broadly useful than in
the distribution (esp if we're authoring this rather than generating it via
jira). I think it would be beneficial, however, to use Markdown in the CMS
to author and then include that file directly in the distro as a snapshot
for those offline. Authoring in the CMS would hopefully also encourage us
to update the document incrementally rather than making the release manager
handle it at the end.
The more I reread this thread, the more I like the release notes described
by Eric[2].
-Sean
[1]: To the public API, at a minimum. I think there are a few other things
that practically speaking we should also call out, like changes to implicit
configuration via defaults, the core iterators, or the Constraint interface.
[2]: http://s.apache.org/ih9
Re: [DISCUSS] CHANGES Documents
Posted by Christopher <ct...@apache.org>.
I agree with that a short list would be more valuable to readers.
Further, I do not think a comprehensive history of changes would be in
any way beneficial, nor do I think sub-tickets, tests, or tasks, are
beneficial to report. By including this comprehensive list, we're also
making a lot of assumptions about the value of the issue summary to
users, and I'm not so certain that's enough information, in the
general case, to be meaningful to users without requiring them to
cross-reference JIRA anyway.
For example, consider these two examples of things labeled "New Feature":
1. [ACCUMULO-1488] - support BigDecimal encoding for basic built-in combiners
2. [ACCUMULO-1960] - agitator should support sudo as well
Aside from the fact that these are probably improvements, not actual
new features, can anybody honestly say that an average user will know
what these are referring to without actually looking them up in JIRA?
I suspect not... and these are listed prominently in the "New Feature"
section... something a user would care about.
However, that said, I think Keith's idea of prepending to the CHANGES
list generated by the tool (perhaps without tasks/tests/sub-tickets),
for each released version, is the simplest way to generate and include
them. (That's what I used for 1.5.0).
It's true that 1.5.0 replaced this file, rather than prepended to
it... I'm not sure if that's something we should follow as a precedent
always, or for significant (non-bugfix) version jumps, or not at all.
I would be concerned about carrying on this practice of always
prepending, especially as we approach 1MB in size or larger. Our
tickets are now in the thousands, and the file size could easily grow
out of control. This file certainly won't be of much value if it's too
large to open in a minimal text editor like Notepad.exe (which, in
some versions has a limit of 54KB file size).
However, every 1.5.0 release candidate replaced this file instead of
preserving the history of prior release changes, and nobody noticed
until within this last week, so that might say something about the
value people are actually getting from this file. I strongly suspect
that, if anything, people just want to know the simple answers "What's
New?" and "Does this fix my bug yet?" questions, and I don't think
this file answers either of those questions well in any of the
previous releases. Nor do I think this format lends itself easily to
answering those questions. A per-release "Release Notes" section on
the website would probably be more useful for that purpose, with a
footnote reference to SCM/JIRA for the full list of changes. But, is
there another role the CHANGES file is expected to play which I'm
overlooking?
--
Christopher L Tubbs II
http://gravatar.com/ctubbsii
On Wed, Feb 19, 2014 at 4:53 PM, Eric Newton <er...@gmail.com> wrote:
> I think generated CHANGES files are a disservice to the reader.
>
> A short list of the major differences from the last release should be given.
>
> For a bug release, a short list of the critical bugs should be given after
> the .0 release.
>
> So, 1.4.1 would list the 1.4.0 features, and the critical bugs that caused
> the 1.4.1 release to be made.
> 1.4.2 would list 1.4.0 features, 1.4.1 and 1.4.2 critical bug fixes.
>
> Basically, I want to quickly understand if I should upgrade (or not).
>
> If people want the full list, they can get it from JIRA.
>
> I would also be fine with a CHANGES file with a URL reference to JIRA.
>
> I personally would not down-vote a release because it has an accurate
> CHANGES file, but not the content I think it should have.
>
> -Eric
>
>
>
> On Wed, Feb 19, 2014 at 4:30 PM, Josh Elser <jo...@gmail.com> wrote:
>
>> The CHANGES document that is included in an Accumulo release contains some
>> set of changes from a previous release which presently contain the
>> following information:
>>
>> 1) Issue Type (Task, Bug, Feature, etc)
>> 2) Issue Number (ACCUMULO-1234)
>> 3) Issue Subject
>>
>> There have been various preferences expressed, primarily over IRC, on
>> which changes should be contained and how they should be formatted. The
>> largest consensus, and what I believe we should do, is as follows:
>>
>> Entries in a CHANGES file should contain issues, delimited by minor
>> version within the major version[1], grouped by issue type. The minor
>> version changes sorted be sorted in reverse order (e.g. 1.5.2, 1.5.1, then
>> 1.5.0). Changes from the previous major version (e.g. 1.4.x) would *not* be
>> included in this CHANGES file.
>>
>> Opinions? The results of this discussion will be documented on the
>> release-making page[2] of the website for future reference.
>>
>> - Josh
>>
>> [1] Major and minor version here is referred to as Y and Z of version
>> strings of the form: X.Y.Z (not as prescribed by semver, proper)
>> [2] http://accumulo.apache.org/releasing.html
>>
Re: [DISCUSS] CHANGES Documents
Posted by Keith Turner <ke...@deenlo.com>.
On Wed, Feb 19, 2014 at 4:53 PM, Eric Newton <er...@gmail.com> wrote:
> I think generated CHANGES files are a disservice to the reader.
>
> A short list of the major differences from the last release should be
> given.
>
It would be nice to create a better release notes. I was poking around on
the web reading about release notes. These android release notes[1] are an
example of summarizing whats in the release in a nice way. Seems very user
friendly. For example the decision to not support RFC2549 is communicated
very clearly to the user.
[1] http://developer.android.com/sdk/RELEASENOTES.html
>
> For a bug release, a short list of the critical bugs should be given after
> the .0 release.
>
> So, 1.4.1 would list the 1.4.0 features, and the critical bugs that caused
> the 1.4.1 release to be made.
> 1.4.2 would list 1.4.0 features, 1.4.1 and 1.4.2 critical bug fixes.
>
> Basically, I want to quickly understand if I should upgrade (or not).
>
> If people want the full list, they can get it from JIRA.
>
> I would also be fine with a CHANGES file with a URL reference to JIRA.
>
One problem w/ this is that over time the link may stop working. Software
can be used for many years after release. I do not think that we need stop
including whats generated from jira if we also produce nice user friendly
release notes. I think both are appropriate for different audiences.
>
> I personally would not down-vote a release because it has an accurate
> CHANGES file, but not the content I think it should have.
>
> -Eric
>
>
>
> On Wed, Feb 19, 2014 at 4:30 PM, Josh Elser <jo...@gmail.com> wrote:
>
> > The CHANGES document that is included in an Accumulo release contains
> some
> > set of changes from a previous release which presently contain the
> > following information:
> >
> > 1) Issue Type (Task, Bug, Feature, etc)
> > 2) Issue Number (ACCUMULO-1234)
> > 3) Issue Subject
> >
> > There have been various preferences expressed, primarily over IRC, on
> > which changes should be contained and how they should be formatted. The
> > largest consensus, and what I believe we should do, is as follows:
> >
> > Entries in a CHANGES file should contain issues, delimited by minor
> > version within the major version[1], grouped by issue type. The minor
> > version changes sorted be sorted in reverse order (e.g. 1.5.2, 1.5.1,
> then
> > 1.5.0). Changes from the previous major version (e.g. 1.4.x) would *not*
> be
> > included in this CHANGES file.
> >
> > Opinions? The results of this discussion will be documented on the
> > release-making page[2] of the website for future reference.
> >
> > - Josh
> >
> > [1] Major and minor version here is referred to as Y and Z of version
> > strings of the form: X.Y.Z (not as prescribed by semver, proper)
> > [2] http://accumulo.apache.org/releasing.html
> >
>
Re: [DISCUSS] CHANGES Documents
Posted by Eric Newton <er...@gmail.com>.
I think generated CHANGES files are a disservice to the reader.
A short list of the major differences from the last release should be given.
For a bug release, a short list of the critical bugs should be given after
the .0 release.
So, 1.4.1 would list the 1.4.0 features, and the critical bugs that caused
the 1.4.1 release to be made.
1.4.2 would list 1.4.0 features, 1.4.1 and 1.4.2 critical bug fixes.
Basically, I want to quickly understand if I should upgrade (or not).
If people want the full list, they can get it from JIRA.
I would also be fine with a CHANGES file with a URL reference to JIRA.
I personally would not down-vote a release because it has an accurate
CHANGES file, but not the content I think it should have.
-Eric
On Wed, Feb 19, 2014 at 4:30 PM, Josh Elser <jo...@gmail.com> wrote:
> The CHANGES document that is included in an Accumulo release contains some
> set of changes from a previous release which presently contain the
> following information:
>
> 1) Issue Type (Task, Bug, Feature, etc)
> 2) Issue Number (ACCUMULO-1234)
> 3) Issue Subject
>
> There have been various preferences expressed, primarily over IRC, on
> which changes should be contained and how they should be formatted. The
> largest consensus, and what I believe we should do, is as follows:
>
> Entries in a CHANGES file should contain issues, delimited by minor
> version within the major version[1], grouped by issue type. The minor
> version changes sorted be sorted in reverse order (e.g. 1.5.2, 1.5.1, then
> 1.5.0). Changes from the previous major version (e.g. 1.4.x) would *not* be
> included in this CHANGES file.
>
> Opinions? The results of this discussion will be documented on the
> release-making page[2] of the website for future reference.
>
> - Josh
>
> [1] Major and minor version here is referred to as Y and Z of version
> strings of the form: X.Y.Z (not as prescribed by semver, proper)
> [2] http://accumulo.apache.org/releasing.html
>
Re: [DISCUSS] CHANGES Documents
Posted by Sean Busbey <bu...@cloudera.com>.
I'd prefer it if the CHANGES document included all changes, as they do in
Avro and Jackson[1]. For those who just get a distribution dropped on them,
it provides a very useful short way of tracking lots of info. Not everyone
can get to the source repo readily.
In this case the CHANGES file also then serves as an easy way of tracking
which minor versions of a previous major version are included in the
current major version.
This is especially true if users are cut off from the Internet and are
looking to upgrade from an older version.
Marginally related: I'd really like us to add a call out section for
backwards incompatible changes. (including from X.Y to X.Y+1)
[1]: http://svn.codehaus.org/jackson/tags/1.8/1.8.9/release-notes/VERSION
https://github.com/apache/avro/blob/trunk/CHANGES.txt
-Sean
On Wed, Feb 19, 2014 at 3:49 PM, Mike Drob <ma...@cloudera.com> wrote:
> I'd be happy with the solution described.
>
>
> I saw a project _somewhere_ using a way more detailed release notes style,
> of the format:
>
> [issue key] [priority] [issue type] reported by [reporter], resolved by
> [assignee]
> [summary]
>
> But that might be too verbose and I can't find it again anyway.
>
> Mike
>
>
> On Wed, Feb 19, 2014 at 4:30 PM, Josh Elser <jo...@gmail.com> wrote:
>
> > The CHANGES document that is included in an Accumulo release contains
> some
> > set of changes from a previous release which presently contain the
> > following information:
> >
> > 1) Issue Type (Task, Bug, Feature, etc)
> > 2) Issue Number (ACCUMULO-1234)
> > 3) Issue Subject
> >
> > There have been various preferences expressed, primarily over IRC, on
> > which changes should be contained and how they should be formatted. The
> > largest consensus, and what I believe we should do, is as follows:
> >
> > Entries in a CHANGES file should contain issues, delimited by minor
> > version within the major version[1], grouped by issue type. The minor
> > version changes sorted be sorted in reverse order (e.g. 1.5.2, 1.5.1,
> then
> > 1.5.0). Changes from the previous major version (e.g. 1.4.x) would *not*
> be
> > included in this CHANGES file.
> >
> > Opinions? The results of this discussion will be documented on the
> > release-making page[2] of the website for future reference.
> >
> > - Josh
> >
> > [1] Major and minor version here is referred to as Y and Z of version
> > strings of the form: X.Y.Z (not as prescribed by semver, proper)
> > [2] http://accumulo.apache.org/releasing.html
> >
>
Re: [DISCUSS] CHANGES Documents
Posted by Mike Drob <ma...@cloudera.com>.
I'd be happy with the solution described.
I saw a project _somewhere_ using a way more detailed release notes style,
of the format:
[issue key] [priority] [issue type] reported by [reporter], resolved by
[assignee]
[summary]
But that might be too verbose and I can't find it again anyway.
Mike
On Wed, Feb 19, 2014 at 4:30 PM, Josh Elser <jo...@gmail.com> wrote:
> The CHANGES document that is included in an Accumulo release contains some
> set of changes from a previous release which presently contain the
> following information:
>
> 1) Issue Type (Task, Bug, Feature, etc)
> 2) Issue Number (ACCUMULO-1234)
> 3) Issue Subject
>
> There have been various preferences expressed, primarily over IRC, on
> which changes should be contained and how they should be formatted. The
> largest consensus, and what I believe we should do, is as follows:
>
> Entries in a CHANGES file should contain issues, delimited by minor
> version within the major version[1], grouped by issue type. The minor
> version changes sorted be sorted in reverse order (e.g. 1.5.2, 1.5.1, then
> 1.5.0). Changes from the previous major version (e.g. 1.4.x) would *not* be
> included in this CHANGES file.
>
> Opinions? The results of this discussion will be documented on the
> release-making page[2] of the website for future reference.
>
> - Josh
>
> [1] Major and minor version here is referred to as Y and Z of version
> strings of the form: X.Y.Z (not as prescribed by semver, proper)
> [2] http://accumulo.apache.org/releasing.html
>
Re: [DISCUSS] CHANGES Documents
Posted by Josh Elser <jo...@gmail.com>.
On 2/20/14, 9:31 AM, Keith Turner wrote:
> On Wed, Feb 19, 2014 at 9:18 PM, Sean Busbey<bu...@cloudera.com>wrote:
>
>> >I think excluding tickets that aren't resolved is a good idea, but we'll
>> >need to document that there may be commits that reference issues not
>> >present in CHANGES because we are CtR.
>> >
>
> I think that if an issue has commits against it should be marked for the
> release and closed. If needed edit the issue to align with what was
> commited and open follow on issues if needed.
>
Yeah, I think you're right. It's much easier to ensure that Jira is the
ultimate source of correctness for what fixes/improvements/etc are
contained in a release. Much easier to query Jira than try to guess at
what extra should be added.
Re: [DISCUSS] CHANGES Documents
Posted by Keith Turner <ke...@deenlo.com>.
On Thu, Feb 20, 2014 at 12:36 PM, Mike Drob <ma...@cloudera.com> wrote:
> On Thu, Feb 20, 2014 at 12:31 PM, Keith Turner <ke...@deenlo.com> wrote:
>
> > On Wed, Feb 19, 2014 at 9:18 PM, Sean Busbey <busbey+lists@cloudera.com
> > >wrote:
> >
> > > I think excluding tickets that aren't resolved is a good idea, but
> we'll
> > > need to document that there may be commits that reference issues not
> > > present in CHANGES because we are CtR.
> > >
> >
> >
> > I think that if an issue has commits against it should be marked for the
> > release and closed. If needed edit the issue to align with what was
> > commited and open follow on issues if needed.
> >
> > +1
>
> My reasoning behind this that I rely on jira to understand whats in a
release. Maybe this is a flawed approach on my part and using the git
logs would be better. Even so I would still like the keep whats in jira as
sane as possible.
> >
> > > On Feb 19, 2014 7:01 PM, "Josh Elser" <jo...@gmail.com> wrote:
> > >
> > > > One extra thing: in the CHANGES that I generated, I excluded any
> > tickets
> > > > that didn't have a status of "Closed" or "Resolved".
> > > >
> > > > Not sure what people think about that.
> > > >
> > > > On 2/19/14, 1:30 PM, Josh Elser wrote:
> > > >
> > > >> The CHANGES document that is included in an Accumulo release
> contains
> > > >> some set of changes from a previous release which presently contain
> > the
> > > >> following information:
> > > >>
> > > >> 1) Issue Type (Task, Bug, Feature, etc)
> > > >> 2) Issue Number (ACCUMULO-1234)
> > > >> 3) Issue Subject
> > > >>
> > > >> There have been various preferences expressed, primarily over IRC,
> on
> > > >> which changes should be contained and how they should be formatted.
> > The
> > > >> largest consensus, and what I believe we should do, is as follows:
> > > >>
> > > >> Entries in a CHANGES file should contain issues, delimited by minor
> > > >> version within the major version[1], grouped by issue type. The
> minor
> > > >> version changes sorted be sorted in reverse order (e.g. 1.5.2,
> 1.5.1,
> > > >> then 1.5.0). Changes from the previous major version (e.g. 1.4.x)
> > would
> > > >> *not* be included in this CHANGES file.
> > > >>
> > > >> Opinions? The results of this discussion will be documented on the
> > > >> release-making page[2] of the website for future reference.
> > > >>
> > > >> - Josh
> > > >>
> > > >> [1] Major and minor version here is referred to as Y and Z of
> version
> > > >> strings of the form: X.Y.Z (not as prescribed by semver, proper)
> > > >> [2] http://accumulo.apache.org/releasing.html
> > > >>
> > > >
> > >
> >
>
Re: [DISCUSS] CHANGES Documents
Posted by Mike Drob <ma...@cloudera.com>.
On Thu, Feb 20, 2014 at 12:31 PM, Keith Turner <ke...@deenlo.com> wrote:
> On Wed, Feb 19, 2014 at 9:18 PM, Sean Busbey <busbey+lists@cloudera.com
> >wrote:
>
> > I think excluding tickets that aren't resolved is a good idea, but we'll
> > need to document that there may be commits that reference issues not
> > present in CHANGES because we are CtR.
> >
>
>
> I think that if an issue has commits against it should be marked for the
> release and closed. If needed edit the issue to align with what was
> commited and open follow on issues if needed.
>
> +1
>
> > On Feb 19, 2014 7:01 PM, "Josh Elser" <jo...@gmail.com> wrote:
> >
> > > One extra thing: in the CHANGES that I generated, I excluded any
> tickets
> > > that didn't have a status of "Closed" or "Resolved".
> > >
> > > Not sure what people think about that.
> > >
> > > On 2/19/14, 1:30 PM, Josh Elser wrote:
> > >
> > >> The CHANGES document that is included in an Accumulo release contains
> > >> some set of changes from a previous release which presently contain
> the
> > >> following information:
> > >>
> > >> 1) Issue Type (Task, Bug, Feature, etc)
> > >> 2) Issue Number (ACCUMULO-1234)
> > >> 3) Issue Subject
> > >>
> > >> There have been various preferences expressed, primarily over IRC, on
> > >> which changes should be contained and how they should be formatted.
> The
> > >> largest consensus, and what I believe we should do, is as follows:
> > >>
> > >> Entries in a CHANGES file should contain issues, delimited by minor
> > >> version within the major version[1], grouped by issue type. The minor
> > >> version changes sorted be sorted in reverse order (e.g. 1.5.2, 1.5.1,
> > >> then 1.5.0). Changes from the previous major version (e.g. 1.4.x)
> would
> > >> *not* be included in this CHANGES file.
> > >>
> > >> Opinions? The results of this discussion will be documented on the
> > >> release-making page[2] of the website for future reference.
> > >>
> > >> - Josh
> > >>
> > >> [1] Major and minor version here is referred to as Y and Z of version
> > >> strings of the form: X.Y.Z (not as prescribed by semver, proper)
> > >> [2] http://accumulo.apache.org/releasing.html
> > >>
> > >
> >
>
Re: [DISCUSS] CHANGES Documents
Posted by Keith Turner <ke...@deenlo.com>.
On Wed, Feb 19, 2014 at 9:18 PM, Sean Busbey <bu...@cloudera.com>wrote:
> I think excluding tickets that aren't resolved is a good idea, but we'll
> need to document that there may be commits that reference issues not
> present in CHANGES because we are CtR.
>
I think that if an issue has commits against it should be marked for the
release and closed. If needed edit the issue to align with what was
commited and open follow on issues if needed.
> On Feb 19, 2014 7:01 PM, "Josh Elser" <jo...@gmail.com> wrote:
>
> > One extra thing: in the CHANGES that I generated, I excluded any tickets
> > that didn't have a status of "Closed" or "Resolved".
> >
> > Not sure what people think about that.
> >
> > On 2/19/14, 1:30 PM, Josh Elser wrote:
> >
> >> The CHANGES document that is included in an Accumulo release contains
> >> some set of changes from a previous release which presently contain the
> >> following information:
> >>
> >> 1) Issue Type (Task, Bug, Feature, etc)
> >> 2) Issue Number (ACCUMULO-1234)
> >> 3) Issue Subject
> >>
> >> There have been various preferences expressed, primarily over IRC, on
> >> which changes should be contained and how they should be formatted. The
> >> largest consensus, and what I believe we should do, is as follows:
> >>
> >> Entries in a CHANGES file should contain issues, delimited by minor
> >> version within the major version[1], grouped by issue type. The minor
> >> version changes sorted be sorted in reverse order (e.g. 1.5.2, 1.5.1,
> >> then 1.5.0). Changes from the previous major version (e.g. 1.4.x) would
> >> *not* be included in this CHANGES file.
> >>
> >> Opinions? The results of this discussion will be documented on the
> >> release-making page[2] of the website for future reference.
> >>
> >> - Josh
> >>
> >> [1] Major and minor version here is referred to as Y and Z of version
> >> strings of the form: X.Y.Z (not as prescribed by semver, proper)
> >> [2] http://accumulo.apache.org/releasing.html
> >>
> >
>
Re: [DISCUSS] CHANGES Documents
Posted by Josh Elser <jo...@gmail.com>.
For clarity, tickets that aren't Closed or Resolved are (typically for
us) Duplicate, Invalid, Won't Fix, etc.
On 2/19/14, 6:18 PM, Sean Busbey wrote:
> I think excluding tickets that aren't resolved is a good idea, but we'll
> need to document that there may be commits that reference issues not
> present in CHANGES because we are CtR.
> On Feb 19, 2014 7:01 PM, "Josh Elser" <jo...@gmail.com> wrote:
>
>> One extra thing: in the CHANGES that I generated, I excluded any tickets
>> that didn't have a status of "Closed" or "Resolved".
>>
>> Not sure what people think about that.
>>
>> On 2/19/14, 1:30 PM, Josh Elser wrote:
>>
>>> The CHANGES document that is included in an Accumulo release contains
>>> some set of changes from a previous release which presently contain the
>>> following information:
>>>
>>> 1) Issue Type (Task, Bug, Feature, etc)
>>> 2) Issue Number (ACCUMULO-1234)
>>> 3) Issue Subject
>>>
>>> There have been various preferences expressed, primarily over IRC, on
>>> which changes should be contained and how they should be formatted. The
>>> largest consensus, and what I believe we should do, is as follows:
>>>
>>> Entries in a CHANGES file should contain issues, delimited by minor
>>> version within the major version[1], grouped by issue type. The minor
>>> version changes sorted be sorted in reverse order (e.g. 1.5.2, 1.5.1,
>>> then 1.5.0). Changes from the previous major version (e.g. 1.4.x) would
>>> *not* be included in this CHANGES file.
>>>
>>> Opinions? The results of this discussion will be documented on the
>>> release-making page[2] of the website for future reference.
>>>
>>> - Josh
>>>
>>> [1] Major and minor version here is referred to as Y and Z of version
>>> strings of the form: X.Y.Z (not as prescribed by semver, proper)
>>> [2] http://accumulo.apache.org/releasing.html
>>>
>>
>
Re: [DISCUSS] CHANGES Documents
Posted by Sean Busbey <bu...@cloudera.com>.
I think excluding tickets that aren't resolved is a good idea, but we'll
need to document that there may be commits that reference issues not
present in CHANGES because we are CtR.
On Feb 19, 2014 7:01 PM, "Josh Elser" <jo...@gmail.com> wrote:
> One extra thing: in the CHANGES that I generated, I excluded any tickets
> that didn't have a status of "Closed" or "Resolved".
>
> Not sure what people think about that.
>
> On 2/19/14, 1:30 PM, Josh Elser wrote:
>
>> The CHANGES document that is included in an Accumulo release contains
>> some set of changes from a previous release which presently contain the
>> following information:
>>
>> 1) Issue Type (Task, Bug, Feature, etc)
>> 2) Issue Number (ACCUMULO-1234)
>> 3) Issue Subject
>>
>> There have been various preferences expressed, primarily over IRC, on
>> which changes should be contained and how they should be formatted. The
>> largest consensus, and what I believe we should do, is as follows:
>>
>> Entries in a CHANGES file should contain issues, delimited by minor
>> version within the major version[1], grouped by issue type. The minor
>> version changes sorted be sorted in reverse order (e.g. 1.5.2, 1.5.1,
>> then 1.5.0). Changes from the previous major version (e.g. 1.4.x) would
>> *not* be included in this CHANGES file.
>>
>> Opinions? The results of this discussion will be documented on the
>> release-making page[2] of the website for future reference.
>>
>> - Josh
>>
>> [1] Major and minor version here is referred to as Y and Z of version
>> strings of the form: X.Y.Z (not as prescribed by semver, proper)
>> [2] http://accumulo.apache.org/releasing.html
>>
>
Re: [DISCUSS] CHANGES Documents
Posted by Josh Elser <jo...@gmail.com>.
One extra thing: in the CHANGES that I generated, I excluded any tickets
that didn't have a status of "Closed" or "Resolved".
Not sure what people think about that.
On 2/19/14, 1:30 PM, Josh Elser wrote:
> The CHANGES document that is included in an Accumulo release contains
> some set of changes from a previous release which presently contain the
> following information:
>
> 1) Issue Type (Task, Bug, Feature, etc)
> 2) Issue Number (ACCUMULO-1234)
> 3) Issue Subject
>
> There have been various preferences expressed, primarily over IRC, on
> which changes should be contained and how they should be formatted. The
> largest consensus, and what I believe we should do, is as follows:
>
> Entries in a CHANGES file should contain issues, delimited by minor
> version within the major version[1], grouped by issue type. The minor
> version changes sorted be sorted in reverse order (e.g. 1.5.2, 1.5.1,
> then 1.5.0). Changes from the previous major version (e.g. 1.4.x) would
> *not* be included in this CHANGES file.
>
> Opinions? The results of this discussion will be documented on the
> release-making page[2] of the website for future reference.
>
> - Josh
>
> [1] Major and minor version here is referred to as Y and Z of version
> strings of the form: X.Y.Z (not as prescribed by semver, proper)
> [2] http://accumulo.apache.org/releasing.html
Re: [DISCUSS] CHANGES Documents
Posted by Keith Turner <ke...@deenlo.com>.
On Wed, Feb 19, 2014 at 6:14 PM, Josh Elser <jo...@gmail.com> wrote:
> The 1.5.0 CHANGES does not include 1.4.Z changes.
It should probably include the 1.4.0 changes.
>
>
> On 2/19/14, 3:04 PM, Keith Turner wrote:
>
>> I think we should just take the release notes jira generates for X.Y.Z and
>> prepend them to the CHANGES files with a header saying "Release Notes -
>> Apache Accumulo - Version X.Y.Z". This is what was done for 1.4.[1,2,3,4]
>> and 1.5.0
>>
>> For example the following link will generate 1.4.4 release notes (can
>> change it from HTML to text by pressing "Configure release notes").
>>
>> https://issues.apache.org/jira/secure/ReleaseNote.jspa?
>> version=12324151&styleName=Html&projectId=12312121&Create=Create
>>
>>
>> On Wed, Feb 19, 2014 at 4:30 PM, Josh Elser <jo...@gmail.com> wrote:
>>
>> The CHANGES document that is included in an Accumulo release contains
>>> some
>>> set of changes from a previous release which presently contain the
>>> following information:
>>>
>>> 1) Issue Type (Task, Bug, Feature, etc)
>>> 2) Issue Number (ACCUMULO-1234)
>>> 3) Issue Subject
>>>
>>> There have been various preferences expressed, primarily over IRC, on
>>> which changes should be contained and how they should be formatted. The
>>> largest consensus, and what I believe we should do, is as follows:
>>>
>>> Entries in a CHANGES file should contain issues, delimited by minor
>>> version within the major version[1], grouped by issue type. The minor
>>> version changes sorted be sorted in reverse order (e.g. 1.5.2, 1.5.1,
>>> then
>>> 1.5.0). Changes from the previous major version (e.g. 1.4.x) would *not*
>>> be
>>> included in this CHANGES file.
>>>
>>> Opinions? The results of this discussion will be documented on the
>>> release-making page[2] of the website for future reference.
>>>
>>> - Josh
>>>
>>> [1] Major and minor version here is referred to as Y and Z of version
>>> strings of the form: X.Y.Z (not as prescribed by semver, proper)
>>> [2] http://accumulo.apache.org/releasing.html
>>>
>>>
>>
Re: [DISCUSS] CHANGES Documents
Posted by Josh Elser <jo...@gmail.com>.
The 1.5.0 CHANGES does not include 1.4.Z changes.
On 2/19/14, 3:04 PM, Keith Turner wrote:
> I think we should just take the release notes jira generates for X.Y.Z and
> prepend them to the CHANGES files with a header saying "Release Notes -
> Apache Accumulo - Version X.Y.Z". This is what was done for 1.4.[1,2,3,4]
> and 1.5.0
>
> For example the following link will generate 1.4.4 release notes (can
> change it from HTML to text by pressing "Configure release notes").
>
> https://issues.apache.org/jira/secure/ReleaseNote.jspa?version=12324151&styleName=Html&projectId=12312121&Create=Create
>
>
> On Wed, Feb 19, 2014 at 4:30 PM, Josh Elser <jo...@gmail.com> wrote:
>
>> The CHANGES document that is included in an Accumulo release contains some
>> set of changes from a previous release which presently contain the
>> following information:
>>
>> 1) Issue Type (Task, Bug, Feature, etc)
>> 2) Issue Number (ACCUMULO-1234)
>> 3) Issue Subject
>>
>> There have been various preferences expressed, primarily over IRC, on
>> which changes should be contained and how they should be formatted. The
>> largest consensus, and what I believe we should do, is as follows:
>>
>> Entries in a CHANGES file should contain issues, delimited by minor
>> version within the major version[1], grouped by issue type. The minor
>> version changes sorted be sorted in reverse order (e.g. 1.5.2, 1.5.1, then
>> 1.5.0). Changes from the previous major version (e.g. 1.4.x) would *not* be
>> included in this CHANGES file.
>>
>> Opinions? The results of this discussion will be documented on the
>> release-making page[2] of the website for future reference.
>>
>> - Josh
>>
>> [1] Major and minor version here is referred to as Y and Z of version
>> strings of the form: X.Y.Z (not as prescribed by semver, proper)
>> [2] http://accumulo.apache.org/releasing.html
>>
>
Re: [DISCUSS] CHANGES Documents
Posted by Josh Elser <jo...@gmail.com>.
Also, wow. I had no idea that tool existed. I had to manually create
that file...
On 2/19/14, 3:04 PM, Keith Turner wrote:
> I think we should just take the release notes jira generates for X.Y.Z and
> prepend them to the CHANGES files with a header saying "Release Notes -
> Apache Accumulo - Version X.Y.Z". This is what was done for 1.4.[1,2,3,4]
> and 1.5.0
>
> For example the following link will generate 1.4.4 release notes (can
> change it from HTML to text by pressing "Configure release notes").
>
> https://issues.apache.org/jira/secure/ReleaseNote.jspa?version=12324151&styleName=Html&projectId=12312121&Create=Create
>
>
> On Wed, Feb 19, 2014 at 4:30 PM, Josh Elser <jo...@gmail.com> wrote:
>
>> The CHANGES document that is included in an Accumulo release contains some
>> set of changes from a previous release which presently contain the
>> following information:
>>
>> 1) Issue Type (Task, Bug, Feature, etc)
>> 2) Issue Number (ACCUMULO-1234)
>> 3) Issue Subject
>>
>> There have been various preferences expressed, primarily over IRC, on
>> which changes should be contained and how they should be formatted. The
>> largest consensus, and what I believe we should do, is as follows:
>>
>> Entries in a CHANGES file should contain issues, delimited by minor
>> version within the major version[1], grouped by issue type. The minor
>> version changes sorted be sorted in reverse order (e.g. 1.5.2, 1.5.1, then
>> 1.5.0). Changes from the previous major version (e.g. 1.4.x) would *not* be
>> included in this CHANGES file.
>>
>> Opinions? The results of this discussion will be documented on the
>> release-making page[2] of the website for future reference.
>>
>> - Josh
>>
>> [1] Major and minor version here is referred to as Y and Z of version
>> strings of the form: X.Y.Z (not as prescribed by semver, proper)
>> [2] http://accumulo.apache.org/releasing.html
>>
>
Re: [DISCUSS] CHANGES Documents
Posted by Keith Turner <ke...@deenlo.com>.
I think we should just take the release notes jira generates for X.Y.Z and
prepend them to the CHANGES files with a header saying "Release Notes -
Apache Accumulo - Version X.Y.Z". This is what was done for 1.4.[1,2,3,4]
and 1.5.0
For example the following link will generate 1.4.4 release notes (can
change it from HTML to text by pressing "Configure release notes").
https://issues.apache.org/jira/secure/ReleaseNote.jspa?version=12324151&styleName=Html&projectId=12312121&Create=Create
On Wed, Feb 19, 2014 at 4:30 PM, Josh Elser <jo...@gmail.com> wrote:
> The CHANGES document that is included in an Accumulo release contains some
> set of changes from a previous release which presently contain the
> following information:
>
> 1) Issue Type (Task, Bug, Feature, etc)
> 2) Issue Number (ACCUMULO-1234)
> 3) Issue Subject
>
> There have been various preferences expressed, primarily over IRC, on
> which changes should be contained and how they should be formatted. The
> largest consensus, and what I believe we should do, is as follows:
>
> Entries in a CHANGES file should contain issues, delimited by minor
> version within the major version[1], grouped by issue type. The minor
> version changes sorted be sorted in reverse order (e.g. 1.5.2, 1.5.1, then
> 1.5.0). Changes from the previous major version (e.g. 1.4.x) would *not* be
> included in this CHANGES file.
>
> Opinions? The results of this discussion will be documented on the
> release-making page[2] of the website for future reference.
>
> - Josh
>
> [1] Major and minor version here is referred to as Y and Z of version
> strings of the form: X.Y.Z (not as prescribed by semver, proper)
> [2] http://accumulo.apache.org/releasing.html
>