You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-commits@db.apache.org by Apache Wiki <wi...@apache.org> on 2010/10/12 19:58:37 UTC
[Db-derby Wiki] Update of "ReleaseCandidates" by RichardHillegas
Dear Wiki user,
You have subscribed to a wiki page or wiki category on "Db-derby Wiki" for change notification.
The "ReleaseCandidates" page has been changed by RichardHillegas.
http://wiki.apache.org/db-derby/ReleaseCandidates
--------------------------------------------------
New page:
This page is an appendix to the overall Derby release instructions found here: DerbySnapshotOrRelease
'''Table of Contents'''
<<TableOfContents(4)>>
For each release candidate:
* drive bug list to zero
* add new section to testing wiki pages
* arrange for appropriate version numbers in JIRA
* ensure all new (and old) files have correct copyright & license
* svn update source and doc trees
* build all, then:
* ensure all release notes are current
* copy `rrefexcept71493.dita` from `<source>/classes/doc` to `<docsource>/src/ref`
* update `releaseSummary.xml`, create release notes & changes files
* clean doc & source trees, then build release artifacts
* (optional:) build eclipse plugin or get a volunteer to do it for you
* sign and place on `people.apache.org` web site (in your `public_html directory`)
* verify a downloaded lib, bin and src distribution (build in the src distribution, preferably create a release)
* bump version to prepare for a possible next build
* update release wiki page
* call for vote
<<Anchor(FirstRC)>>
=== For the first release candidate on a new branch ===
1. Update `tools/ant/properties/release.properties` by hand, and set the `beta` property to false (unless this is a ''beta'' release candidate).
1. Check in the modification.
1. You will need to clobber and build again before you can see the changed `beta` property reflected in the source. Note that the first release off a new branch is automatically beta, even if you set the `beta` property to false.
<<Anchor(ForEachRC)>>
=== For each release candidate ===
Verify that:
* `beta` property is false (unless you are creating a ''beta'' release candidate). If this is the first release candidate off this branch the `beta` property should have been set to false in a [[#FirstRC|previous section]]. If this is an update relase, the `beta` property should have been set to false as a part of the release cycle for the first release off this branch.
* Version number is correct. For the first release candidate off a branch, the version number should have been set immediately [[#BranchVersion|after cutting the branch]]. For subsequent release candidates, including update release candidates, the version number should have been bumped after [[#Bump4th|spinning the previous release candidate]]
The third and fourth parts of the version number are combined into a single property, maint, where maint = (third digit * 1000000) + fourth digit. Note that removing the beta flag will not have an effect unless the 3rd digit (fixpack) is greater than 0, since version numbers with fixpack=0 always are considered alpha. Fixpack (3rd digit) will normally be set to 1 when the [[#BranchCutting|branch is cut]], but if it isn't, it must be incremented before the release candidate can be created.
==== Check-ins just before generating release artifacts ====
1. [[http://db.apache.org/derby/manuals/docscheck.html|Adjust version numbers in documentation]]. Make sure the copyright notices has the correct years.
1. Generate `RELEASE_NOTES.html` in the branch and check it into the svn repository. Please consult the instructions for [[http://wiki.apache.org/db-derby/ReleaseNoteProcess|generating release notes]].
1. For versions < 10.3; finalize `CHANGES`. For later releases the `CHANGES` file has been deprecated.
{i} The tool `java/tools/ChangesFileGenerator.java` can help you generate this file. It can be invoked by running `ant genchanges` in `tools/release`.
1. Check in the latest SQLState documentation. (This step can be done in advance, but make sure that no SQLState has been modified before creating the release).
Build the source tree. The SQLStates are documented in the Reference Guide on the following page: `rrefexcept71493.dita`. This file is generated by the Derby build and placed in `classes/doc`. Take the version of this file generated by building the code branch and check it into the doc branch at `src/ref/rrefexcept71493.dita`. While you're at it, merge that change to the trunk so that the nightly build will generate an up-to-date Reference Guide too.
1. Sync the source and doc repository.
'svn up' in your subversion view to bring all files in your view up to the latest revision. Otherwise, the version output by svn which is captured for the build number will be a range (e.g. 290275:320938).
==== Build the release artifacts ====
1. Check you have all required pieces:
- doc tree
- with DITA library
- with latest SQLState
- `KEYS` checked in
- `RELEASE_NOTES.html` and CHANGES (''only for version < 10.3'') checked in.
- md5 & pgp and docs info set correctly in `tools/ant/properties/packaging.properties` and available (PATH)
- `ant.properties` set correctly for: jdk15, jdk16, jsr169
- sane not set in `ant.properties`
- non-source files for building source available: `junit.jar`, `felix.jar`, (with 10.3 and earlier: `osgi.jar`), dita library (again).
1. Build the documentation.
The documentation needs to be included in the -bin distribution and src, so you will need to access the doc branch when running the ant release target. The doc build is not controlled by the source tree build, and thus needs to be completed beforehand.
{i} Information on building the docs is located at [[http://db.apache.org/derby/manuals/dita.html]].
1. <<Anchor(CreateDistros)>>Create the distributions for release by running:
{{{
svn up
ant prepareforrelease
cd tools/release
ant release
ant sign}}}
(!) Note: ant prepareforrelease does a few basic checks, and then:
{{{
ant clobber
rm -rf jars javadoc snapshot # really clean
rm tools/release/*.zip tools/release/*.tar.gz # really,
rm tools/release/*.md5 tools/release/*.asc # really clean
ant sane ; ant all ; ant buildjars # for lib-debug
ant clobber
ant insane
ant -Dsane=false snapshot
ant publishedapi}}}
You will need to enter your PGP passphrase several times as the release distributions are signed.
(!) You can save yourself some typing by using gpg's `--passphrase-fd <fd>` option. This instructs gpg to read the passphrase from the specified file descriptor.
This will create the following files in your tools/release directory:
*db-derby-[version]-bin.tar.gz
*db-derby-[version]-bin.zip
*db-derby-[version]-lib.tar.gz
*db-derby-[version]-lib.zip
*db-derby-[version]-lib-debug.tar.gz
*db-derby-[version]-lib-debug.zip
*db-derby-[version]-src.tar.gz
*db-derby-[version]-src.zip
The Eclipse core plugin is generated in the snapshot directory at the top level by the snapshot target. You should also create the Eclipse UI plugins (see `plugins/eclipse/readme.txt`, except use the core plugin created in the snapshot directory), but this requires Eclipse. If you don't want to do it yourself, those interested in the Eclipse plugins will likely volunteer to generate them for you.
<!> Note that ui-plugin can be built as a ''beta''. If you don't build the ui-plugin yourself, make sure that its ''beta'' status matches that of the release candidate you are building.
You should also create checksums and signatures for these files with:
{{{
gpg --armor --detach-sign derby_ui_plugin_[version].zip
gpg --armor --detach-sign derby_core_plugin_[version].zip
md5 -q derby_ui_plugin_[version].zip > derby_ui_plugin_[version].zip.md5
md5 -q derby_core_plugin_[version].zip > derby_core_plugin_[version].zip.md5}}}
<<Anchor(SignOne)>> {X} There is a problem with the `ant sign` target on Cygwin that may occur elsewhere. If for some reason the `ant sign` target hangs, it may be prompting and waiting for input that you cannot see.
(!) In that case, you can also use this simple script to automate signing the release archives:
{{{
#!/bin/sh signone() {
gpg --detach-sign --armor $1
md5 -q $1 > $1.md5
}
signone $1-bin.tar.gz
signone $1-bin.zip
signone $1-lib.tar.gz
signone $1-lib.zip
signone $1-lib-debug.tar.gz
signone $1-lib-debug.zip
signone $1-src.tar.gz
signone $1-src.zip}}}
Invoking this 'sign.sh db-derby-10.1.1.0' would sign all of the release archives for Derby 10.1.1.0, for example.
{X} Be sure to replace the commands for gpg and md5 with the correct commands for your system. Note that on cygwin, the md5 switch is "-n" rather than "-q".
1. Verify the signatures and checksums.
As an example, the Derby 10.1 archives would be verified with GPG as follows:
{{{
gpg --verify derby_ui_plugin_1.1.0.zip.asc derby_ui_plugin_1.1.0.zip
gpg --verify derby_core_plugin_10.1.1.zip.asc derby_core_plugin_10.1.1.zip
gpg --verify db-derby-10.1.1.0-src.zip.asc db-derby-10.1.1.0-src.zip
gpg --verify db-derby-10.1.1.0-src.tar.gz.asc db-derby-10.1.1.0-src.tar.gz
gpg --verify db-derby-10.1.1.0-lib.zip.asc db-derby-10.1.1.0-lib.zip
gpg --verify db-derby-10.1.1.0-lib.tar.gz.asc db-derby-10.1.1.0-lib.tar.gz
gpg --verify db-derby-10.1.1.0-lib-debug.zip.asc db-derby-10.1.1.0-lib-debug.zip
gpg --verify db-derby-10.1.1.0-lib-debug.tar.gz.asc db-derby-10.1.1.0-lib-debug.tar.gz
gpg --verify db-derby-10.1.1.0-bin.zip.asc db-derby-10.1.1.0-bin.zip
gpg --verify db-derby-10.1.1.0-bin.tar.gz.asc db-derby-10.1.1.0-bin.tar.gz}}}
The md5 checksums can be verified by generating them via another method. For example, using openssl:
{{{
openssl md5 < db-derby-10.1.1.0-src.zip
}}}
And comparing the output of openssl to the output from ant in `db-derby-10.1.1.0-src.zip.md5`
1. Keep the `jars/insane/*.jar` and `jars/insane/derby.war` files available. You will need them for maven deployment after the vote is complete.
(!) It is advisable to copy the jars to another directory and include the version number of the release candidate in the directory name. This way you avoid having to extract the jars from the release artifacts if you inadvertently overwrite the jars (through a rebuild) before deploying to the maven repository.
1. <<Anchor(Bump4th)>>Bump the fourth digit of the source in preparation for a possible next build. I don't think this step does anything except update the last digit of the release id in release.properties. The bumped release id represents the head of the branch.
{{{
cd tools/release
ant bumplastdigit}}}
Commit the changed version number.
1. At the same time, make sure that you add the bumped release id to JIRA. This allows bugs to be marked as fixed at the head of the branch. See the following email thread for our latest thinking on this topic: http://old.nabble.com/Re%3A-Plans-for-a-10.5.3.1--tt26533770.html#a26577283
1. Post the distributions
a. Make sure the umask of your Apache account grants both read and write access to group (db) and only read access to others. {i} Read access for others is necessary for web access, and the write permission for the db group will make life easier for future release managers.
a. Create a new directory for the release candidate in your `people.apache.org:public_html` directory.
a. Upload all files from the `tools/release` directory into this directory.
a. Upload `snapshot/derby_core_plugin_x.y.z.rev.*` into this directory.
a. (Optional:) Upload `derby_ui_plugin_a.b.c.*` into this directory.
{i} If someone has volunteered to build the Eclipse plugin for you, you will have to defer this step until the volunteer has had a chance to download the other release artifacts which she will need to build the plugin.
<!> Remember to sign the `derby_ui_plugin.x.y.z.zip` before you upload it!
a. Post to derby-dev so that others can begin testing. (!) It is convenient to create a link to the release candidate directory from the release wiki page.
1. Vote on the distributions
Call for a vote on derby-dev to have the distributions posted on your `public_html` accepted for the release.
{i} It is not always easy to decipher all the voting rules which govern the acceptance/rejection of a release candidate. First there are the [[http://www.apache.org/foundation/voting.html|Apache rules for releases]], the [[http://db.apache.org/decisions.html|DB decision guidelines]], and finally the [[http://db.apache.org/management.html|DB PMC Bylaws]].
The existing practice is: A vote needs to be running for at least 7 days, so, give at least that much time before closing the vote to give adequate time for others to inspect and test the distributions. If no-one has responded after a week, prod gently until you get a response. A majority of votes, and at least one binding +1 vote are required for acceptance.
Forward or bcc a copy of the call for vote to private@db.apache.org so the DB PMC is aware that a vote is in progress. Also forward the results post to private@db.apache.org. ( <!> Note: do not '''cc''' the PMC; '''bcc''' or forward a copy of the post.)
==== During the vote ====
1. Address items on the ReleaseVettingChecklist
Make sure that the community addresses relevant items on the ReleaseVettingChecklist.
==== After an unsuccessful vote ====
1. If vote does not pass and go back to [[#TargetBugs|targeting bugs in Jira]].
If the vote does not pass and additional release candidates need to be made, then presumably it won't have passed because of a showstopper-type bug or similar issue, so you need to go back to the bug-fixing section.