This document describes (in frightening detail) the release procedure for releasing an individual Seam module and provides a checklist of steps that must be completed for a successful release.

Let's begin with that checklist:

1. Check your SCM repository definition
2. Ensure all dependencies are released
3. Get licensed
4. Coordinate with QE to have your release tested (CR and Final releases only)
5. Select a version that adheres to the version guidelines
6. If this is your first time releasing, get setup on JBoss Nexus
7. Prepare, tag and publish the release with Maven
8. Build and publish the distribution
9. Upload the documentation (will need to be done by a Red Hat employee)
10. Add the release to sfwk.org
11. Release the project in JIRA
12. Version review
13. Announce the release on the blog and forums

If someone would like to create a script for automating this work, we'll send you some Seam (or other JBoss) swag.

SCM repository definition

You should have only one SCM repository definition, and it should be in the pom.xml at the root of your module (you module's parent). The definition should have both connection and developerConnection elements: (replace {module} with the name of your module in the following sample):

<scm>
   <connection>scm:git:git://github.com/seam/{module}.git</connection>
   <developerConnection>scm:git:git@github.com:seam/{module}.git</developerConnection>
   <url>http://github.com/seam/{module}</url>
</scm>

If that's not there, things will fail later. Let's go for success.

Check your dependencies!

Maven is strict about ensuring that all dependencies are non-snapshot before starting the release, which is not a bad thing! Also verify that all your dependencies are available in central.

You can go the long way and check out your project on another computer and have Maven resolve dependencies using a temporary repository location:

mvn dependency:resolve -Dmaven.repo.local=/tmp/repository

That command will bail if you were relying on dependencies that are not available in one of the remote repositories used by your module. The Maven release command, described below, will also tell you. If you do, we'll see you back here in a bit ;)

Get licensed!

Make sure you have a license on all your source files. Copy/paste it from this page:

Seam Licensing

Also, make sure you don't have any improperly licensed material in your source tree. This should be obvious point, but we'll say it anyway.

Coordinate with QE

Seam is unique in that we have a dedicated QE team to help ensure the software is dependable when released. This guarantee will improve over time, as QE understands your module better, you have more tests and examples with tests and QE has helped you setup acceptance tests on your module. So please, coordinate with QE in advance of making a final release of your module (not a requirement for Alpha and Beta releases).

Select a version

Module versions should align with the JBoss Project Versioning Guidelines. As a rule though, we should follow this naming convention for qualifiers:

• Alpha[n] for alpha releases
• Beta[n] for beta releases
• CR[n] for candidate releases
• Final for production releases

Some examples:

• Seam Faces 3.0.0.Beta1
• Seam Security 3.0.1.CR2
• Seam Faces 3.0.1.Final

Maven

Version numbers in Maven should follow the format:

• major.minor.micro.qualifier (e.g., 3.0.1.Beta1)

Snapshots should use a qualifier of SNAPSHOT for releases (e.g., 3.1.0-SNAPSHOT).

NOTE

We've changed from using a hypen (-) before the qualifier to using a dot (.) to comply with the aforementioned JBoss Project Versioning Guidelines.

Getting setup on JBoss Nexus

Seam releases and snapshots will be uploaded to the JBoss Nexus releases and snapshots repositories, respectively. and snapshots will be uploaded to the JBoss Nexus snapshots repository. Artifacts don't go directly to into the repository, however. They first get staged through Nexus and then get synced to the repository after a manual publishing step using a web interface.

NOTE

We originally planned to publish releases into Maven central, but it became an uphill battle for us to persuade all the dependent projects to publish their artifacts there. Besides, in the end, we believe the JBoss repository is going to be a better resource for our users anyway.

Repository configuration

Both of the JBoss Nexus repositories (staging and snapshots) are configured in the Weld parent project POM (org.jboss.weld:weld-parent), which is inherited by the Seam parent POM (svn folder: build/parent/pom.xml, artifact: org.jboss.seam:seam-parent):

<distributionManagement>
   <repository>
      <id>jboss-releases-repository</id>
      <name>JBoss Releases Repository</name>
      <url>https://repository.jboss.org/nexus/service/local/staging/deploy/maven2</url>
   </repository>
   <snapshotRepository>
      <id>jboss-snapshots-repository</id>
      <name>JBoss Snapshots Repository</name>
      <url>https://repository.jboss.org/nexus/content/repositories/snapshots</url>
   </snapshotRepository>
</distributionManagement>

Your module doesn't need any extra configuration. Just by using Seam parent as your module's parent POM you inherit this configuration.

Setting yourself up as a release engineer

To be a release engineer, you first need to follow these steps:

1. Create an account on http://jboss.org
2. Request access on the seam-dev mailinglist (Please provide your jboss username)
3. A project team member email Paul Gier, or create a helpdesk ticket, and someone from the JBoss.org team will add you as a release engineer

Then, you need to add your credentials to your ~/.m2/settings.xml file, as follows:

<settings xmlns="http://maven.apache.org/POM/4.0.0"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
   <servers>
      <server>
         <id>jboss-releases-repository</id>
         <username>[jboss username]</username>
         <password>[jboss password]</password>
      </server>
      <server>
         <id>jboss-snapshots-repository</id>
         <username>[jboss username]</username>
         <password>[jboss password]</password>
      </server>
   </servers>
</settings>

The server id matches the JBoss Nexus repositories defined in the Weld parent POM (which is inherited by the Seam parent POM).

You'll also need to have GnuPG set up on your machine and a published gpg key. GnuPG stands for GNU Privacy Guard and is used to used to encrypt data and to create digital signatures.

If you've never created a GPG key (or lost the passphrase to the one you have), you'll need to create one and publish it. You can either follow the official guide or this cheat sheet:

1. Generate a key pair:
   

   gpg --gen-key

   - Use the default key type (DSA and Elgamal)
   - Choose the keysize 2048
   - Set the key to not expire
   - Enter your official name (for trust)
   - Enter an e-mail address you will always have
   - Choose a strong passphrase (and write it down!)
   
   
2. Determine your key id (YOUR_KEY_ID)
   

   gpg --list-secret-keys

   - Your key id is the alphanum value after the slash in the line that begins with sec
   - Here's a script that will print just the key id
   

   gpg --list-secret-keys | grep '^sec' | sed 's/sec \+.*\/\([^ ]\+\).*/\1/'

3. Publish the key:
   

   gpg --keyserver pgp.mit.edu --send-key YOUR_KEY_ID

After you publish the key, you can search for it in the web search interface.

Now, you need to tell the build about your GPG key. Add this profile to ~/.m2/settings.xml and the Nexus plugin:

<settings xmlns="http://maven.apache.org/POM/4.0.0"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
   <servers>
      ...
   </servers>
   <profiles>
      <profile>
         <id>release</id>
         <activation>
            <property>
               <name>release</name>
            </property>
         </activation>
         <properties>
            <gpg.passphrase>[gpg passphrase]</gpg.passphrase>
         </properties>
      </profile>
   </profiles>
   <pluginGroups>
      <pluginGroup>org.sonatype.plugins</pluginGroup>
   </pluginGroups>
</settings>

Now you are a Seam 3 release engineer! Give yourself a pat on the shoulder. We will too, when it's time for you to release ;)

Driving the release with Maven

Maven will release so you don't have to. Well, you have to run the Maven goals. The Maven release plugin will update the version numbers in your POMs, execute the necessary git commands to create the git tag, publish the artifacts to a Nexus staging repository. The Nexus plugin will then close the staging repository in releasing for releasing. The release is a manual step that you will perform using the web-based Nexus UI (so you don't have to worry that you'll accidentally publish without knowing about it).

Before running any maven commands make sure you create a release branch (as documented at http://nvie.com/posts/a-successful-git-branching-model/). We highly recommend using git flow to do this:

git flow release start <release name>

but if not the previous link has information about creating a release branch. What this is doing is creating another branch from develop that will contain any release changes such as maven updates, last minute fixes, etc. It will later be merged to master and also develop.

Make sure maven does all of it's work on the release branch.

Dry run

First, you start with a dry run. This will only perform local changes. It will not touch git (replacing m with the micro version, Q with the qualifier of the release and R with the qualifier of the next anticipated release):

mvn release:prepare --batch-mode -Drelease -DdevelopmentVersion=3.0.m.R-SNAPSHOT -DreleaseVersion=3.0.m.Q -Dtag=3.0.m.Q -DdryRun

This command assumes you have a 3.0.m-SNAPSHOT. Replace the m with the micro version (e.g., 0, 1, 2, etc) and Q with the version qualifier of the release (e.g., Alpha1, Beta2, Final, etc).

Preparing a release goes through the following release phases:

1. Check that there are no uncommitted changes in the sources
2. Check that there are no SNAPSHOT dependencies
3. Change the version in the POMs from -SNAPSHOT to a new version
4. Run the project tests against the modified POMs to confirm everything is in working order
5. Commit the modified POMs
6. Tag the code in the SCM with a version name
7. Bump the version in the POMs to a new value -SNAPSHOT
8. Commit the modified POMs

If you have unreleased dependencies, the command will abort. If it succeeds, you will see output like this:

[INFO] Full run would be tagging /home/dallen/projects/seam/upstream/faces with label: '3.0.0.Alpha1'
[INFO] Transforming 'Seam Faces Module'...
[INFO] Not removing release POMs
[INFO] Full run would be checking in 1 files with message: '[maven-release-plugin] prepare for next development iteration'
[INFO] Release preparation simulation complete.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------

If you see that, you are good to go.

Tag

Now you are ready to tag the release. Run the command for real this time (replacing m with the micro version, Q with the qualifier of the release and R with the qualifier of the next anticipated release, as before):

mvn release:prepare --batch-mode -Drelease -DdevelopmentVersion=3.0.m.R-SNAPSHOT -DreleaseVersion=3.0.m.Q -Dtag=3.0.m.Q -Dresume=false

Once this finishes, verify that the tag appears in git (e.g. use a browser).

If you've made a mistake

If you make a mistake during release (or decide to back out and have a drink instead), you can easily undo this mistake using the following command:

mvn release:rollback -Drelease

If that doesn't work, clean up manually:

git checkout -- pom.xml
rm -f release.properties

The rollback goal won't remove any created tag, or work for undoing a branch, so you have to delete those manually using git. For example:

git push origin :3.0.m.Q

Release to Nexus

You are all tagged and now it is time to publish. You'll be using a combination of the Maven release plugin and the Nexus plugin to publish the artifacts. The Nexus plugin pushes the artifacts to a JBoss Nexus staging repository. From there, you'll use a web UI to publish the artifacts to the real JBoss Nexus repository.

Begin the publishing process by finalizing the release and pushing the artifacts to a staging repository using the Nexus staging plugin. Replace the tokens in the description according to the module name and release number. The description is optional, though it help you identify the staging repository in the Nexus UI.

mvn release:perform nexus:staging-close -Drelease

The command should exit giving you the URL to the staging repository.

[INFO] Using authentication information for server: 'jboss-releases-repository'.
[INFO] Logging into Nexus: https://repository.jboss.org/nexus
[INFO] User: [jboss username]
[INFO] Using the only staged repository available: jboss_release_staging_profile-049
[INFO] Closing staging repository for: 'org.jboss.seam.faces:seam-faces-parent:3.0.0-SNAPSHOT

-  jboss_release_staging_profile-049 (profile: JBoss Release Staging Profile)
   URL: https://repository.jboss.org/nexus/content/repositories/jboss_release_staging_profile-049

[INFO] The following CLOSED staging repositories were found for: 'org.jboss.seam.faces:seam-faces-parent:3.0.0-SNAPSHOT':

-  jboss_release_staging_profile-049 (profile: JBoss Release Staging Profile)
   URL: https://repository.jboss.org/nexus/content/repositories/jboss_release_staging_profile-049

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------

(Never mind the -SNAPSHOT references. You didn't mess it up, it just doesn't report the version correctly).

Now visit the URL that Nexus reported to you as closed and verify that the artifacts you are expecting to release appear there in the typical Maven structure. If that URL returns 404 or your artifacts aren't there, then something went wrong.

You'll also get an e-mail from Nexus notifying you that the artifacts were staged.

Once this is done you can safely finish the release branch using

git flow release finish <release name>

and push to GitHub. The above command will merge the release branch to master and also develop. The branch will then be deleted locally, you should also remote it from origin:

git push origin master develop :release/<release name>

Try it out (optional)

Before you push to the JBoss Community repository for all of eternity, you may want to verify your artifacts from the standpoint of a consumer (or you may ask QE team to do so). This is easy to do. First, note the URL that Nexus reported to you when you staged the artifacts. Add the following profile to your $HOME/.m2/settings.xml file and reference that URL:

   <profiles>
      ...
      <profile>
         <id>jboss-staging</id>
         <repositories>
            <repository>
               <id>jboss-staging</id>
               <releases>
                  <enabled/>
               </releases>
               <url>https://repository.jboss.org/nexus/content/repositories/jboss_release_staging_profile-XXX</url>
            </repository>
         </repositories>
      </profile>
   </profiles>
   <activeProfiles>
      ...
      <activeProfile>jboss-staging</activeProfile>
   </activeProfiles>

NOTE

If you are using the JBoss developer configuration, make sure that you negate the jboss-staging repository in the mirrorOf element:

<mirrorOf>*,!jboss-deprecated,!jboss-staging</mirrorOf>

Clear out your module's artifacts from your local repository:

rm -Rf $HOME/.m2/repository/org/jboss/seam/{module}

Now, go into a project that references your module and force Maven to pull it from the staging repository:

mvn dependency:resolve

You can also just create an example web application that uses your module, or anything that gets Maven to resolve it. Now you can inspect your local repository and make sure it fetched the right artifacts.

If everything looks good...

Make it official!

While you published your artifacts, they won't get automatically synced to the JBoss Community repository without a nod from you. You give the nod by promoting the staged artifacts through the Nexus web interface. Follow these steps to kick off the promotion:

1. Login to http://repository.jboss.org/nexus
2. Click on Staging Repositories link in the left hand navigation
3. Look for the staging activity with your username in the repository name with a status closed
4. Check the row and click Release or Drop
   - Release will begin a sync to the repository (Release is forever!)
   - Drop will discard the staging repository and you will have to release to Nexus again to get it back

When you click on Release, you will be prompted to enter a description. The description is optional. Just click Release (if you really mean it).

Now go have another drink (or chocolate) and check in a couple hours to verify the artifacts made it to the JBoss releases repository. Also look for an e-mail from Nexus notifying you that the artifacts were promoted.

If the tag has already been pushed to github you can use this to release from the tag on github:

release:perform nexus:staging-close -Drelease -Dtag=3.1.0.Beta1 -DconnectionUrl=scm:git:<git connection>

Typically the git connection is in the form of git://github.com/seam/module_name.git

Building the distribution

We provide zip distributions of each Seam 3 module on SourceForge, in the JBoss project. A release can be performed by any member of a project team, not just Red Hat employees. However, you will need to have the Release Technician in the JBoss SourceForge project. To request the Release Technician role, email mailto:help.AT.jboss.org.

To create a Seam 3 module distribution, switch to the tag you just created and install it.

git checkout 3.0.m.Q

Then, from the root directory of the module, run:

mvn clean install -Drelease

That will generate the distribution zip file. You then need to follow the instructions on the Release files for download page to upload the zip. You should put the zip in the Seam/{Module short name}/{version} directory, where {Module short name} is the capitalized short name of the module (no spaces) and {version} is the version of the release. (For example, Seam/Faces/3.0.0.Alpha1 and Seam/Security/3.0.0.Beta1)

You'll need to wait up to an hour while SourceForge replicates the file. Check back to the main file download page to see if the file is available.

Uploading the documentation

The documentation for Seam 3 modules consists of the reference guide and the API docs (e.g., JavaDoc) and is organized by module under the following URL:

http://docs.jboss.org/seam/3

The files under the 3 directory should match the following structure:

3
|-- moduleA
|   |-- 3.0.0.Beta1
|   |   |-- api
|   |   \-- reference
|   |       \-- en-US
|   |           |-- html
|   |           |-- html_single
|   |           \-- pdf
|   |-- ...
|   |-- 3.0.0.Final
|   |   |-- api
|   |   \-- reference
|   |       \-- en-US
|   |           |-- html
|   |           |-- html_single
|   |           \-- pdf
|   |-- latest -> 3.0.0.Final
|   \-- snapshot
|       |-- api
|       \-- reference
|           \-- en-US
|               |-- html
|               |-- html_single
|               \-- pdf
\-- moduleB
    |-- 3.0.0.Alpha1
    |   |-- api
    |   \-- reference
    |       \-- en-US
    |           |-- html
    |           |-- html_single
    |           \-- pdf
    \-- latest -> 3.0.0.Alpha1

The documentation artifacts are uploaded using a secure shell file transfer (scp, sftp or rsync) to seam@filemgmt.jboss.org:docs_htdocs/seam/3. Access is restricted to designated Red Hat employee accounts (and in some cases to community contributors).

NOTE

If you need access to upload documentation, please coordinate with a Seam project member from Red Hat (preferably the project lead).

The general upload process is as follows:

1. Checkout the release tag from git
2. Build the module distribution (or just the documentation)
3. Execute the following commands to prep the remote directory and upload the documentation (replacing {module} with the name of the module directory and 3.0.m.Q with the release version):

export MODULE={module}; export RELEASE=3.0.m.Q
cd docs/target
mkdir -p $MODULE/$RELEASE/reference
rsync -r --protocol=28 $MODULE seam@filemgmt.jboss.org:docs_htdocs/seam/3/
rsync -r --protocol=28 docbook/publish/ seam@filemgmt.jboss.org:docs_htdocs/seam/3/$MODULE/$RELEASE/reference/
cd ../..

You can then copy the apidocs. Return the root of the release tag checkout, then type:

cd api
mvn javadoc:javadoc
cd target/site
mkdir api
rsync -r --protocol=28 api seam@filemgmt.jboss.org:docs_htdocs/seam/3/$MODULE/$RELEASE/
rsync -r --protocol=28 apidocs/ seam@filemgmt.jboss.org:docs_htdocs/seam/3/$MODULE/$RELEASE/api/
cd ../../..

Remember to update the latest symlink. For this, you'll need to connect via sftp:

sftp seam@filemgmt.jboss.org
sftp> cd docs_htdocs/seam/3/{module}
sftp> rm latest
sftp> ln 3.0.m.Q latest

If you have the SSHFS installed, the remote file commands above can be simplified to local file commands.

export MODULE={module}; export RELEASE=3.0.m.Q
mkdir -p ~/mount/seamdocs
sshfs seam@filemgmt.jboss.org:docs_htdocs/seam/3 ~/mount/seamdocs
mkdir -p ~/mount/seamdocs/$MODULE/$RELEASE/reference
cp -R docs/target/docbook/publish/ ~/mount/seamdocs/$MODULE/$RELEASE/reference/
mkdir -p ~/mount/seamdocs/$MODULE/$RELEASE/api
cp -R api/target/site/apidocs/ ~/mount/seamdocs/$MODULE/$RELEASE/api/
cd ~/mount/seamdocs/$MODULE
rm latest
ln -s $RELEASE latest
cd
fusermount -u ~/mount/seamdocs

Seam project members, please refer to these two internal documents for additional information about the documentation server, including how to request and setup access for a user:

• Getting access to filemgmt.jboss.org
• Uploading files to docs.jboss.org
• Access and upload instructions for docs.jboss.org (RichFaces-specific example)

Before moving on, check to make sure the documentation appears under http://docs.jboss.org/seam/3. Keep the link to the documentation handy, as you'll use it in the next section when adding the release to sfwk.org.

Adding the release to sfwk.org

There are three pages to update to list the availability of your release:

• Maven artifacts
• Distribution downloads
• Documentation

Just follow the yellow brick road, so to speak, to add your release. Be sure to test all the links before calling it done.

Furthermore, if this is the very first release of a module, also edit these pages:

• Seam 3.0 Roadmap
• Project Status And Direction

Releasing the JIRA project

Release the project in JIRA so that people are able to file bugs against the released version (otherwise, they will get filed incorrectly).

1. Go to the Admin page for the project (which you get to through Administration)
2. Click on Manage versions
3. Click the Release link in the row of the version you are releasing (If there are any open issues, JIRA will ask you if you want to move them)

Version review

Review the scheduled versions for the project. Make sure future releases are in JIRA so that reported issues can be scheduled properly.

Announcing the release

Create a new blog post on in.relation.to to announce your release. Be sure to tag the entry Seam 3.

NOTE

If you don't have an in.relation.to account, we encourage you to post on your personal blog on JBoss Community (every member can have a personal blog). If it's your first entry, let a Seam administrator know so your feed can be added to the aggregated feed on the Seam 3 project page.

After you have published the blog entry, create a sticky forum entry in Seam 3 users that links to the blog post. You should look at a previous release announcement for a template. Be sure to include the following items:

• Module name and version number
• What the module is (mission statement)
• Pertinent release notes (the exciting stuff)
• A list of contributors that put work into this release
• Next steps and future work
• Links to all the critical resources (Download, Maven artifacts, API, JavaDoc, reference guide, JIRA, etc)

Publicize your blog

A good way to drive traffic to your blog entry is to post it on DZone.com, make sure to use a catchy (but accurate) title, an enticing description (2-3 sentences), and tweet / email all your friends to have them read and vote on it.

You're done!

If you've made it this far, go have an expensive beer or fine chocolate. For beer, I recommend a Chimay Blue, Grande Reserve. For chocolate, I recommend Neuhaus (or any Belgium Chocolatier). These are delicacies fit for such an occasion. You may have your own way of celebrating. Either way, enjoy!