This page is an appendix to the overall Derby release instructions: DerbySnapshotOrRelease

Table of Contents


Once before release:

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

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

Work the toward a release candidate

  1. 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).
  2. Target the bugs you feel should be fixed in JIRA

    • All features and bug fixes should be tracked in JIRA: 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.

  3. Fix bugs and update STATUS

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

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

  6. Check that all creative works have ASF license headers.
  7. If you are building a release on the 10.6 branch or earlier, then you need to check that the version and copyright year are correct. For 10.7 and later releases, these tasks are performed automatically as part of building a release candidate:
    • Ensure that the end copyright 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.

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

and after the release has been voted on:

Although there are build tools that can automate most of these steps, you must carefully configure your machine and build environment for those tools to work successfully.

Underlying tools

You have to have to be able to do the following / use the following tools ( {i} see: BUILDING.html):

Supporting software

You have to have the following files available ( {i} see: BUILDING.html):

For 10.12 and earlier, you also need:

For 10.4 and earlier, you also need:

For 10.3 and earlier, you also need:

Inputs you get from Subversion

For the documentation and source building portions of the build, you need to at least have the doc tree and source tree available.

Configuring the build

Your ~/ file needs to include:

relnotes.src.reports=<location where you want to save/access the xml scripts for generating release notes>
docs.root=<location of the root directory of your docs client>
#sane=<sane should *not* be set>

But wait! There is more to put in your ~/! So please read on...

For 10.4 and earlier, your ~/ file also needs to include:

j14lib=<location of jdk14(2)/jre/lib>
jdk16=<location of jdk16>
jsr169compile.classpath=<location of jsr169 implementation>

Configuring the digesting and signing process

{i} There are special considerations for the digesting and signing process:

md5.exec=<name of your checksumming executable>
md5.options=<options to be passed on the command line to the checksumming executable>
pgp.exec=<name of your signing executable>
pgp.options=<options to be passed on the command line to the signing executable>

pgp.options=--detach-sign --armor

Something about site-dev that I don't understand (yet)

Also make sure that you are subscribed to 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.
  2. 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
  3. If you are building 10.6 or earlier, copy tools/ant/properties/packaging.tmpl to tools/ant/properties/ and modify as necessary.

    • The build will attempt to use a file called tools/ant/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 ~/ or on the ant command line (NOTE: does not work for these variables).

      {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 ~/ 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: A standalone md5 utility can be found at Note, for the executable available from this last location, the correct option for output is md5 -n.

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

      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. 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 PGP is a commercial product which is available from

      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/ at

      {X} You need to make sure the tools/ant/properties/ file (10.6 or earlier), or ~/ file (10.7 or later) has correct information for your pgp tool.

  5. Ensure you have appropriate jdks available. Unless you are building a 10.12 or earlier release, this is simply Java 8.
    • {i} For 10.4 and earlier, see: BUILDING.txt for information on JSR169 and OSGI support. For 10.12 and earlier, make sure you have Java 7. For 10.2 through 10.11, 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 so that the JDBC 4.0 classes are built and the JDBC 4.0 javadoc is created. For versions 10.4 through 10.10 (?), you need to also have jdk1.5 available

  6. 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/ to point to your local copy of the documentation.

      To build the documentation, you need to obtain and place it in the docs' tree lib.

      {i} See: 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

Create a new branch

For a major (feature) release, you must create a new branch for the release, in both the code and docs trees. See CreatingDerbyBranch . Do this just before you build the first release candidate.

ReleasePrep (last edited 2017-10-19 01:46:56 by RichardHillegas)