[
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.
