We roughly follow the Apache release process when performing a release for the OpenSocial Explorer. There are a few prerequisites before being able to perform a release:
Requirement number one is obvious however requirement number two may seem a bit odd if your are not experiences with open source projects. At a very high level we want to sign all release artifacts so that consumers can be somewhat confident that the artifacts are coming from a reliable source. Apache has a very good overview of the how and why of doing this. If you want to perform releases please read and follow their document first.
The OpenSocial Explorer should be consumable by other applications so we also publish our artifacts to the Central Maven Repository for other Maven projects to easily consume. Sonyatype has an open source Maven repository which syncs with the Central Maven Repository that we use for hosting the OpenSocial Explorers artifacts. The process for deploying artifacts to their repository is documented in their user guide.
The steps below specify how to perform a release.
The Sonatype OSS release process assumes you have some servers defined in your Maven settings in order to upload release artifacts. Open your Maven settings.xml file in ~/.m2 and add the following servers.
<settings>
...
<servers>
<server>
<id>sonatype-nexus-snapshots</id>
<username>your-jira-id</username>
<password>your-jira-pwd</password>
</server>
<server>
<id>sonatype-nexus-staging</id>
<username>your-jira-id</username>
<password>your-jira-pwd</password>
</server>
</servers>
...
</settings>
The jira-id and jira-pwd are your JIRA user name and password you signed up with in step 3 of the prequisites above.
Open an issue used to track the release.
Create a clone of the repository to do your release work. You may also use an existing clone of the repo if you have one.
$ git clone git@github.com:OpenSocial/explorer.git $ cd explorer
You want to do a dry run of the release first. This will perform a release without checking in any code or creating a tag.
$ mvn release:prepare -DdryRun=true -Prelease
Running the release profile (-Prelease) is key in that it will also build the opensocial-explorer-assembly module and produce source and javadoc jar files. This is kept out of the normal build to reduce the overhead when doing development. The release:prepare goal will create modified POM files for all the modules. You will see multiple versions for each.
It is good practice to review the changes made to the different POM files to make sure everything appears correct. You can easily do this with any diff tool. The main things to look for is that the versions and SCM elements are modified correctly. If you find something that is wrong you can clean the release by running
$ mvn release:clean
This will clean up all the POM files. You can then go ahead and fix whatever is wrong and rerun the dry run.
Once you are satisfied with the dry run you can prepare the release.
$ mvn release:clean $ mvn release:prepare -Prelease
The release:prepare goal will actually check in the new POM files and tag the release in the GitHub repo.
You should now deploy the releases to the staging repository.
$ mvn release:perform -Dgoals=deploy -Prelease
Note we only execute the deploy goal because we do not want to deploy the site as well. Our project uses a different method of deploying the project site.
You should now be able to log into Sonatype Nexus App and click Staging Repositories in the navigator on the left and find the release you just staged. The artifacts in this staging repository will be the ones you and the rest of the community test with before promoting the release. It is easier to download the artifacts here than from the Nexus app.
Modify the issue you created in step 1 with a link to the staging artifacts and let the community know that there is a new release candidate. As long as no one finds any issues within 72 hours of staging the release you may promote the release.
Follow step 8a in the Sonatype OSS User Guide to release the staged artifacts. Once a staged release has been closed they will appear here. Note that the Sonatype repository syncs with the Central Maven Repository every 2 hours so it may take up to 2 hours for the release to appear in the Central Maven Repository.
It is not uncommon to find a problem with a staged release. When you do you will need to drop the release, fix the problem, and stage it again. In step 8a of the Sonatype OSS User Guide there is a description of how to drop a release as well. This will remove all the staged artifacts from the repository.
This is not the only thing you need to do though, remember Maven also created a tag for the release and checked in changes to the POM files, we also need to undo those as well. Luckily as long as you have not run a release clean operation since performing the release, Maven can take case of undoing some of this for you by using the release rollback goal. You just have to run
$ mvn release:rollback -Dtag=tag-name -Prelease
Currently this will not undo the tag Maven created in GitHub, that you will have to do yourself.
After a new release you need to update the Downloads page with a links to the latest release artifacts and source code. To publish the site see the site documentation.
Close the issue you opened for the release and also close the milestone for the release. Make sure you create a milestone for the next release.
We need to get the word out about the new release, here are some channels we can use to do that.