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:47:44 UTC
[Db-derby Wiki] Update of "ReleasePrep" by RichardHillegas
Dear Wiki user,
You have subscribed to a wiki page or wiki category on "Db-derby Wiki" for change notification.
The "ReleasePrep" page has been changed by RichardHillegas.
http://wiki.apache.org/db-derby/ReleasePrep
--------------------------------------------------
New page:
This page is an appendix to the overall Derby release instructions: DerbySnapshotOrRelease
'''Table of Contents'''
<<TableOfContents(4)>>
=== Timeline ===
Once before release:
* volunteer for release manager and announce this
* create wiki pages (main, buddytesting, platform testing, app testing) for release
* troll for buddies for buddytesting
* (optional:) create branch
* ensure you have all required tools and files
* ensure your KEYS are in place, and signed
* create `packaging.properties` based on `packaging.tmpl`
=== Before a candidate can be generated ===
==== Prepare the community for a new release ====
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 shepherd 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. Create wiki pages for the release. (Unless you have already done so. It may be convenient to have a wiki page prior to feature freeze and branch cutting). Use pages for a previous release as a template. You're likely to create a general page and a page to hold the testing information.
1. <<Anchor(CutBranch)>>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}/ -m "Created the {branchname} source branch"
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}/ -m "Created the {branchname} doc branch"
}}}
Post a message to derby-dev@db.apache.org requesting that a Hudson build job is created for the new branch.
1. After creating the branch, bump the version number on '''trunk'''. There is not currently an ant target for bumping the version number on the trunk so you need to edit `tools/ant/properties/release.properties` on trunk by hand. Bump the major/minor properties as appropriate, zero out the maint property (if it isn't zero already), and ensure the beta flag is set to true (if it isn't already). E.g. after bumping from 10.4 to 10.5 `release.properties` should look similar to:
{{{
#Wed Jul 19 08:21:42 PDT 2006
drdamaint=0
maint=0000000
major=10
minor=5
eversion=10.5
beta=true
copyright.comment=Copyright 1997, 2008 The Apache Software Foundation or its licensors, as applicable.
vendor=The Apache Software Foundation}}}
(!) It is probably a good idea to update to the head of trunk, and do a clean build (`ant clobber; ant all`) and run some tests before committing the change.
1. Also consider bumping the version number for the upgrade tests on trunk at this time; in method boot in java/engine/org/apache/derby/impl/sql/catalog/!DataDictionaryImpl.java, modify the value for softwareVersion. But this can also be done the next time new upgrade tests get added on trunk.
1. <<Anchor(BranchVersion)>> On the '''new branch''', edit `tools/ant/properties/release.properties` and update the value of the `maint` property. The exact value of depends on the type of release (feature, update or snapshot). For a new feature release the value will typically be
{{{
maint=1000000
}}}
This will set the version string for the branch to
{{{
<major>.<minor>.1.0 (beta)
}}}
The relationship between the `maint` property and the version number reported by `sysinfo` is given by the following equation: `maint=100000*3rd+4th`, (or `maint=1000000*fixpack+point` as described in the [[http://db.apache.org/derby/papers/versionupgrade.html|Derby Versioning Scheme]]. Note that a "fixpack" of 0 overrides the `beta` property in `tools/ant/properties/release.properties` and tags the version string with "alpha"). See also the description of how to [[#ReleaseCandidate|spin a release candidate]].
(!) It is probably a good idea do a clean build (`ant clobber; ant all`) and run some or all tests before committing this change to the branch.
<!> For releases off branches older than 10.4, you need to first run ant regex (in tools/release) to automatically update version references in a number of master files. These changed master files also need to be checked in.
1. Add the new branch number to the list of branches on the source page of the website.
{i} For instructions on how to build the website using Forrest, please see: [[http://db.apache.org/derby/papers/derby_web.html]]
The actual page to modify is `src/documentation/content/xdocs/dev/derby_source.xml`. For a minor (bug fix) release, consider bumping the third version of the source tree it will come off (likely a branch).
==== Work the toward a release candidate ====
1. <<Anchor(VersionInJIRA)>> Arrange for the new version(s) in JIRA.
Unless you are a Jira-admin you need to post to derby-dev requesting that new versions be added to JIRA. For any release you need a new version for the (beta) release candidate. When creating a new branch you also need a new development version for trunk, (unless this has been done earlier for some reason).
1. <<Anchor(TargetBugs)>> 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 bugs and update `STATUS` (and `CHANGES.html`/`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.
{i} Derby branches up to 10.2 included a file `CHANGES` for that purpose; 10.3 branch and trunk have `RELEASE_NOTES.html` checked in and `CHANGES.html` which is generated for the release. The process of generating these files is described at the ReleaseNoteProcess wiki page.
1. <<Anchor(DriveBugListToZero)>> 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'.
{i} More info can be found at ReleaseNoteProcess.
1. Check that all creative works have ASF license headers.
{i} See: [[http://wiki.apache.org/db-derby/FixingLicenseHeader]].
1. Check that the year and other information is correct.
Ensure that the year in `NOTICE` is correct.
<!> Ensure that all versions and copyright details in the docs tree are correct, this includes the top level `conrefs.dita`, as well as lower level dita files.
1. Fix outstanding release generation bugs.
Take a look at JIRAs in the "Build tools" component, looking for ones which have been labeled with the "releasegeneration" tag. You may want to fix some of these before building a release candidate.
==== Environment requirements for the release manager ====
To be able to produce the release artifacts, you need to
* update version numbers and run tests to verify it was correct
* generate release notes and `CHANGES.html`
* build all in doc and source objects (except for eclipse ui and doc plugins, those are optional)
* sign
* verify
and after the release has been voted on:
* modify derby web
* distribute to maven
This means you have to have to be able to do the following / use the following tools ( {i} see: `BUILDING.html`):
* md5 {X} The tool for generating md5 sums varies between systems. You may have to use `md5sum` or `digest -a md5`. {i} See also how to configure the [[#CopyPkgTmpl|ant sign target]])
* pgp ( {i} see: [[http://people.apache.org/~henkp/trust/]], [[http://gnupg.org]] or [[http://pgp.com.]] )
* ant
* dita ( {i} see: [[http://db.apache.org/derby/manuals/dita.html]] )
* forrest ( {i} see: [[http://db.apache.org/derby/papers/derby_web.html]] )
* eclipse (optional:)
And you have to have the following files available ( {i} see: `BUILDING.html`):
* junit.jar (put this in tools/java)
* `DITA-OT1.1.2.1_bin-ASL.zip` ( {i} see: [[http://db.apache.org/derby/manuals/dita.html]])
For 10.4 and earlier, you also need:
* j2me implementation
* jdk16 implementaion
For 10.3 and earlier, you also need:
* osgi support (for 10.3 and earlier `osgi.jar` - see: `BUILDING.txt` for your version. 10.4 and later always builds this using `tools/java/felix.jar`)
You need to at least have the doc tree and source tree available, and your `ant.properties` file needs to include:
proceed=true
relnotes.src.reports=<location where you want to save/access the xml scripts for generating release notes>
#sane=<sane should *not* be set>}}}
For 10.4 and earlier, your `ant.properties` file also needs to include:
{{{
j14lib=<location of jdk14(2)/jre/lib>
jdk16=<location of jdk16>
jsr169compile.classpath=<location of jsr169 implementation>}}}
{i} Special consideration for non-linux users:
{X} [[#CopyPkgTmpl|ant sign]], the last step in the ant release process, may not work. <!> Try it out before the release time arrives!
{X} Your md5 tool may be different. You will most likely need to [[#CopyPkgTmpl|configure the ant sign target for your system]]. {i} You do this by copying `packaging.tmpl` to `packaging.properties` and adjust it appropriately for your system.
(!) If you cannot do this, you may achieve the same using [[#SignOne|this script]].
Also make sure that you are subscribed to site-dev@apache.org. You may need to prod that list at the end.
==== Steps to prepare your machine/code check-out for the release process ====
1. Get a clean copy of the source tree for your version
A clean check-out is best.
1. For 10.4 and earlier, obtain files for building all optional pieces:
Consult BUILDING.txt and make sure you have all relevant pieces not in the source tree:
* jdk14
* jdk15 (after 10.3.*)
* jdk16
* junit.jar
including those required for building the optional pieces:
* The jdk1.6-specific classes (JDBC4 support)
* The OSGi support (osgi.jar or felix.jar. felix.jar should be automatically present in `tools/java` with 10.4 and later).
* The JSR169 support
1. <<Anchor(CopyPkgTmpl)>>If you are building 10.6 or earlier, copy `tools/ant/properties/packaging.tmpl` to `tools/ant/properties/packaging.properties` and modify as necessary.
The build will attempt to use a file called `tools/ant/properties/packaging.properties` to carry out checksum (md5)and signing (pgp) tasks. If you are building 10.7 or later, then override the values in packaging.tmpl as you would any other ant variables: i.e., override them as necessary in ant.properties or on the ant command line.
{X} Because this differs per operating system, you have to create this file based on the template (`tools/ant/properties/packaging.tmpl`) or override the values in ant.properties. packaging.tmpl is set for a likely linux environment.
{i} 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. Make sure your public PGP/GPG key is in the KEYS file, and preferably after it has been signed.
{i} 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. Your key should be tied into the Apache web of trust, which means you should have at least one person sign your key, and you should have done `gpg --refresh-keys` to get that person's signature before you follow the steps at the top of the `KEYS` file.
{i} GPG is available for a variety of platforms from http://gnupg.org. PGP is a commercial product which is available from http://pgp.com.
Your KEY needs to be in the `KEYS` file in trunk, `KEYS` file on the branch if you've created one, and the KEYS file in `/www/www.apache.org/dist/db/derby` at `people.apache.org`.
{X} You need to make sure the `tools/ant/properties/packaging.properties` file (or ant.properties) has correct information for your pgp tool.
1. Ensure you have appropriate jdks available
{i} For 10.4 and earlier, see: `BUILDING.txt` for information on JSR169 and OSGI 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.
For versions after 10.3, you need to also have jdk1.5 available
1. Check out a clean copy of the doc tree
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.
To build the documentation, you need to obtain `DITA-OT1.1.2.1_bin-ASL.zip` and place it in the docs' tree lib.
{i} See: [[http://db.apache.org/derby/manuals/dita.html]] for more info about building the documentation.
<!> If you see ''branch target offset too large for short'', try ant -lib lib target_list. If you run out of memory, export ANT_OPTS=-Xmx512m
1. (Optional:) Have eclipse installed or make arrangements with someone willing to build the eclipse ui plugin. As release manager you need to have access to the plugin zips if you don't build them yourself (e.g. the volunteer can attach the plugin zips to a Jira issue). <!> If you are not building the plugin yourself, make sure that the ''beta'' status of the plugin matches that of the release candidate you are building.