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, 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 of the website for future reference.
I'd prefer it if the CHANGES document included all changes, as they do in Avro and Jackson. 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)
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").
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" <[EMAIL PROTECTED]> 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 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?
On Wed, Feb 19, 2014 at 10:33 PM, Christopher <[EMAIL PROTECTED]> wrote:
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 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.
: 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.
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. 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.
On Thu, Feb 20, 2014 at 12:32 AM, Josh Elser <[EMAIL PROTECTED]> wrote: 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).
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.
On Thu, Feb 20, 2014 at 1:20 AM, Sean Busbey <busbey+[EMAIL PROTECTED]>wrote:
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.
On Wed, Feb 19, 2014 at 4:53 PM, Eric Newton <[EMAIL PROTECTED]> wrote: 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 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.
 http://developer.android.com/sdk/RELEASENOTES.html 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.
On Wed, Feb 19, 2014 at 11:33 PM, Christopher <[EMAIL PROTECTED]> wrote: I would love to drop sub-task from the list.
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.
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. 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.
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.
On Thu, Feb 20, 2014 at 12:31 PM, Josh Elser <[EMAIL PROTECTED]> wrote: 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.
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.
On Thu, Feb 20, 2014 at 1:10 AM, Sean Busbey <busbey+[EMAIL PROTECTED]>wrote: 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'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, 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.
On Thu, Feb 20, 2014 at 1:10 PM, Josh Elser <[EMAIL PROTECTED]> wrote: 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.[188.8.131.52] 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.
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.
On Thu, Feb 20, 2014 at 1:00 PM, Keith Turner <[EMAIL PROTECTED]> 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".
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).
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.
On Feb 21, 2014 3:22 PM, "Josh Elser" <[EMAIL PROTECTED]> wrote: issue types (or only excluding sub-tasks) for 1.5.1 and revisiting at a later point: prefer not having any of those three things in there, I will not oppose any RC on that basis." 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.
NEW: Monitor These Apps!
Apache Lucene, Apache Solr and all other Apache Software Foundation projects and their respective logos are trademarks of the Apache Software Foundation.
Elasticsearch, Kibana, Logstash, and Beats are trademarks of Elasticsearch BV, registered in the U.S. and in other countries. This site and Sematext Group is in no way affiliated with Elasticsearch BV.
Service operated by Sematext