<scm> <connection>scm:git:git://github.com/picketlink/picketlink.git</connection> <developerConnection>scm:git:git@github.com:picketlink/picketlink.git</developerConnection> <url>http://github.com/picketlink/picketlink</url> </scm>
This page will highlight the steps needed to release PicketLink. The content has been heavily borrowed from the Seam Release Process (http://www.seamframework.org/Seam3/ModuleReleaseProcedure).
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:
<scm> <connection>scm:git:git://github.com/picketlink/picketlink.git</connection> <developerConnection>scm:git:git@github.com:picketlink/picketlink.git</developerConnection> <url>http://github.com/picketlink/picketlink</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/repositoryThat 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:
Here is an example https://github.com/picketlink/picketlink/blob/master/core/api/src/main/java/org/picketlink/Identity.java
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.
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:
PicketLink 3.0.0.Beta1
PicketLink 3.0.1.CR2
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.
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.picketlink:picketlink-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 PicketLink parent as your module's parent POM you inherit this configuration.
To be a release engineer, you first need to follow these steps:
Create an account on http://jboss.org
Request access on the security-dev mailinglist (Please provide your jboss username)
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 PicketLink 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:
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!)
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/'
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 PicketLink 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 -DdryRunThis 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:
Check that there are no uncommitted changes in the sources
Check that there are no SNAPSHOT dependencies
Change the version in the POMs from -SNAPSHOT to a new version
Run the project tests against the modified POMs to confirm everything is in working order
Commit the modified POMs
Tag the code in the SCM with a version name
Bump the version in the POMs to a new value -SNAPSHOT
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/anil/projects/picketlink with label: '3.0.0.Alpha1'
INFO Transforming 'PicketLink 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=falseOnce 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 -DreleaseIf that doesn't work, clean up manually:git checkout – pom.xml
rm -f release.propertiesThe 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 -DreleaseThe 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.picketlink.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.picketlink.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 usinggit 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/picketlink, go into a project that references your module and force Maven to pull it from the staging repository:mvn dependency:resolveYou 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:
Login to http://repository.jboss.org/nexus
Click on Staging Repositories link in the left hand navigation
Look for the staging activity with your username in the repository name with a status closed
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
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 PicketLink module distribution, switch to the tag you just created and install it.git checkout 3.0.m.QThen, from the root directory of the module, run:mvn clean install -DreleaseThat 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 picketlink/version directory 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 PicketLink 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/picketlink/3
The files under the {{3}} directory should match the following structure:3
| -- picketlink |
| | -- 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
The documentation artifacts are uploaded using a secure shell file transfer (scp, sftp or rsync) to seam@filemgmt.jboss.org:docs_htdocs/picketlink/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:
Checkout the release tag from git
Build the module distribution (or just the documentation)
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 picketlink@filemgmt.jboss.org:docs_htdocs/picketlink/3/
rsync -r --protocol=28 docbook/publish/ picketlink@filemgmt.jboss.org:docs_htdocs/picketlink/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 picketlink@filemgmt.jboss.org:docs_htdocs/picketlink/3/$MODULE/$RELEASE/
rsync -r --protocol=28 apidocs/ picketlink@filemgmt.jboss.org:docs_htdocs/picketlink/3/$MODULE/$RELEASE/api/
cd ../../..Remember to update the latest symlink. For this, you'll need to connect via sftp:sftp picketlink@filemgmt.jboss.org
sftp> cd docs_htdocs/picketlink/3/
{module}
sftp> rm latest
sftp> ln 3.0.m.Q latestIf 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
PicketLink project members, please refer to these two internal Red Hat documents for additional information about the documentation server, including how to request and setup access for a user:
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/picketlink/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).
Go to the Admin page for the project (which you get to through Administration)
Click on Manage versions
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)
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 PicketLink 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 PicketLink project page.
After you have published the blog entry, create a sticky forum entry in PicketLink 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)
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.