db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Db-derby Wiki] Update of "ReleasePrep" by RichardHillegas
Date Tue, 12 Oct 2010 17:47:44 GMT
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.

Mime
View raw message