You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-dev@db.apache.org by "Rick Hillegas (JIRA)" <ji...@apache.org> on 2007/04/20 17:25:15 UTC
[jira] Created: (DERBY-2570) Create a utility which generates
Release Notes
Create a utility which generates Release Notes
----------------------------------------------
Key: DERBY-2570
URL: https://issues.apache.org/jira/browse/DERBY-2570
Project: Derby
Issue Type: Improvement
Components: Build tools
Affects Versions: 10.3.0.0
Reporter: Rick Hillegas
This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
1) A high-level description of the release. The Release Manager would write this description, based on a template.
2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
The following approach makes sense to us:
A) The community will agree on an html template for these notes.
B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
C) Various iterations of the note may be needed.
D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
This effort involves at least two major steps:
I) Getting the community to agree to these note-writing conventions.
II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
Re: [jira] Updated: (DERBY-2570) Create a utility which generates Release Notes
Posted by Myrna van Lunteren <m....@gmail.com>.
On 6/18/07, Rick Hillegas <Ri...@sun.com> wrote:
> There may be enough information in JIRA to model our idea of what issues
> should be included and what issues should be excluded. But even if there
> is, it's not clear to me that the JIRA interface is rich enough to
> express the query you want--it is difficult to express NOTs and ANDs.
> The simplest solution might be to add yet another toggle to our JIRA:
> ExcludeFromReleaseNotes. The release manager would have to go through
> all of the issues and turn on this toggle for the excludable issues. The
> ReleaseNotesGenerator could be trained to throw away those
> issues--that's a half hour of work which I'll gladly do if we decide to
> go down this path.
>
> I may have sufficient karma to add that toggle if the community thinks
> it's a good idea. Let me know how I can be helpful.
>
> Regards,
> -Rick
>
I thought the JiraConnector could be helpful, but somehow it appears
to only take 1 search criterium - for instance, either
fixVersion=10.3.0.0 or resolution=1, which was maddening.
Maybe another set of eyes can get that to work correctly.
With the patch I attached before, I went the other way and made the
ReleaseNotesGenerator exclude things.
I prefer not to go & reopen & modify & reclose all issues for 10.3....
And I guess in the end we can do some manual modification of the
release notes...
:-(
Myrna
Re: [jira] Updated: (DERBY-2570) Create a utility which generates
Release Notes
Posted by Rick Hillegas <Ri...@Sun.COM>.
Myrna van Lunteren wrote:
> Hi Rick,
>
> I struggled a lot with trying to get the xml reports to only show the
> rows I wanted...
> How do you obtain the reports?
>
> Thx,
> Myrna
Hi Myrna,
I don't have a very happy answer to this question. Maybe Andrew can give
better pointers here.
In the bad old days of 10.2, I started out with an xml report based on a
JIRA query. I then went through that report and identified issues which
I thought didn't deserve mentioning in the release notes. I put those
ids in a database. In the database, I also stored the ids of all issues
which I had already documented in the release notes. Then, when I
generated new versions of the xml report, I ran a program which only
printed out the issues which were not excluded and which were not
documented already. Pretty crude.
There may be enough information in JIRA to model our idea of what issues
should be included and what issues should be excluded. But even if there
is, it's not clear to me that the JIRA interface is rich enough to
express the query you want--it is difficult to express NOTs and ANDs.
The simplest solution might be to add yet another toggle to our JIRA:
ExcludeFromReleaseNotes. The release manager would have to go through
all of the issues and turn on this toggle for the excludable issues. The
ReleaseNotesGenerator could be trained to throw away those
issues--that's a half hour of work which I'll gladly do if we decide to
go down this path.
I may have sufficient karma to add that toggle if the community thinks
it's a good idea. Let me know how I can be helpful.
Regards,
-Rick
Re: [jira] Updated: (DERBY-2570) Create a utility which generates Release Notes
Posted by Myrna van Lunteren <m....@gmail.com>.
Hi Rick,
I struggled a lot with trying to get the xml reports to only show the
rows I wanted...
How do you obtain the reports?
Thx,
Myrna
Re: [jira] Commented: (DERBY-2570) Create a utility which generates Release Notes
Posted by Myrna van Lunteren <m....@gmail.com>.
On 4/20/07, Bryan Pendleton (JIRA) <ji...@apache.org> wrote:
>
> [ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12490384 ]
>
> Bryan Pendleton commented on DERBY-2570:
> ----------------------------------------
>
> If the release notes are stored in Jira (a sensible, place, I think), then why do they
> also need to be stored in the code tree? Seems to violate the Don't Repeat Yourself principle...
>
Good question. The only thing I can think of is that things in JIRA
could still be changed - even when a case is closed - and we can have
a saved 'snapshot' sort of file that goes with the release...
Myrna
Re: [jira] Updated: (DERBY-2570) Create a utility which generates Release Notes
Posted by Myrna van Lunteren <m....@gmail.com>.
Rick,
Thanks for all your work on this so far...It looks good...
However, I have one question/issue...
You must be generating the reports:
- fixedBugsList.xml - This is the xml JIRA report of issues addressed
by the release.
- releaseNotesList.xml - This is the xml JIRA report of issues which
have detailed release notes attached to them.
Did you save the filters for obtaining those reports?
Thx,
Myrna
On 5/15/07, Rick Hillegas (JIRA) <ji...@apache.org> wrote:
>
> [ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
>
> Rick Hillegas updated DERBY-2570:
> ---------------------------------
>
> Attachment: derby-2570-v01.diff
>
> Attaching derby-2570-v01.diff. This is a first version of the pamphlet generator. Please take it for a test-drive.
>
> A releaseSummary.xml
>
> This is the release overview, which the Release Manager fills in. It is checked into the codeline so that other members of the community can help the Release Manager wordsmith the overview and description of new features.
>
>
> A tools/release/templates/releaseSummaryTemplate.xml
>
> This is a template file for creating releaseSummary.xml. The template has "???" placeholders which the Release Manager should replace with real information.
>
>
> M tools/release/build.xml
>
> This contains a new "genrelnotes" target for generating the pamphlet. This target assumes that you have defined the "relnotes.src.reports" variable in your ant.properties. This variable points at a directory which contains the following xml JIRA reports:
>
> - fixedBugsList.xml - This is the xml JIRA report of issues addressed by the release.
> - releaseNotesList.xml - This is the xml JIRA report of issues which have detailed release notes attached to them.
>
> The "genrelnotes" target reads the above files, together with trunk/releaseSummary.xml and generates the pamphlet as trunk/RELEASE-NOTES.html.
>
>
> A java/build/org/apache/derbyBuild/ReleaseNotesGenerator.java
>
> This is the ant task which generates the release notes from various inputs. You can run this as a standalone program, specifying the following arguments:
>
> - The name of the summary file describing the release (modelled on releaseSummary.xml).
> - The name of the xml JIRA report of issues fixed in this release.
> - The name of the xml JIRA report of issues which have detailed release notes attached to them.
> - The name of the html file which will hold the generated pamphlet.
>
>
> M RELEASE-NOTES.html
>
> This is the pamphlet generated by running the tool. This shows you what the output looks like.
>
> --------------------------------------------------------
>
> To run the tool, define "relnotes.src.reports" in your ant.properties and create the xml JIRA reports as described above in the comment on build.xml. Run the top level build script in order to build ReleaseNotesGenerator. Then cd to trunk/tools/release and type "ant genrelnotes".
>
> The pamphlet generator attempts to connect to JIRA in order to grab the detailed release notes attached to significant issues. Before running the tool, it is worthwhile to try pinging issues.apache.org. If you can't ping issues.apache.org from a shell window, then the tool will exit. You may need to adjust your proxy and firewall settings.
>
> It would be nice if you didn't have to hand-generate the xml JIRA reports. Maybe the community could agree on some canonical JIRA filters which define these reports. Then the ReleaseNotesGenerator could prod JIRA to produce the reports.
>
> > Create a utility which generates Release Notes
> > ----------------------------------------------
> >
> > Key: DERBY-2570
> > URL: https://issues.apache.org/jira/browse/DERBY-2570
> > Project: Derby
> > Issue Type: Improvement
> > Components: Build tools
> > Affects Versions: 10.3.0.0
> > Reporter: Rick Hillegas
> > Assigned To: Rick Hillegas
> > Attachments: derby-2570-v01.diff, releaseNote.html, releaseNote.html, releaseSummaryTemplate.xml
> >
> >
> > This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> > Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> > 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> > 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> > In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> > The following approach makes sense to us:
> > A) The community will agree on an html template for these notes.
> > B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> > C) Various iterations of the note may be needed.
> > D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> > This effort involves at least two major steps:
> > I) Getting the community to agree to these note-writing conventions.
> > II) Writing the Release Note generator.
>
> --
> This message is automatically generated by JIRA.
> -
> You can reply to this email to add a comment to the issue online.
>
>
[jira] Updated: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Rick Hillegas updated DERBY-2570:
---------------------------------
Attachment: releaseSummaryTemplate.xml
Attaching a template file for the release summary. These are the facts which the Release Manager must supply to the pamphlet generator, including:
1) Release IDs
2) Details on the build environment
3) Release overview
4) Description of new features
Hopefully, the comments in the template will give the Release Manager enough guidance.
I like Laura's suggestion that the filled-in summary should be placed under source-control so that the community can word-smith the overview and the description of new features. I think it would be fine if the filled-in summary lived in trunk/releaseSummary.xml. Unless someone objects, that is where the build target will expect to find the summary.
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Assigned To: Rick Hillegas
> Attachments: releaseNote.html, releaseNote.html, releaseSummaryTemplate.xml
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12499807 ]
Rick Hillegas commented on DERBY-2570:
--------------------------------------
Thanks for the patch, Myrna. I have a couple comments.
It seems to me that this patch does 2 very useful things:
1) It automatically generates one of the JIRA reports--that's what I think JiraConnector does.
2) It filters that JIRA report, throwing away unwanted issues.
A) It seems to me that JiraConnector could be folded into ReleaseNotesGenerator. That is, ReleaseNotesGenerator could just run this query itself and grab the resulting xml document off the web using the same machinery that is used to grab the individual release notes (see ReleaseNotesGenerator.getReleaseNote()). For the moment, the query could be hard-coded and later on we could sand down the parameter-substitution problem you saw. If you folded JiraConnector into ReleaseNotesGenerator, then we could get rid of one of the arguments to ReleaseNotesGenerator and eliminate yet another step in our build process.
B) It seems to me that some of the filtering you are doing (e.g., looking for types bug, improvement, new feature, and subtask) could be folded into the Jira query and removed from the special checks in ReleseNotesGenerator. Maybe the exclusion of Test components has to be a post-Jira filter, but I wonder if that one could be folded into the query too. I'm puzzled why there's a special check for 10.2.1.6--does this mean that those issues need to be adjusted so that they list 10.2.2.0 as one of their fixversions? In general, it would be nice to have a clear model of what filters are done in Jira and what
filters are done post-Jira.
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-2570-v01.diff, DERBY-2570_20070525.diff, releaseNote.html, releaseNote.html, releaseSummaryTemplate.xml
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12505539 ]
Rick Hillegas commented on DERBY-2570:
--------------------------------------
Latest patch committed to trunk at subversion revision 547982 and ported to the 10.3 branch at revision 547983.
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-2570-v01.diff, derby-2570-v02.diff, derby-2570-v03.diff, derby-2570-v04.diff, DERBY-2570_20070525.diff, releaseNote.html, releaseNote.html, releaseSummaryTemplate.xml
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12505913 ]
Rick Hillegas commented on DERBY-2570:
--------------------------------------
Committed to trunk at subversion revision 548432 and ported to 10.3 branch at revision 548433.
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-2570-v01.diff, derby-2570-v02.diff, derby-2570-v03.diff, derby-2570-v04.diff, derby-2570-v05.diff, DERBY-2570_20070525.diff, releaseNote.html, releaseNote.html, releaseSummaryTemplate.xml
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12505522 ]
Rick Hillegas commented on DERBY-2570:
--------------------------------------
Merged previous patch from trunk to 10.3 branch at subversion revision 547961.
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-2570-v01.diff, derby-2570-v02.diff, DERBY-2570_20070525.diff, releaseNote.html, releaseNote.html, releaseSummaryTemplate.xml
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Updated: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Rick Hillegas updated DERBY-2570:
---------------------------------
Attachment: derby-2570-v05.diff
Attaching derby-2570-v05.diff. This teaches the pamphlet generator to substitute <releaseID/> and <previousReleaseID/> with the correct values wherever these variables occur in the overview section of the summary file. Touches the following files:
M java/build/org/apache/derbyBuild/ReleaseNotesGenerator.java
Added the substitution logic.
M tools/release/templates/releaseSummaryTemplate.xml
Added a comment to the <overview> section explaining that these empty tags are now variables.
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-2570-v01.diff, derby-2570-v02.diff, derby-2570-v03.diff, derby-2570-v04.diff, derby-2570-v05.diff, DERBY-2570_20070525.diff, releaseNote.html, releaseNote.html, releaseSummaryTemplate.xml
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12496574 ]
Rick Hillegas commented on DERBY-2570:
--------------------------------------
Committed derby-2570-v01.diff at subversion revision 538929.
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Assigned To: Rick Hillegas
> Attachments: derby-2570-v01.diff, releaseNote.html, releaseNote.html, releaseSummaryTemplate.xml
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Daniel John Debrunner (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12490944 ]
Daniel John Debrunner commented on DERBY-2570:
----------------------------------------------
> I think that we should remove RELEASE_NOTES.html from source control.
-1
An Apache open *source* release is a snapshot of the source at a specific revision, thus all artifacts of the release need to be in svn.
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Laura Stewart (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12491082 ]
Laura Stewart commented on DERBY-2570:
--------------------------------------
What about a "incompatibilities" section for each issue (as appropriate) that addresses incompatibilities with previous versions of Derby?
And although generated automatically, shouldn't there be an edit of the Release Notes after they are generated? Something that a technical writer such as Kim or myself should do...
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Attachments: releaseNote.html
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12491353 ]
Rick Hillegas commented on DERBY-2570:
--------------------------------------
> 1) By editting a JIRA's one line summary, you affect the JIRA's summary as it appears in the pamphlet.
I want to make sure that we're not talking past one another here. What the above comment refers to are the 1-line summaries which appear in RELEASE_NOTES.html in the section titled "Bug Fixes".
The particular example you cite (DERBY-1384) is not a 1-line summary. Instead, it appears in 10.2's RELEASE_NOTES.html in the Issues section, with its own expanded ItemNote. Fine-tuning this ItemNote would be covered by:
> 2) By editting a JIRA's releaseNote.html, you affect what goes into the section on "Behavior Changes from Previous Releases".
For these issues, I'm thinking that we wouldn't include the 1-line summary from the JIRA. Instead, the summary would be what appears in the ItemNote's "Summary of Change" section.
Are you saying that we should not attach separate releaseNote.html files to affected JIRAs and should, instead, collect all the ItemNotes in a master file for the release? I can see some appeal in this--it certainly would simplify the process of generating the pamphlet. However, it would make it harder to track whether an ItemNote has actually been written for a JIRA which has been marked "Release Note Needed".
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Attachments: releaseNote.html, releaseNote.html
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Daniel John Debrunner (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12491067 ]
Daniel John Debrunner commented on DERBY-2570:
----------------------------------------------
One of the possible reasons for the inconsistency in the release notes may be the fact they are titled with the Jira issue number that lead to the change. This may be leading folks to document that issue, but really what needs to be documented is the change in behaviour *resulting* from that issue.
Also maybe even making the title of the section "Issues" is causing confusion. Many of the items listed are not "issues", but improvements that might affect existing applications. This may be leading to inconsistencies in wording, especially for "Solution" and "Workaround". Maybe a better name for "Workaround" would be something along the lines of "Possible Application Changes Required"
A better name of the entire section could be something like "Behaviour Changes from Previous Releases".
Possible names for the individual item descriptions could be:
Summary of Change
- One line summary of change - e.g. Calls to rowUpdated(), rowDeleted(), and rowInserted() now forbidden on unpositioned, forward-only ResultSets.
Symptoms Seen by Applications Affected by Change
- description of errors or change in behaviour the application might see.
Rationale for Change
- why the change was made, e.g. to bring Derby in-line with the JDBC standard
Possible Application Changes Required
- describe re-coding require to either revert to the old behaviour or adjust to the new behaviour.
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Attachments: releaseNote.html
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Updated: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Rick Hillegas updated DERBY-2570:
---------------------------------
Attachment: derby-2570-v06.diff
Attaching derby-2570-v06.diff. This lets people put interesting formatting tags inside the summary paragraphs of release notes. Previously, in constructing the list of links to detailed notes, only the first text node from the summary was put into the link text. This truncated the summary line for DERBY-2264.
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-2570-v01.diff, derby-2570-v02.diff, derby-2570-v03.diff, derby-2570-v04.diff, derby-2570-v05.diff, derby-2570-v06.diff, DERBY-2570_20070525.diff, releaseNote.html, releaseNote.html, releaseSummaryTemplate.xml
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Updated: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Rick Hillegas updated DERBY-2570:
---------------------------------
Attachment: releaseNote.html
Attaching a first rev of the ItemNote template: releaseNote.html. What do you think?
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Attachments: releaseNote.html
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Andrew McIntyre (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12490990 ]
Andrew McIntyre commented on DERBY-2570:
----------------------------------------
The release notes that are included in the release are neither what we currently have checked into the trunk as the current RELEASE_NOTES.html, nor are they in JIRA in an easily manipulable format. The release notes that are included in the release are going to be (in most cases) the work of the release manager, including a summary, the list of application impacts and long form release notes, and a list of bug fixes and new features and such. The goal of this JIRA is to eliminate the mechanical steps to compiling the actual release notes that will become part of the release. It should be, once completed, checked into svn. Just as with the last several releases, long form release notes should be put into JIRA, although we would now ask that contributors attach them to JIRA as attachments using a template, instead of free form in the comments.
So:
- the current RELEASE_NOTES.html in the trunk should be moved elsewhere, as it is a template for the final product and not an actual set of release notes.
- a new template providing an outline of HTML markup for the long form release notes should be added in the same place (tools/release/templates? tools/templates?) along with instructions for filling it out and attaching it to JIRA.
- create a tool which compiles the long and short form release notes from JIRA, and incorporates a hand-written (or partially generated) summary provided by the release manager who will be running the tool. Previously this had been done by hand and the work described in this JIRA aims to alleviate this manual step for the release manager.
- the compiled release notes would be put up for review and checked into svn before release artifacts are generated.
The only difference from previous releases is that we would ask contributors to provide long form release notes using the template described above and attach it to JIRA, so that the automated tool could scrape it out of JIRA and compile the release notes which much less manual effort. The tool could check that each JIRA with 'release note needed' checked contained a long form release note, and if the contributor does not provide one, or is no longer interested in providing one, then it will still be up to the release manager to get the release note into the necessary format so that it is included in the release notes.
To address Bryan's concern, a long form release note attached to JIRA may be part of one or several releases. A compiled set of release notes with description (including specific version number), summary, and some set of long form notes and short form bug fixes and features is meant to be distributed with one and only one release. To address Dan's concern, I do believe that this compiled set of release notes should be checked into svn before the release artifacts are generated so that the final product becomes a part of the source distribution and included in the subversion history.
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Myrna van Lunteren (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12510691 ]
Myrna van Lunteren commented on DERBY-2570:
-------------------------------------------
should we close this & handle new improvements in a separate jira?
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-2570-v01.diff, derby-2570-v02.diff, derby-2570-v03.diff, derby-2570-v04.diff, derby-2570-v05.diff, derby-2570-v06.diff, DERBY-2570_20070525.diff, releaseNote.html, releaseNote.html, releaseSummaryTemplate.xml
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Closed: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Myrna van Lunteren (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Myrna van Lunteren closed DERBY-2570.
-------------------------------------
Resolution: Fixed
Fix Version/s: 10.3.0.0
Derby Info: (was: [Patch Available])
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Fix For: 10.3.0.0
>
> Attachments: derby-2570-v01.diff, derby-2570-v02.diff, derby-2570-v03.diff, derby-2570-v04.diff, derby-2570-v05.diff, derby-2570-v06.diff, DERBY-2570_20070525.diff, releaseNote.html, releaseNote.html, releaseSummaryTemplate.xml
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12494057 ]
Rick Hillegas commented on DERBY-2570:
--------------------------------------
Checked in releaseNotes.html at subversion revision 535894:
A tools/release/templates
A tools/release/templates/releaseNote.html
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Attachments: releaseNote.html, releaseNote.html
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Daniel John Debrunner (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12491072 ]
Daniel John Debrunner commented on DERBY-2570:
----------------------------------------------
Ok - I now see the html comments in the template ... :-)
I think there is still confusion over what is being described:
For "Problems" & "Symptoms" the text in upper-case is in the present tense, so I expect it to be about the current release, but the example given is in the past tense and about the previous release.
I think moving away from "Issue" and towards "Behaviour Change" would help a great deal.
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Attachments: releaseNote.html
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12491046 ]
Rick Hillegas commented on DERBY-2570:
--------------------------------------
Note that if you just click on releaseNote.html, you won't see much: just the headings and stub text. Html comments explain how to fill in the sections.
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Attachments: releaseNote.html
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Daniel John Debrunner (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12491056 ]
Daniel John Debrunner commented on DERBY-2570:
----------------------------------------------
On the template:
Looking at how these headings were used in the 10.2 release notes I think there needs to be some clarification of what they actually mean.
This would lead to consistency in the release notes, maybe the template could include the defintions.
For example looking at the release notes for 10.2
http://db.apache.org/derby/releases/release-10.2.2.0.cgi
For DERBY-1384
"Problem - Maximum BLOB/CLOB length has increased to 2G-1"
That's not a problem, I think the problem is really "Application may allow BLOB/CLOB values previously rejected".
"Symptoms" sometimes describes to old behaviour (e.g. DERBY-1295), I would think it would describe symptoms the application will see when using the new software.
"Cause" seems a confused section, I'm not really sure what its intention is. DERBY-822 seems to have a clear cause of the issue, but then it overlaps with information given in the preceeding symptoms section. Sometimes it seems to just describe old behaviour which I'm not sure is relevant here.
"Solution" is sometimes used to describe the change made in Derby (e.g. DERBY-1652) and sometimes the solution the application needs to make (e.g. DERBY-1867).
"Workaround" and "Solution" sometimes overlap
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Attachments: releaseNote.html
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Myrna van Lunteren (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12505527 ]
Myrna van Lunteren commented on DERBY-2570:
-------------------------------------------
I added the JiraConnector with revision http://svn.apache.org/viewvc?view=rev&revision=547965.
It has a better query for the release notes list than the one in the patch, and is dedicated to create the two files the ReleaseNotesGenerator needs.
It can be combined with the ReleaseNotesGenerator later.
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-2570-v01.diff, derby-2570-v02.diff, DERBY-2570_20070525.diff, releaseNote.html, releaseNote.html, releaseSummaryTemplate.xml
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Myrna van Lunteren (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12499842 ]
Myrna van Lunteren commented on DERBY-2570:
-------------------------------------------
re comment A. You're right, if we wrap JiraConnector into
ReleaseNotesGenerator, we'd get rid of an extra step. I'll see if I
can do that later this week, but I'm battling something else right
now...
re comment B. The problem I had was that I couldn't figure out how to
do 'or' in the queries. Probably something simple, but...So hence the
elaborate checking of types.
I don't quite know what to do about 10.2.1.6. The current practice of
marking things fixed in a hypothetical next release is proving
troublesome, the result being that we now have things fixed in
10.2.1.6 and 10.3, but not 10.2.2.0., which is what we're checking for
as being the last previous release...
Maybe we should add some logic for optional multiple older releases to
ignore into the generator.
Myrna
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-2570-v01.diff, DERBY-2570_20070525.diff, releaseNote.html, releaseNote.html, releaseSummaryTemplate.xml
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Reopened: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Myrna van Lunteren (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Myrna van Lunteren reopened DERBY-2570:
---------------------------------------
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-2570-v01.diff, derby-2570-v02.diff, derby-2570-v03.diff, derby-2570-v04.diff, derby-2570-v05.diff, derby-2570-v06.diff, DERBY-2570_20070525.diff, releaseNote.html, releaseNote.html, releaseSummaryTemplate.xml
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
Re: [jira] Commented: (DERBY-2570) Create a utility which generates
Release Notes
Posted by Rick Hillegas <Ri...@Sun.COM>.
Daniel John Debrunner wrote:
> Rick Hillegas (JIRA) wrote:
>
>> I think the issue may be: Are the release notes source or are they a
>> build artifact? I'm viewing them as a build artifact. The sources for
>> this aftifact are:
>
> Then the source for them needs to be completely in svn.
>
>> o The state of JIRA at some point in time.
>
> Can you go back to Jira at a specific point in time to re-create the
> same release artifact?
>
> Dan.
>
Maybe Andrew or Jean can answer this. I don't know.
Regards,
-Rick
Re: [jira] Commented: (DERBY-2570) Create a utility which generates
Release Notes
Posted by Daniel John Debrunner <dj...@apache.org>.
Rick Hillegas (JIRA) wrote:
> I think the issue may be: Are the release notes source or are they a build artifact? I'm viewing them as a build artifact. The sources for this aftifact are:
Then the source for them needs to be completely in svn.
> o The state of JIRA at some point in time.
Can you go back to Jira at a specific point in time to re-create the
same release artifact?
Dan.
[jira] Commented: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12490969 ]
Rick Hillegas commented on DERBY-2570:
--------------------------------------
> An Apache open *source* release is a snapshot of the source at a specific revision, thus all artifacts of the release need to be in svn.
The release notes already appear under svn in the distribution zips and tars as well as on the release download page. This was true before RELEASE_NOTES.html was added to the code tree in 10.2. We would simply be going back to the 10.1 state of affairs. Were we violating Apache process back then?
I think the issue may be: Are the release notes source or are they a build artifact? I'm viewing them as a build artifact. The sources for this aftifact are:
o The state of JIRA at some point in time.
o A summary written by the release manager.
Perhaps the summary could be placed under source control?
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Updated: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Rick Hillegas updated DERBY-2570:
---------------------------------
Derby Info: [Patch Available]
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Assigned To: Rick Hillegas
> Attachments: derby-2570-v01.diff, releaseNote.html, releaseNote.html, releaseSummaryTemplate.xml
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12490922 ]
Rick Hillegas commented on DERBY-2570:
--------------------------------------
Thanks for bringing this up, Bryan. As part of this work, I think that we should remove RELEASE_NOTES.html from source control.
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Closed: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Rick Hillegas closed DERBY-2570.
--------------------------------
Resolution: Fixed
Closing. As Myrna recommends, we can track improvements in later JIRAs.
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-2570-v01.diff, derby-2570-v02.diff, derby-2570-v03.diff, derby-2570-v04.diff, derby-2570-v05.diff, derby-2570-v06.diff, DERBY-2570_20070525.diff, releaseNote.html, releaseNote.html, releaseSummaryTemplate.xml
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12491027 ]
Rick Hillegas commented on DERBY-2570:
--------------------------------------
Thanks to Bryan, Myrna, Dan, and Andrew for the discussion.
I think this is an improvement on what I was imagining. I was hoping that we could eliminate another discrete, manual step in release generation. To that end, I was hoping that when you pushed the big GenerateRelease button, the release notes would be generated along with the user guides, zips, signatures, etc..
However, based on today's discussion, I see now that something related to the release notes has to be checked into svn. Maybe the release notes themselves, maybe their sources. I agree with Andrew that it is probably simpler to check in the release notes themselves. For me the clincher argument is the need to review the release notes. Checking them into the codeline fits this process into our familiar review cycle.
For the remainder of this comment, I want to split the overloaded term "release notes" into the following separate concepts:
ItemNote - This is the JIRA-specific description of a significant issue and its resolution/workaround. This description is attached to the JIRA.
Overview - This is the release-specific summary which the release manager writes.
ReleasePamphlet - This is the full description of the release, including the overview, the list of fixed bugs, and the list of significant ItemNotes. This is what is currently checked into the branch as RELEASE_NOTES.html, shipped in our distributions, and included on the release download page.
I can see the need to provide templates for the ItemNote and Overview. Between html comments and exlanatory sample text, I hope that these templates can be self-describing.
I think that tools/release/templates is a fine place to park the 2 new templates. As far as I'm concerned, the output of the pamphlet generator, RELEASE_NOTES.html, can continue to live where it does now. We can stub it out so that it is clear that you should not hand-edit the file.
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12505529 ]
Rick Hillegas commented on DERBY-2570:
--------------------------------------
Ported previous patch from main to 10.3 branch at subversion revision 547970
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-2570-v01.diff, derby-2570-v02.diff, derby-2570-v03.diff, DERBY-2570_20070525.diff, releaseNote.html, releaseNote.html, releaseSummaryTemplate.xml
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12499893 ]
Rick Hillegas commented on DERBY-2570:
--------------------------------------
Hi, Myrna. Some more comments follow:
B: I think that, by default, Jira does ORs on field values. It's NOTs and ANDs that I don't understand. It looks to me as though your filters need ORs and NOTs.
It's possible that the only NOT you need is this: "NOT fixed in the previous release." I think you can do that post-Jira filtering in ReleaseNotesGenerator, relying only on the <releaseID> and <previousReleaseID> values from releaseSummary.xml. Or, at least, you could get pretty close and then just scrub the Jira entries a little. Here's how it looks to me:
i) We assume that two releases are cut off the same branch if their release ids have the same major and minor numbers.
ii) Once a bug has been marked as fixed in a given branch, it is assumed that it is fixed in all subsequent releases in that branch.
iii) If <releaseID> and <previousReleaseID> are in the same branch, then we don't need to perform the post-Jira filtering. The fact that a bug is marked as fixed in <releaseID> means (because of ii) that the bug was not also fixed in <previousReleaseID>.
iv) If, however, <releaseID> and <previousReleaseID> are in different branches, then we need to filter out all bugs which are marked as fixed in the <previousReleaseID> branch. That is, all bugs marked as fixed in a release whose major and minor ids agree with the major and minor ids of <previousReleaseID>.
I think that will work.
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-2570-v01.diff, DERBY-2570_20070525.diff, releaseNote.html, releaseNote.html, releaseSummaryTemplate.xml
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Daniel John Debrunner (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12491345 ]
Daniel John Debrunner commented on DERBY-2570:
----------------------------------------------
> 1) By editting a JIRA's one line summary, you affect the JIRA's summary as it appears in the pamphlet.
I think this is the wrong approach. For something that can affect existing applications it is the behaviour change resulting from the Jira entry not the entry itself.
For example, DERBY-1384 in 10.2
The summary in Jira is:
Increase default BLOB/CLOB length to maximum supported (2G?)
which was cleaned up (incorrectly) in the release notes as
Maximum BLOB/CLOB length has increased to 2G-1.
But that's not what existing applications need to be aware of. They need to understand that due to this change columns that are declared as BLOB/CLOB now will not reject values larger than 1M and if their application depended on that, they need to make changes.
Changing the summary for DERBY-1384 would be wrong, it's correct.
The summary for such a change in behaviour needs to highlight how it might affect/break applications so that an application developer is more likely to read it.
Maybe separating the release notes from Jira and just have a single file release_notes.html file with the actual contents would work.
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Attachments: releaseNote.html, releaseNote.html
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Assigned: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Rick Hillegas reassigned DERBY-2570:
------------------------------------
Assignee: Rick Hillegas
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Assigned To: Rick Hillegas
> Attachments: releaseNote.html, releaseNote.html
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Updated: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Rick Hillegas updated DERBY-2570:
---------------------------------
Attachment: derby-2570-v04.diff
Attach derby-2570-v01.diff. This creates a separate tool out of the logic in the pamphlet generator which looks for spefici information in the release note. This tool should be run standalone on a release note before attaching it to a JIRA. Touches the following files:
A java/build/org/apache/derbyBuild/ReleaseNoteReader.java
Tool carved out of the pamphlet generator.
M java/build/org/apache/derbyBuild/ReleaseNotesGenerator.java
Pamphlet generator modified to use the new tool.
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-2570-v01.diff, derby-2570-v02.diff, derby-2570-v03.diff, derby-2570-v04.diff, DERBY-2570_20070525.diff, releaseNote.html, releaseNote.html, releaseSummaryTemplate.xml
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12506233 ]
Rick Hillegas commented on DERBY-2570:
--------------------------------------
Committed to trunk at subversion revision 548781. Merged to 10.3 branch at revision 548783.
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-2570-v01.diff, derby-2570-v02.diff, derby-2570-v03.diff, derby-2570-v04.diff, derby-2570-v05.diff, derby-2570-v06.diff, DERBY-2570_20070525.diff, releaseNote.html, releaseNote.html, releaseSummaryTemplate.xml
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Updated: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Rick Hillegas updated DERBY-2570:
---------------------------------
Attachment: derby-2570-v03.diff
Attaching derby-2570-v03.diff. This teaches the pamphlet generator to buffer up errors rather than failing on the first bad release note. Committed at subversion revision 547969.
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-2570-v01.diff, derby-2570-v02.diff, derby-2570-v03.diff, DERBY-2570_20070525.diff, releaseNote.html, releaseNote.html, releaseSummaryTemplate.xml
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Updated: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Rick Hillegas updated DERBY-2570:
---------------------------------
Attachment: derby-2570-v02.diff
Attaching derby-2570-v02.diff. This teaches the release note generator to report notes which have badly formatted summary lines. Committed at subversion revision 547957.
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-2570-v01.diff, derby-2570-v02.diff, DERBY-2570_20070525.diff, releaseNote.html, releaseNote.html, releaseSummaryTemplate.xml
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Updated: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Rick Hillegas updated DERBY-2570:
---------------------------------
Attachment: derby-2570-v01.diff
Attaching derby-2570-v01.diff. This is a first version of the pamphlet generator. Please take it for a test-drive.
A releaseSummary.xml
This is the release overview, which the Release Manager fills in. It is checked into the codeline so that other members of the community can help the Release Manager wordsmith the overview and description of new features.
A tools/release/templates/releaseSummaryTemplate.xml
This is a template file for creating releaseSummary.xml. The template has "???" placeholders which the Release Manager should replace with real information.
M tools/release/build.xml
This contains a new "genrelnotes" target for generating the pamphlet. This target assumes that you have defined the "relnotes.src.reports" variable in your ant.properties. This variable points at a directory which contains the following xml JIRA reports:
- fixedBugsList.xml - This is the xml JIRA report of issues addressed by the release.
- releaseNotesList.xml - This is the xml JIRA report of issues which have detailed release notes attached to them.
The "genrelnotes" target reads the above files, together with trunk/releaseSummary.xml and generates the pamphlet as trunk/RELEASE-NOTES.html.
A java/build/org/apache/derbyBuild/ReleaseNotesGenerator.java
This is the ant task which generates the release notes from various inputs. You can run this as a standalone program, specifying the following arguments:
- The name of the summary file describing the release (modelled on releaseSummary.xml).
- The name of the xml JIRA report of issues fixed in this release.
- The name of the xml JIRA report of issues which have detailed release notes attached to them.
- The name of the html file which will hold the generated pamphlet.
M RELEASE-NOTES.html
This is the pamphlet generated by running the tool. This shows you what the output looks like.
--------------------------------------------------------
To run the tool, define "relnotes.src.reports" in your ant.properties and create the xml JIRA reports as described above in the comment on build.xml. Run the top level build script in order to build ReleaseNotesGenerator. Then cd to trunk/tools/release and type "ant genrelnotes".
The pamphlet generator attempts to connect to JIRA in order to grab the detailed release notes attached to significant issues. Before running the tool, it is worthwhile to try pinging issues.apache.org. If you can't ping issues.apache.org from a shell window, then the tool will exit. You may need to adjust your proxy and firewall settings.
It would be nice if you didn't have to hand-generate the xml JIRA reports. Maybe the community could agree on some canonical JIRA filters which define these reports. Then the ReleaseNotesGenerator could prod JIRA to produce the reports.
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Assigned To: Rick Hillegas
> Attachments: derby-2570-v01.diff, releaseNote.html, releaseNote.html, releaseSummaryTemplate.xml
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Bryan Pendleton (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12490384 ]
Bryan Pendleton commented on DERBY-2570:
----------------------------------------
If the release notes are stored in Jira (a sensible, place, I think), then why do they
also need to be stored in the code tree? Seems to violate the Don't Repeat Yourself principle...
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Updated: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Myrna van Lunteren (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Myrna van Lunteren updated DERBY-2570:
--------------------------------------
Attachment: DERBY-2570_20070525.diff
Attaching a patch that
1. hacks through Rick's elegant code to massage the issues accepted into the release notes bug fixing area to be only those that:
- do not have fixversion listing the previous release
- do not have fixversion listing 10.2.1.6 (this one is hardcoded)
- only are of type bug, improvement, new feature, or sub-task
- do not have component 'Test'.
I already checked in a revision of the RELEASE-NOTES.html built using this...
But I did not want to check in my modifications without a review.
2. add a class, JiraConnector, that goes after JIRA's xml and pulls a report based on hardwired query.
This query can be modified, or the file can be made to take a parameter...I tried the parameter approach and for some reason the resulting xml was quite different. So, I resorted to leaving this in hard-coded. Right now, also, the file name that the JiraConnector creates is not what is expected by the ReleaseNotesGenerator class. That too, can be modified later.
This patch is ready for review.
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Assigned To: Rick Hillegas
> Attachments: derby-2570-v01.diff, DERBY-2570_20070525.diff, releaseNote.html, releaseNote.html, releaseSummaryTemplate.xml
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Updated: (DERBY-2570) Create a utility which generates
Release Notes
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-2570?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Rick Hillegas updated DERBY-2570:
---------------------------------
Attachment: releaseNote.html
Thanks for the feedback, Dan and Laura. I have attached a new rev of releaseNote.html. This incorporates Dan's suggestions. It also includes an optional Incompatibilities section as Laura suggested.
I like Dan's suggestion for renaming the Issues section.
I think that it would be great if technical writers could get involved in improving RELEASE_NOTES.html. The problem, of course, is that hand-edits of that file may be clobbered the next time someone runs the pamphlet-generator. Perhaps we should also put the Overview under svn? If we did that, then other people could improve the following parts of the pamphlet:
1) By editting a JIRA's one line summary, you affect the JIRA's summary as it appears in the pamphlet.
2) By editting a JIRA's releaseNote.html, you affect what goes into the section on "Behavior Changes from Previous Releases".
3) By editting the Overview in svn, you affect what goes into the overall release description.
Is that sufficient? Is there something else we should do to make it possible for technical writers to improve RELEASE_NOTES.html?
> Create a utility which generates Release Notes
> ----------------------------------------------
>
> Key: DERBY-2570
> URL: https://issues.apache.org/jira/browse/DERBY-2570
> Project: Derby
> Issue Type: Improvement
> Components: Build tools
> Affects Versions: 10.3.0.0
> Reporter: Rick Hillegas
> Attachments: releaseNote.html, releaseNote.html
>
>
> This proposal summarizes an off-list conversation among Myrna van Lunteren, Bernt Johnsen, Andrew McIntyre, and myself.
> Currently, there is a template for release notes in the top level directory of the code tree. Actually filling in this template is a time-consuming, error-prone process. We would like to automate this process as much as possible. We believe it ought to be possible to generate the Release Notes given the following inputs:
> 1) A high-level description of the release. The Release Manager would write this description, based on a template.
> 2) An xml report produced by a JIRA filter. The filter would list all of the JIRAs addressed by the release.
> In order for this to work, we would need for the community to agree on conventions for the release notes which are attached to JIRAs, viz., the JIRAs whose "Release Note Needed" toggles are turned on. These JIRA-specific notes become items in the Issues section of the final Release Notes. Each of these items calls the reader's attention to a significant topic involving Derby's behavior, that behavior's compatibility with previous releases, and adjustments which the user may need to make to her applications.
> The following approach makes sense to us:
> A) The community will agree on an html template for these notes.
> B) The note-writer will fill in this template and attach it to the JIRA using a canonical file name, say "releaseNote.html".
> C) Various iterations of the note may be needed.
> D) The utility for generating Release Notes will grab the latest rev of "releaseNote.html" attached to the JIRA.
> This effort involves at least two major steps:
> I) Getting the community to agree to these note-writing conventions.
> II) Writing the Release Note generator.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.