- Whenever possible, use the maven release plugin. If something doesn't work file a bug against it.
- Use extreme caution in creating branches as opposed to releasing from trunk. While "core" geronimo may need to keep branches, most smaller projects such as specs, plugins, components, and most likely tools should avoid the complexity of branches unless clearly necessary and agreed upon.
- When branches are needed, branches/x.y would be the branch for all x.y.z releases
The next sections are copied from http://maven.apache.org/developers/release/releasing.html with modifications for Geronimo.
Releasing A Geronimo Project
What follows is a description of releasing a Geronimo project to a staging repository, whereupon it is scrutinized by the community, approved, and transfered to a production repository.
Be sure that:
- you have all Maven servers defined in your
settings.xml. For more information, please refer to Maven Committer settings which also apply for Geronimo committers.
- you have created your GPG keys. For more information, please refer to Making GPG Keys.
In order to release a project you must also have the following setup in your
$HOME/.m2/settings.xml which is a profile that defines the staging repository.
Here's what your release profile might look like in your
Everything that you need to release has (will have, actually) been configured in the genesis root pom all Geronimo projects inherit from.
Your project should adhere to standard trunk,branches,tags svn layout in which case no further release profile configuration should be needed. Some slight deviation such as our specs project still works without extra configuration. Avoid more complex layouts that require special configuration.
This is the base release configuration in the genesis root pom:
Release Process for Part Of Geronimo
1. Prepare your poms for release:
Genesis and the recommended settings.xml file above rely on the existence of some configuration in the top level pom in your project to parameterize where in your staging area the release will be located. This makes it so you can have multiple independent releases under vote in your staging area at once, and clearly locates the maven generated site in the documentation once the release is completed. You should only need to do this the first time these instructions are used.
- Try out the release and look for anything strange such as incorrect target locations in the modified poms, missing licenses, etc.
- Diff the original file
pom.xmlwith the one called
pom.xml.tagto see if the license or any other info has been removed. This has been known to happen if the starting <project> tag is not on a single line. The only things that should be different between these files are the
<scm>elements. Any other changes, you must back-port yourself to the original
pom.xmlfile and commit before proceeding with the release.
- Remember to do
mvn release:cleanbefore you start the real release process.
2. (optional) Publish a snapshot:
3. Prepare the release
Preparing the release will create the new tag in SVN, automatically checking in on your behalf.
4. Make a copy of the checked out project in this state in case you need to roll back the release
AFAICT mvn release:rollback only works on a checkout on which mvn release:prepare has been run but not mvn release:perform.
5. Stage the release for a vote
6. Stage the latest documentation (if there is an actual maven generated site)
7. Propose a vote on the dev list with the closed issues, the issues left, the staging repository and the staging site. For instance:
Once a vote is successful, post the result to the dev list and cc the pmc.
In case the vote fails, rollback the release using the backup copy you made in step 4
You also have to remove the tag from svn by hand.
8. Copy from the staging repo to the production repo
Once the release is deemed fit for public consumption it can be transfered to a production repository where it will be available to all users.
Note: Current version of the stage plugin is 1.0-alpha-1. There's probably an easier way, but I added it to a pom and built to pull it down.
Here is an example on how to use the stage plugin:
9. Deploy the current and versioned websites (if there is a reasonable maven generated site)
10. Review Website (if any)
Wait for the files to arrive at
11. Update the plugins page
If this is a plugin release, update the apache
PROPOSAL ON HOW TO DO THIS:
First, perform the release. This process could be done as part of the release but that may be too confusing. The important point is to build the new tag with a fresh copy of geronimo-plugins.xml.
geronimo-plugins.xml is located in svn under e.g. geronimo/site/trunk/docs/plugins/geronimo-2.1/geronimo-plugins.xml
copy this file to
mvn clean install on a fresh checkout of the new tag.
copy the merged geronimo-plugins.xml back your svn site checkout.
Put the apache license header back in to the merged file (the car-maven-plugin removes it)
Edit the source-repository elements in the new plugins if necessary. They should contain
and most likely nothing else.
commit the svn revisions.
12. Update JIRA
Go to Admin section in JIRA and move the released version to released and make a new version.
13. Create an Announcement. For instance:
14. Add the release to the next board report, in the private subversion area.
15. Add the release to the wiki, under the Recent Releases section of the front page and on the Releases page.
16. Celebrate :o)
Notes and Gotchas
- If the selection of modules for the default build is set in a default profile then more work will be necessary. When genesis did not have the modules specified in the base pom this involved running mvn release:perform -Pdefault,release which only deploys the root, then running mvn deploy -Prelease in each of the 3 modules listed in the default profile. For projects that are not expected to be used as parents of independently releasable projects (for instance server/trunk) including the list of modules in the release profile override should work. Better still is just having the modules outside a profile.
When using the maven release plugin is impossible (this should be a less frequent event as we progress):
- when a release is frozen, we spin off a branch with that exact name, as in branches/x.y.z, where z starts at zero and increments by one.
- at that time branches/x.y is immediately updated to version x.y.(z+1)-SNAPSHOT
- We cut releases from the frozen branch
- When a release passes final tck testing and final vote, the frozen branch is moved to tags
Updating the poms after making a new branch
Once a new branch is created you will generally need to manage the version number in the poms. The following Perl scripts will assist in that task. It could use some polishing but given the relatively infrequent use.
Remember to properly escape periods in the oldVersion. For instance, to change 1.1.1-SNAPSHOT to 1.1.1 you would have
We create a branch at freeze time for the following reasons:
- it takes at least one week from freeze to ship due to voting, tck testing and potential repeats of that process (re-cut, re-certify, re-vote). There is no reason why work on x.y.z+1 needs to be delayed - only 52 weeks a year.
- stronger guarantee no one is updating the branch once frozen
- less likely that people and ci systems (continuum) will checkout and build pre-release versions of x.y.z (not x.y.z-SNAPSHOT) which would need to be removed manually and may accidentally be distributed.
- it is currently very difficult to roll version numbers forward, entries here and there are often missed. Far better to have branches/x.y have a few straggling old x.y.z-SNAPSHOT versions than a few overlooked x.y.z final numbers that needed to go back to SNAPSHOT - they never leave SNAPSHOT and need to be reverted back later if that process happens in the frozen branch.
- Download and install the Gnu Privacy Guard (GPG) from http://www.gnupg.org. Read the documentation on that site and create a key. Have the key signed and verified by others. Submit your public key to http://pgp.mit.edu/. This is a one time process.
- Create a "staging" profile in your
- Copy (or move as per situation, for eg specs) the trunk to branches using the following command.
- Checkout or update this branches tree on your machine.
- Update the <scm> urls in the
pom.xmlto point to the final url in tags. Eg:
- Build the new branches tree that will soon be released using the following command.
- Go the temporary staging directory specified by
deploy.altRepositoryelement in the staging profile of your
settings.xml. Delete all *.asc.* files under this directory tree. Tar the staging directory using the command
- Copy the tar ball to a publicly accessible location. Put it for a vote. In the vote notice, please include the precise names and versions being voted on (e.g. geronimo-javamail_1.4_spec-1.1) and the svn urls to the current source and where the tag will be created.
- After it has been approved, untar the tar ball into the appropriate maven structure on people.apache.org under the directory /www/people.apache.org/repo/m2-ibiblio-rsync-repository. A cron job will rsync this with ibiblio and release it into the wild.
- Move the branches to tags using the following command.
The original process in this document was voted on by the Geronimo community. Please formally propose all changes to firstname.lastname@example.org.
Revised process using maven tools voted on in March 2008. Only major structural changes now require votes.
See: (not yet in archive)