accumulo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Keith Turner <ke...@deenlo.com>
Subject Re: [DISCUSS] CHANGES Documents
Date Thu, 20 Feb 2014 17:09:28 GMT
On Wed, Feb 19, 2014 at 11:33 PM, Christopher <ctubbsii@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 <eric.newton@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 <josh.elser@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
> >>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message