Release Management
Sling releases (and SNAPSHOTS) are deployed to the Nexus repository instead of the traditional deployment via the Maven 2 mirros source on people.apache.org. This makes the release process much leaner and simpler. In addtion we can benefit from the Apache Parent POM 6, which has most of the release profile setup built-in.
Most of the hard work of preparing and deploying the release is done by Maven.
Prerequisites
- To prepare or perform a release you MUST BE at least be an Apache Sling Committer.
- Each and every release must be signed; therefore the public key should be cross signed by other Apache committers (not required but suggested) and this public key should be added to http://www.apache.org/dist/sling/KEYS (See Appendix A)
- When preparing the release on Mac OS X, check out Appendix B before trying the steps in the next chapter.
- Make sure you have all Apache servers defined in your settings.xml
Note: Listing the Apache servers in the settings.xml file also requires adding the password to that file. Starting with Maven 2.1 this password may be encrypted and needs not be give in plaintext. Please refer to Password Encryption for more information.
In the past we staged release candidates on our local machines using a semi-manual process. Now that we inherit from the Apache parent POM version 6, a repository manager will automatically handle staging for you. This means you now only need to specify your GPG passphrase in the release profile of your ${user.home}/.m2/settings.xml:
<settings>
...
<profiles>
<profile>
<id>apache-release</id>
<properties>
<gpg.passphrase> </gpg.passphrase>
</properties>
</profile>
</profiles>
...
</settings>
Everything else has been configured in the latest Sling Parent POM:
<parent>
<groupId>org.apache.sling</groupId>
<artifactId>sling</artifactId>
<version>6</version>
</parent>
Staging the Release Candidates
First prepare your POMs for release:
- Make sure there are no snapshots in the POMs to be released
- Check that your POMs will not lose content when they are rewritten during the release process
Compare the original pom.xml with the one called pom.xml.tag to 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 <version> and <scm> elements. If there are any other changes, you must fix the original pom.xml file and commit before proceeding with the release.
- Publish a snapshot
- If you experience an error during deployment like a HTTP 401 check your settings for the required server entries as outlined in the Prerequisites
- Be sure that the generated artifacts respect the Apache release rules: NOTICE and LICENSE files should be present in the META-INF directory within the jar. For -sources artifacts, be sure that your POM does not use the maven-source-plugin:2.0.3 which is broken. The recommended version at this time is 2.0.4
- You should verify the deployment under the snapshot repository on Apache
- Prepare the release
- Preparing the release will create the new tag in SVN, automatically checking in on your behalf
- If you get a build failure because of an SVN commit problem (namely The specified baseline is not the latest baseline, so it may not be checked out.), just repeat the mvn release:prepare command until SVN is happy. This is based on a known timing issue when using the European SVN mirror.
- Stage the release for a vote
- The release will automatically be inserted into a temporary staging repository for you, see the Nexus staging documentation for full details
- You can continue to use mvn release:prepare and mvn release:perform on other sub-projects as necessary on the same machine and they will be combined in the same staging repository - this is useful when making a release of multiple Sling modules.
- Close the staging repository
- Login to https://repository.apache.org using your Apache SVN credentials. Click on Staging on the left. Then click on org.apache.sling in the list of repositories. In the panel below you should see an open repository that is linked to your username and IP. Right click on this repository and select Close. This will close the repository from future deployments and make it available for others to view. If you are staging multiple releases together, skip this step until you have staged everything
- Verify the staged artifacts
- If you click on your repository, a tree view will appear below. You can then browse the contents to ensure the artifacts are as you expect them. Pay particular attention to the existence of *.asc (signature) files. If you don't like the content of the repository, right click your repository and choose Drop. You can then rollback your release (see Canceling the Release) and repeat the process
- Note the staging repository URL (especially the number at the end of the URL) you will need this in your vote email
Starting the Vote
Propose a vote on the dev list with the closed issues, the issues left, and the staging repository - for example:
Wait for the Results
From Votes on Package Releases:
Votes on whether a package is ready to be released follow a format similar to majority approval – except that the decision is officially determined solely by whether at least three +1 votes were registered. Releases may not be vetoed. Generally the community will table the vote to release if anyone identifies serious problems, but in most cases the ultimate decision, once three or more positive votes have been garnered, lies with the individual serving as release manager. The specifics of the process may vary from project to project, but the 'minimum of three +1 votes' rule is universal.
The list of binding voters is available on the Project Team page.
If the vote is successful, post the result to the dev list - for example:
Be sure to include all votes in the list and indicate which votes were binding. Consider -1 votes very carefully. While there is technically no veto on release votes, there may be reasons for people to vote -1. So sometimes it may be better to cancel a release when someone, especially a member of the PMC, votes -1.
If the vote is unsuccessful, you need to fix the issues and restart the process - see Canceling the Release.
If the vote is successful, you need to promote and distribute the release - see Promoting the Release.
Canceling the Release
If the vote fails, or you decide to redo the release:
- Remove the release tag from Subversion (svn del ...)
- Login to https://repository.apache.org using your Apache SVN credentials. Click on Staging on the left. Then click on org.apache.sling in the list of repositories. In the panel below you should see a closed repository that is linked to your username and IP (if it's not yet closed you need to right click and select Close). Right click on this repository and select Drop.
- Rollback the version in the pom.xml and commit any fixes you need to make
Promoting the Release
If the vote passes:
- Copy the released artifacts to the Sling dist directory (/x1/www/www.apache.org/dist/sling) on people.apache.org. This folder is replicated to http://www.apache.org/dist/sling/ a few times a day.
- Delete the old release from the Sling dist directory (it's archived)
- Login to https://repository.apache.org with your Apache SVN credentials. Click on Staging. Find your closed staging repository, right click on it and choose Promote. Select the Releases repository from the drop-down list and click Promote.
- Once the release is promoted (there's currently a delay on this, up to 12 hours?) click on Repositories, select the Releases repository and validate that your artifacts are all there.
- If you're releasing bundles, you should also add them to the Sling Release OBR (see Appendix C).
- Update the news section on the website at News.
- Update the download page on the website at Downloads to point to the new release.
For the last two tasks, it's better to give the mirrors some time to distribute the uploaded artifacts (one day should be fine). This ensures that once the website (news and download page) is updated, people can actually download the artifacts.
Update JIRA
Go to Manage Versions section on the SLING JIRA and mark the X.Y.Z version as released setting the release date to the date the vote has been closed.
Also create a new version X.Y.Z+2, if that hasn't already been done.
Create an Announcement
Important: Add the release to the Software section of the next board report below Reports.
Related Links
- http://www.apache.org/dev/release-signing.html
- http://wiki.apache.org/incubator/SigningReleases
Considering that you are using a *nix system with a working OpenSSH, GnuPG, and bash you can create and add your own key with the following command:
- Create a public/private pair key:
When gpg asks for e-mail linked the key you MUST USE the <committer>@apache.org one
When gpg asks for comment linked the key you SHOULD USE "CODE SIGNING KEY"
- Add the key to http://www.apache.org/dist/sling/KEYS: type the following command replacing the word e-mail with your Apache's one (<committer>@apache.org).
- You are DONE, but to see the changes on http://www.apache.org/dist/sling/KEYS you must wait 2 hours
Appendix B: preparing releases on Mac OS X
When running the mvn release:prepare command on Mac OS X, you might see the following error:
[INFO] Executing: svn --non-interactive commit --file /tmp/maven-scm-802409492.commit --targets /tmp/maven-scm-18804-targets
[INFO] Working directory: /homedir/dev/sling/dependencymanager
[INFO] ------------------------------------------------------------------------
[ERROR] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Unable to commit files
Provider message:
The svn command failed.
Command output:
svn: Commit failed (details follow):
svn: MKACTIVITY of '/repos/asf/!svn/act/4f11ad5d-9161-0410-b4dd-cb727141ea8c': authorization failed (https:
This is due to a bug in Subversion on the Mac, as described by Brett Porter in his blog. He proposes putting an "svn" script at the head of your path to fix the issue.
Appendix C: Deploy bundles on the Sling OBR
We are mainting an OSGi Bundle Repository providing all release of the Sling Bundles. This repository is maintained as part of the Apache Sling site and is available at http://sling.apache.org/obr/sling.xml. The source for this page is maintained in the SVN repository below the site, that is at http://svn.apache.org/repos/asf/sling/site/. To update the Sling OBR repository you must be an Apache Sling Committer since this requires SVN write access.
To update the OBR you may use the Apache Felix Maven Bundle Plugin which prepares the bundle descriptor to be added to the OBR file. Follow these steps to update the OBR:
1. Checkout or update the Site Source
Note, that you have to checkout the site using the https URL, otherwise you will not be able to commit the changes later.
2. Deploy the Descriptor
To deploy the project descriptor, checkout the tag of the bundle to deploy and run maven
$ svn checkout http:$ mvn clean install \
org.apache.felix:maven-bundle-plugin:deploy \
-DprefixUrl=http: -DremoteOBR=sling.xml \
-DaltDeploymentRepository=apache.releases::default::file:
This generates the bundle descriptor and adds it to the sling.xml file of your site checkout.
2a. Variant: Refer to Maven Repository
Instead of checking out and building the project locally, you may also use the deploy-file goal of the Maven Bundle Plugin:
$ wget http:$ wget http:$ mvn org.apache.felix:maven-bundle-plugin:deploy-file \
-Dfile=the_module-version.jar -DpomFile=the_module-version.pom \
-DbundleUrl=http: -Durl=file: -DprefixUrl=http: -DremoteOBR=sling.xml
$ rm the_module-version.jar the_module-version.pom
3. Commite the Site Changes
In the Site checkout folder commit the changes to the obr/sling.xml files (you may also review the changes using the svn diff command).
$ svn commit -m"Add Bundle ABC Version X.Y.Z" obr/sling.xml
4. Update the Site on people.apache.org
After committing the changes, you have to update the site source, which is getting mirrored to the web servers on people.apache.org
$ ssh people.apache.org svn update /x1/www/sling.apache.org/obr/sling.xml
After updating the site source it will generally take an hour or two until the changes are visible on the web.