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 2007/07/24 20:17:58 UTC
[Db-derby Wiki] Update of "TmpDerbySnapshotOrRelease" by MyrnavanLunteren
Dear Wiki user,
You have subscribed to a wiki page or wiki category on "Db-derby Wiki" for change notification.
The following page has been changed by MyrnavanLunteren:
http://wiki.apache.org/db-derby/TmpDerbySnapshotOrRelease
New page:
Temporary wiki page to work on Restructuring the instructions - see DERBY-2575.
== Releases ==
1. Announce your intention/desire to have a release on the list
As new features are added and bugs fixed, it is likely that someone will announce their intention to produce a release (if they are a committer) and volunteer to be the release manager. It may also be the case that a non-committer will ask when the next official release will occur. This should be a sign to committers that there is demand for a release. :)
1. Volunteer as release manager (or try to enlist one)
Since only committers have the necessary access to Apache resources to shephard a release to its completion, a committer must volunteer to be the release manager. Usually (hopefully) someone will volunteer if it is clear there is demand for a release. A release manager is under no obligation to finish once they volunteer, and another committer can pick up and complete their work, or even produce a competing release if so desired.
1. Target the bugs you feel should be fixed in JIRA
All features and bug fixes should be tracked in JIRA: http://issues.apache.org/jira/browse/DERBY
Mark the Fix In field for the JIRA entries for the items you want to be in the release with the proper version. Also, it's a good idea to post to derby-dev to get an idea of what features or fixes other contributors would like in the release.
1. Fix the bugs, update STATUS and CHANGES/RELEASE_NOTES.html as needed
Get to work! Add features, fix bugs, and update STATUS as you go. The wiki is nice, as are personal webpages, but STATUS is the designated place for Apache projects to keep their current status. Apache members and committers expect to be able to grab the STATUS file from the code tree to determine the current status of the project. It's a nice thing to keep the STATUS file on branches up to date with the current status of the branch. The other essential document is a document describing the changes. Derby branches up to 10.2 included a file 'CHANGES' for that purpose; 10.3 branch and trunk have a RELEASE_NOTES.html checked in. RELEASE_NOTES.html is generated using the generator in <10.3 branch and up/trunk>/java/build/org/apache/derbyBuild/ReleaseNotesGenerator.java.
1. Drive the bug list to zero.
As the list of remaining bugs in JIRA approaches zero, be sure to mark their status properly in JIRA. Mark blocker and critical bugs as such so that others can see the status at a glance. Move non-showstopper bugs out to future releases if it appears they will not be fixed for this release.
1. Drive the creation of release notes.
The release note generator expects files called 'ReleaseNote.html' for each item marked that is:
- resolved to 'Fixed'
- fixed in the release under study but not in the previous release
- marked with 'Existing Application Impact' or 'Release Note Needed'.
1. Check that all creative works have ASF license headers. See: [http://wiki.apache.org/db-derby/FixingLicenseHeader]. Also ensure that the year in NOTICE is correct.
1. Make sure your public PGP/GPG key is in the KEYS file
For information about PGP and why it is used to sign release binaries at Apache, please read [http://people.apache.org/~henkp/trust/].
You should create a PGP key for yourself if you do not have one, and upload it to at least one, preferably two, of the main public keyservers, e.g. pgp.mit.edu. You will need this key to sign the release binaries. Ideally, your key should be tied into the Apache web of trust.
GPG is available for a variety of platforms from http://gnupg.org. PGP is a commercial product which is available from http://pgp.com.
1. For major releases, create a new branch for the release, in both the code and docs trees.
{{{svn copy -r {rev} https://svn.apache.org/repos/asf/db/derby/code/trunk/ https://svn.apache.org/repos/asf/db/derby/code/branches/{branchname}/
svn copy -r {rev} https://svn.apache.org/repos/asf/db/derby/docs/trunk/ https://svn.apache.org/repos/asf/db/derby/docs/branches/{branchname}/}}}
There is not currently a target for bumping the version number on the trunk. You should edit release.properties by hand to bump the major/minor properties as appropriate, zero out the maint property, and ensure the beta flag is set to true. Then, from the top, run:
{{{java org.apache.derbyBuild.maintversion2props tools/ant/properties/release.properties tools/release/maintversion.properties}}}
{{{cd tools/release
ant regex.masters}}}
If you ended up creating a branch, add the new branch number to the list of Branches on the downloads page of the website. For pointers on how to edit the downloads page, see the "Update the website" section above in the Snapshot instructions.
See TODO in #8 for caveat concerning the beta flag. Don't forget to post to derby-dev requesting that a new version be added to JIRA for the next version of Derby.
1. Bump the third version number, adjust the beta flag, finalize CHANGES, and check in the new version and test masters. You will need to clobber and build to see the changed release number(s) reflected in the source. Note that the first release off a new branch is automatically beta, even if you set the beta flag in tools/ant/properties/release.properties to false. Also adjust version numbers in documentation by modifying the appropriate *conrefs.dita files.
There is not currently an ant target for bumping the third version number. The third and fourth parts of the version are combined into a single property, maint, where maint = (third digit * 1000000) + fourth digit. Also, if this is a major/minor (feature) release, you should remove the beta flag at this time. You should update tools/ant/properties/release.properties by hand and then run:
{{{java org.apache.derbyBuild.maintversion2props tools/ant/properties/release.properties tools/release/maintversion.properties}}}
{{{cd tools/release
ant regex.masters}}}
TODO: the regex.masters target does not currently account for changes in the beta flag.
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. Sync the 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).
1. Make sure your build will build all of the optional components.
Consult BUILDING.txt and make sure that your build will compile the optional pieces:
* The jdk1.6-specific classes (JDBC4 support)
* The OSGi support
* The JSR169 support
1. Check in the latest SQLState documentation.
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.
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. Information on building the docs is located at [http://db.apache.org/derby/manuals/dita.html].
1. Copy packaging.tmpl to packaging.properties in tools/release and modify as necessary.
Once you have a copy of the documentation on your local machine, you will need to update the property ${docs.out} in tools/ant/properties/packaging.properties to point to your local copy of the documentation. Check that the settings in tools/ant/properties/packaging.properties are correct for your md5 hash tool and pgp/gpg tool and then go to the next step.
Most Unix distributions come with either md5 or md5sum. An md5sum utility for Windows can be downloaded as a part of the !GnuWin32 port of the core Gnu utilities, from: http://gnuwin32.sourceforge.net/packages/coreutils.htm. A standalone md5 utility can be found at http://www.fourmilab.ch/md5/. Note for the executable available from this last location, the correct option for output is md5 -n.
1. Create the release distributions and checksums, sign the distributions
Check your classpath for osgi.jar for OSGI support and make sure jsr169compile.classpath is set for J2ME support. For 10.2 forward, make sure that you have JDK 1.6 available and that you've set the jdk16 property to the JAVA_HOME for your JDK 1.6 installation in your ant.properties so that the JDBC 4.0 classes are built and the JDBC 4.0 javadoc is created. If you have the sane property set in your ant.properties, remove it at this time to prevent it from overriding the false setting passed into the snapshot target. Create the distributions for release by running:
{{{svn up
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
cd tools/release
ant release
ant sign}}}
You will need to enter your PGP passphrase several times as the release distributions are signed. 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), 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. 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}}}
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. 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 PGP 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. Bump the fourth digit of the version
See step #4 in the snapshot section.
1. Post the distributions
Copy the files from tools/release to your public_html directory on people.apache.org. Post to derby-dev so that others can begin testing.
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. 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.)
1. Address items on the ReleaseVettingChecklist
Make sure that the community addresses relevant items on the ReleaseVettingChecklist.
1. If vote does not pass and go back to 'Drive bug list to zero'.
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, go back to the bug-fixing section.
1. If the vote passes, put distributions onto mirrors
First, read:
http://www.apache.org/dev/mirrors.html and
http://www.apache.org/dev/mirror-step-by-step.html
Copy the distribution archives and their signatures/checksums to a new directory underneath /www/www.apache.org/dist/db/derby on people.apache.org.
If the new release is the most current release, link the -current links to the new files. Here's a quick-and-dirty shell script for doing so:
{{{ln -s $1/$1-bin.tar.gz db-derby-current-bin.tar.gz
ln -s $1/$1-bin.tar.gz.asc db-derby-current-bin.tar.gz.asc
ln -s $1/$1-bin.tar.gz.md5 db-derby-current-bin.tar.gz.md5
ln -s $1/$1-bin.zip db-derby-current-bin.zip
ln -s $1/$1-bin.zip.asc db-derby-current-bin.zip.asc
ln -s $1/$1-bin.zip.md5 db-derby-current-bin.zip.md5
ln -s $1/$1-src.tar.gz db-derby-current-src.tar.gz
ln -s $1/$1-src.tar.gz.asc db-derby-current-src.tar.gz.asc
ln -s $1/$1-src.tar.gz.md5 db-derby-current-src.tar.gz.md5
ln -s $1/$1-src.zip db-derby-current-src.zip
ln -s $1/$1-src.zip.asc db-derby-current-src.zip.asc
ln -s $1/$1-src.zip.md5 db-derby-current-src.zip.md5}}}
which, if you called the script linkcurrent.sh and put it in your home directory, could be run as follows:
{{{cd /www/www.apache.org/dist/db/derby
~/linkcurrent.sh db-derby-10.1.1.0}}}
using db-derby-10.1.1.0 as the release to link to -current as an example.
If this release supercedes a previous release on a branch, be sure to move the old files to the archive. It is important that we keep our mirror directory tidy.
You should also make sure that your public PGP key is in the KEYS file at /www/www.apache.org/dist/db/derby/KEYS
1. Create a page for the release, build/update site
For instructions on how to build the website, see item 3 regarding snapshots above. It is a good idea to use the previous release pages as templates, filling in the changed details as necessary. You should add a .cgi and a .html file for the release. The main thing to remember is that the .cgi file should have the same name as the .html file. Also, when you run 'svn up' on people.apache.org (3e above), make sure that the new .cgi file is executable and otherwise has the correct permissions!
Note the following things when creating the release page:
* Be sure to specify that the src.tar.gz requires gnu tar to unravel (because of our usage of ant tar to create this, using longfile=gnu for handling long filenames).
* Forrest will not copy the release .cgi script over unless you make a link to it from another page. Add the link to derby_downloads.html before building.
* Make sure that the .cgi script is made executable by setting svn:executable on it with {{{svn propset svn:executable ON release-10.1.2.1.cgi}}}. Be sure to do this for both the precursor version you created in src/documentation/content/xdocs/releases and for the generated copy which forrest builds into build/site/releases.
* In order for the release HTML file to be pulled into the build, it is necessary to add a line to the <uris> section of src/documentation/conf/cli.xconf. Near line 310 of that file, add: <uri type="append" src="releases/release-10.1.2.1.html"/> (with the correct version for your release)
* Due to [http://issues.apache.org/jira/browse/FOR-480]FOR-480, the release page will be built into your $FORREST_HOME/main/site directory.
* Due to [http://issues.apache.org/jira/browse/FOR-555]FOR-555, the HTML comments which constitute the form template into which the mirrors.cgi script splices in the mirror information will be removed by Forrest. It is necessary to add these comments back in to the release page before committing or letting the site go live on people.apache.org.
* Subversion may report some files as changed which should be static. Revert anything in build/site/skin or build/site/papers before committing your website changes ([http://db.apache.org/derby/papers/derby_web.html#odd_diffs see the explanation]).
* Once you have committed your changes and updated the website on people, you can preview your changes by following the instructions at http://www.apache.org/dev/project-site.html
1. Deploy to Maven repository.
First, if you do not already have the latest Maven 1 distribution, download it from http://maven.apache.org/maven-1.x/start/download.html, unpack it, and put the bin directory into your path so that you can run maven commands. As of this writing, the latest 1.x version of Maven was 1.0.2.
Next, edit project.xml in the maven directory in the derby tree to contain the correct version number for this release between the <currentversion> tags. Then, edit the project.properties to contain the correct protocol, username, and password for your account on people.apache.org so you can properly authenticate and copy the files to people. The scpexe protocol should work without problems, especially if you have an ssh public key already on people. The project.properties file in the maven directory should look something like this, for the maven.repo lines in the file:
{{{maven.repo.list=apache
maven.repo.apache=scpexe://people.apache.org
maven.repo.apache.directory=/www/www.apache.org/dist/java-repository
maven.repo.apache.username={your_username}
maven.repo.apache.password={your_password}
maven.repo.apache.group=db}}}
Also, make sure you have the maven artifact plugin, version 1.5.2, so that maven generates SHA1 checksums for the files you upload, by running the following command:
{{{maven plugin:download -DgroupId=maven \
-DartifactId=maven-artifact-plugin \
-Dversion=1.5.2}}}
NOTE: this should only be necessary for Maven 1.0.2. The latest artifact plugin will be included in future stable releases of Maven 1.x.
Then, cd into Derby's maven directory and
$ maven # will attain the multiproject:install goal to install the artifacts into your local maven repo
$ maven clean # will attain the multiproject:clean goal to clean up the maven tree
$ maven multiproject:deploy # will copy all the artifacts into the apachecvs repository (note, for now this this has been disabled by commenting out the maven.repo.list definition in project.properties).
This does not build using maven, it works by copying the jars that ant built into jars/${sanity}.
After successfully deploying the jars to the maven repository on minotaur, you may receive an email that you did not upload appropriate PGP signatures for the new files added to www.apache.org/dist/. To prevent receiving this mail, you will need to sign the individual jars and then upload the signatures to /www/people.apache.org/repo/m1-ibiblio-rsync-repository/org.apache.derby/jars after running maven's multiproject:deploy target. The following script signs and renames the jars appropriately, and should be run in the jars/insane directory.
{{{for i in *.jar
do
gpg --armor --detach-sign $i // enter your PGP passphrase for each iteration.
done
for i in *.jar.asc
do
PREFIX=`echo $i | sed 's/.jar.asc//g'`
NEWNAME=$PREFIX-10.1.2.1.jar.asc //use the correct version number for this release.
mv $i $NEWNAME
done}}}
Then, upload the signatures to the jars directory:
{{{sftp {username}@svn.apache.org
cd /www/people.apache.org/repo/m1-ibiblio-rsync-repository/org.apache.derby/jars/
put *.jar.asc}}}
The deployment of the jars and poms to the Maven 1 repository will be automatically converted to appropriate jars and poms for Maven 2 and deployed to that repository as well. See [http://issues.apache.org/jira/browse/DERBY-1378 DERBY-1378] for more information on the automatic conversion to Maven 2.
Maven may not work for you. If Maven does not copy the build artifacts to subdirectories under /www/people.apache.org/repo/m1-ibiblio-rsync-repository/org.apache.derby/, then you will have to do this yourself. In this scenario, you must use Maven to deploy the build artifacts to your local file system and then sftp the results to people.apache.org. To deploy the build artifacts to your local file system, set up project.properties something like this:
{{{maven.repo.list=apache
maven.repo.apache=file://~/zdir
maven.repo.apache.directory=garbage
maven.repo.apache.username=garbage
maven.repo.apache.password=garbage
maven.repo.apache.group=garbage}}}
Then do
$ maven clean
$ maven multiproject:deploy
This will build the artifacts into a subtree rooted at garbage. Use sftp to bulk put the artifacts into the corresponding subdirectories of www/people.apache.org/repo/m1-ibiblio-rsync-repository/org.apache.derby/.
1. Update the Derby project DOAP file for an official release.
Update the release section in this file:
https://svn.apache.org/repos/asf/db/derby/site/trunk/doap_Derby.rdf
This DOAP file is the source for http://projects.apache.org/projects/derby.html . Projects are supposed to get updated periodically (you don't do anything to publish the update). If the update doesn't get generated within a day or two, send email to derby-dev@db.apache.org letting them know you updated the file and that the update appears to be delayed (site-dev@apache.org needs to be notified).
1. Announce the release.
Twenty-four hours after putting the release files in the mirror directory, verify that you can reach them through a mirror. Then, you should email derby-dev, derby-user, general@db.apache.org, announce@apache.org and anyone else you think might be interested an announcement concerning the release. See past release announcements for examples.
Include a description of the project, and a description of any significant new features or important bug fixes. Every tech news blog remotely related to Java or databases will pick up the announcement and post it verbatim, so it's a good idea to spell check it, proofread it a couple of times, and/or get input from derby-dev on its content.
1. Tag the release in subversion.
{{{svn copy -r {rev} https://svn.apache.org/repos/asf/db/derby/code/{trunk_or_branchname}/ https://svn.apache.org/repos/asf/db/derby/code/tags/{version}/
svn copy -r {rev} https://svn.apache.org/repos/asf/db/derby/docs/{trunk_or_branchname}/ https://svn.apache.org/repos/asf/db/derby/docs/tags/{version}/}}}
1. Update STATUS again.
Update STATUS to reflect that the release has occurred. Check in the new file. You're done!
== Snapshots ==
1. Update CHANGES.
Edit the CHANGES file to include a list of the bug fixes included in the snapshot. It is not necessary to make an exhaustive list of subversion commits. Only changes that would be visible to a user need to be included.
1.#2 Run the snapshot target.
At the top of your subversion view of the trunk or one of the branches, do:
{{{svn up
ant clobber
rm -rf jars javadoc snapshot # make sure everything is cleaned out
ant sane ; ant all ; ant buildjars # for the debug archives
ant clobber
ant insane
ant -Dsane=false snapshot}}}
It is best to do this in a view where there are no modified files or mixed revisions. This will create a snapshot directory at the top level, which will contain the five snapshot files:
* db-derby-snapshot-[version]-[changenumber].tar.gz
* db-derby-snapshot-[version]-[changenumber].zip
* db-derby-snapshot-debug-[version]-[changenumber].tar.gz
* db-derby-snapshot-debug-[version]-[changenumber].zip
* derby_core_plugin_[version]_[changenumber].zip
The need to run 'ant insane' as a separate step before the snapshot is filed in JIRA as DERBY-744.
1.#3 Update the website.
For instructions on how to build the website using Forrest, please see:
http://db.apache.org/derby/papers/derby_web.html
a. Place the five files created by the snapshot target into the src/documentation/content/xdocs/binaries directory of the location to which you checked out the website source. 'svn add' them, and 'svn delete' any old snapshot that the new snapshot is replacing. Don't forget to 'svn add' the files in the build part of the site tree.
b. Update the derby_downloads.xml page in the src/documentation/content/xdocs directory so that the links to the current snapshot point to your new files.
c. Run 'forrest site' at the top of the site tree.
d. Check the changes. If they look good, 'svn commit' them. NOTE: you should revert any changed files in build/tmp or build/site/skin. Also, please {{{svn delete}}} any old snapshot files that are no longer necessary.
e. Update the website on people.apache.org by logging into the machine and doing:
{{{cd /www/db.apache.org/derby
svn up}}}
Note that people.apache.org is rsync'd to the actual website every hour or so. Verify that the changes appear on the Derby website at http://db.apache.org/derby/derby_downloads.html
1.#4 Bump the version number.
In the tools/release directory, run the Ant bumplastdigit target.
{{{cd tools/release
ant bumplastdigit}}}
This target updates tools/ant/properties/release.properties and several test canons that contain the version number. Check that the version number is correct. 'svn commit' the changed files.
1.#5 Announce to the lists.
It's a good idea, once the snapshot has appeared on the site, to announce to derby-dev and derby-user that the new snapshot has been posted so interested testers can grab it.
Also, a new JIRA version will need to be created for the new, bumped version number. An email to derby-dev stating that you've bumped the version will (hopefully) be sufficient to get the attention of one of the Derby JIRA admins to add a new version in JIRA.