Derby
  1. Derby
  2. DERBY-2570

Create a utility which generates Release Notes

    Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 10.3.1.4
    • Fix Version/s: 10.3.1.4
    • Component/s: Build tools
    • Labels:
      None

      Description

      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.

      1. derby-2570-v06.diff
        7 kB
        Rick Hillegas
      2. derby-2570-v05.diff
        3 kB
        Rick Hillegas
      3. derby-2570-v04.diff
        13 kB
        Rick Hillegas
      4. derby-2570-v03.diff
        6 kB
        Rick Hillegas
      5. derby-2570-v02.diff
        2 kB
        Rick Hillegas
      6. DERBY-2570_20070525.diff
        11 kB
        Myrna van Lunteren
      7. derby-2570-v01.diff
        110 kB
        Rick Hillegas
      8. releaseSummaryTemplate.xml
        3 kB
        Rick Hillegas
      9. releaseNote.html
        2 kB
        Rick Hillegas
      10. releaseNote.html
        2 kB
        Rick Hillegas

        Activity

        Hide
        Rick Hillegas added a comment -

        Closing. As Myrna recommends, we can track improvements in later JIRAs.

        Show
        Rick Hillegas added a comment - Closing. As Myrna recommends, we can track improvements in later JIRAs.
        Hide
        Myrna van Lunteren added a comment -

        should we close this & handle new improvements in a separate jira?

        Show
        Myrna van Lunteren added a comment - should we close this & handle new improvements in a separate jira?
        Hide
        Rick Hillegas added a comment -

        Committed to trunk at subversion revision 548781. Merged to 10.3 branch at revision 548783.

        Show
        Rick Hillegas added a comment - Committed to trunk at subversion revision 548781. Merged to 10.3 branch at revision 548783.
        Hide
        Rick Hillegas added a comment -

        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.

        Show
        Rick Hillegas added a comment - 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 .
        Hide
        Rick Hillegas added a comment -

        Committed to trunk at subversion revision 548432 and ported to 10.3 branch at revision 548433.

        Show
        Rick Hillegas added a comment - Committed to trunk at subversion revision 548432 and ported to 10.3 branch at revision 548433.
        Hide
        Rick Hillegas added a comment -

        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.

        Show
        Rick Hillegas added a comment - 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.
        Hide
        Rick Hillegas added a comment -

        Latest patch committed to trunk at subversion revision 547982 and ported to the 10.3 branch at revision 547983.

        Show
        Rick Hillegas added a comment - Latest patch committed to trunk at subversion revision 547982 and ported to the 10.3 branch at revision 547983.
        Hide
        Rick Hillegas added a comment -

        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.

        Show
        Rick Hillegas added a comment - 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.
        Hide
        Rick Hillegas added a comment -

        Ported previous patch from main to 10.3 branch at subversion revision 547970

        Show
        Rick Hillegas added a comment - Ported previous patch from main to 10.3 branch at subversion revision 547970
        Hide
        Rick Hillegas added a comment -

        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.

        Show
        Rick Hillegas added a comment - 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.
        Hide
        Myrna van Lunteren added a comment -

        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.

        Show
        Myrna van Lunteren added a comment - 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.
        Hide
        Rick Hillegas added a comment -

        Merged previous patch from trunk to 10.3 branch at subversion revision 547961.

        Show
        Rick Hillegas added a comment - Merged previous patch from trunk to 10.3 branch at subversion revision 547961.
        Hide
        Rick Hillegas added a comment -

        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.

        Show
        Rick Hillegas added a comment - 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.
        Hide
        Rick Hillegas added a comment -

        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.

        Show
        Rick Hillegas added a comment - 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.
        Hide
        Myrna van Lunteren added a comment -

        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

        Show
        Myrna van Lunteren added a comment - 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
        Hide
        Rick Hillegas added a comment -

        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.

        Show
        Rick Hillegas added a comment - 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.
        Hide
        Myrna van Lunteren added a comment -

        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.

        Show
        Myrna van Lunteren added a comment - 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.
        Hide
        Rick Hillegas added a comment -

        Committed derby-2570-v01.diff at subversion revision 538929.

        Show
        Rick Hillegas added a comment - Committed derby-2570-v01.diff at subversion revision 538929.
        Hide
        Rick Hillegas added a comment -

        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.

        Show
        Rick Hillegas added a comment - 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.
        Hide
        Rick Hillegas added a comment -

        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.

        Show
        Rick Hillegas added a comment - 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.
        Hide
        Rick Hillegas added a comment -

        Checked in releaseNotes.html at subversion revision 535894:

        A tools/release/templates
        A tools/release/templates/releaseNote.html

        Show
        Rick Hillegas added a comment - Checked in releaseNotes.html at subversion revision 535894: A tools/release/templates A tools/release/templates/releaseNote.html
        Hide
        Rick Hillegas added a comment -

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

        Show
        Rick Hillegas added a comment - > 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".
        Hide
        Daniel John Debrunner added a comment -

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

        Show
        Daniel John Debrunner added a comment - > 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.
        Hide
        Rick Hillegas added a comment -

        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?

        Show
        Rick Hillegas added a comment - 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?
        Hide
        Laura Stewart added a comment -

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

        Show
        Laura Stewart added a comment - 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...
        Hide
        Daniel John Debrunner added a comment -

        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.

        Show
        Daniel John Debrunner added a comment - 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.
        Hide
        Daniel John Debrunner added a comment -

        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.
        Show
        Daniel John Debrunner added a comment - 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.
        Hide
        Daniel John Debrunner added a comment -

        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

        Show
        Daniel John Debrunner added a comment - 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
        Hide
        Rick Hillegas added a comment -

        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.

        Show
        Rick Hillegas added a comment - 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.
        Hide
        Rick Hillegas added a comment -

        Attaching a first rev of the ItemNote template: releaseNote.html. What do you think?

        Show
        Rick Hillegas added a comment - Attaching a first rev of the ItemNote template: releaseNote.html. What do you think?
        Hide
        Rick Hillegas added a comment -

        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.

        Show
        Rick Hillegas added a comment - 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.
        Hide
        Andrew McIntyre added a comment -

        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.

        Show
        Andrew McIntyre added a comment - 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.
        Hide
        Rick Hillegas added a comment -

        > 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?

        Show
        Rick Hillegas added a comment - > 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?
        Hide
        Daniel John Debrunner added a comment -

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

        Show
        Daniel John Debrunner added a comment - > 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.
        Hide
        Rick Hillegas added a comment -

        Thanks for bringing this up, Bryan. As part of this work, I think that we should remove RELEASE_NOTES.html from source control.

        Show
        Rick Hillegas added a comment - Thanks for bringing this up, Bryan. As part of this work, I think that we should remove RELEASE_NOTES.html from source control.
        Hide
        Bryan Pendleton added a comment -

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

        Show
        Bryan Pendleton added a comment - 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...

          People

          • Assignee:
            Rick Hillegas
            Reporter:
            Rick Hillegas
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development