You can find the full source code for this website in the Seam package in the directory /examples/wiki. It is licensed under the LGPL.
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:
If someone would like to create a script for automating this work, we'll send you some Seam (or other JBoss) swag.
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.
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 ;)
Make sure you have a license on all your source files. Copy/paste it from this page:
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.
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).
Module versions should align with the JBoss Project Versioning Guidelines. As a rule though, we should follow this naming convention for qualifiers:
Some examples:
Version numbers in Maven should follow the format:
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.
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.
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.
To be a release engineer, you first need to follow these steps:
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:
gpg --gen-key- Use the default key type (DSA and Elgamal)
gpg --list-secret-keys- Your key id is the alphanum value after the slash in the line that begins with sec
gpg --list-secret-keys | grep '^sec' | sed 's/sec \+.*\/\([^ ]\+\).*/\1/'
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 ;)
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.
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:
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.
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 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
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>
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...
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:
closed
Releaseor
Drop
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
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.
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:
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:
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:
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.
There are three pages to update to list the availability of your release:
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:
Release the project in JIRA so that people are able to file bugs against the released version (otherwise, they will get filed incorrectly).
Review the scheduled versions for the project. Make sure future releases are in JIRA so that reported issues can be scheduled properly.
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:
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.
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!