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