This document was copied from Apache Joshua's Release Management Procedure. Update as you will.
Introduction
This documents the Apache Joshua release procedure. It is probably good practice to consider this as a dynamic document in the sense that it is up to successive release managers to maintain it ensuring that Maven plugins, etc are kept reasonably up-to-date and that good practice is followed and maintained with regards to the release procedure and resulting release artifacts. If there is something missing, inaccurate or just terribly worded please, please, please update the document for future release managers Good luck.
What you need
Apache Maven
Apache Maven is a software project management and comprehension tool. Based on the concept of a project object model (POM), Maven can manage a project's build, reporting and documentation from a central piece of information. In this context we use it for the entire Joshua release process. If you have been using Joshua source code then you will already have Maven installed. It is always good practice to ensure that you are using the most up-to-date Maven version. The same goes for all Maven plugins defined within Joshua pom.xml. If you see out-of-date plugin versioning, then please update them in a pull request.
Hold on to your hats... Here we go!!!
Before we go any further, there is some good (potentially essential and a huge time saving practice) documentation on this topic. Please see the below links before going any further.
- http://apache.org/dev/#releases
- http://apache.org/dev/release-publishing.html
- http://www.apache.org/dev/publishing-maven-artifacts.html (in particular pay close attention to 'Staging a release')
Preparation
- Create a new release in JIRA. If you do not already have privileges enabling you to do so, ask the Joshua PMC.
- Push off all open issues to the next release; any critical or blocker issues should be resolved on mailing list. Discuss any issues that you are unsure of on the mailing list.
Preparing a release candidate (RC) for community VOTE'ing
As mentioned above, in Joshua we use Maven as a release management tool. We therefore rely predominantly on the maven-release-plugin for the release lifecycle. This includes preparing and RC for a community VOTE.
- Make a clean checkout of Joshua master e.g.
git clone https://git-wip-us.apache.org/repos/asf/incubator-joshua.git
(ensuring that there are no local modifications). - Build the project, running tests e.g.
mvn clean package
- All tests much pass... if they do not then they need to be fixed before further progress can be made.
- Edit CHANGES.md to reflect the current release, this may also be required for other essential files such as NOTICE, README etc. Ensure all of these files are accurate and up-to-date. It is also advised to include the JIRA release report in CHANGES.md, This makes it very easy for people to see the relevant changes for this release bundle.
- If you have never made a Joshua release, you are required to append your gpg key to the Joshua KEYS file, this will then be used to sign all release artifacts. Much more about this can be found herehttp://apache.org/dev/release-signing.html N.B. This is an extremely important part of the release procedure. It is essential to get it right and that all subsequent release managers' KEYS are associated with this file.
- If any changes based on the above have been made, then commit them to master branch. If you do not do this the next stage will not work.
- Run the following e.g.
mvn release:clean release:prepare -DautoVersionSubmodules=true -DdryRun=true
The above makes life very very easy for us and1. cleans out all release-based module directories, and
2. prepares us for a release, making explicit calls to state that we have a multi-module project, and that this is a dry run. Running without the latter can mess up our SCM! Although we've already checked that tests pass, the maven-release plugin wants to do another test run, just to verify that we are not releasing broken code.
- Check all Maven release artifacts produced as output, we wish to iron out any discrepancies at this stage. This includes looking in to the proposed pom.xml files as well as any MANIFEST entires, etc. N.B. This is imperative.
Making the release
If you are happy with the proposed release artifacts then we can now move on to dropping the dryRun profile like so:
mvn release:clean release:prepare -DautoVersionSubmodules=true
This will allow you to view the actual release artifacts.
mvn release:perform
This does the following
- pushes the maven artifacts to an apache staging repository at http://repository.apache.org
- creates a release tag in https://git-wip-us.apache.org/repos/asf?p=incubator-joshua.git;a=tags which you can view.
- finally, it commits the update of all module artifacts within the Joshua pom.xml files and pushes these to Git master branch so we can continue with development e.g. bumps to the next development SNAPSHOT.
Once this has completed,
- navigate to http://repository.apache.org and log in.
- click on Staging Repositories on the left hand side, you should see the Joshua RC staging profile.
- Select the profile and close the staging profile. This makes the artifacts available for people to tests and VOTE upon.
Push the source release artifacts and signatures to dist.apache.org as described below.
Check out Joshua release staging area. The artifacts we push to this area are the ones we make available on official
Apache mirriors. These are therefore the sources artifacts we link to from the Joshua site. e.g.
- In your local copy of Joshua (master), navigate to $JOSHUA/target directory and copy the src.zip and src-tar.gz artifacts along with relevant signatures to the above release staging directory.
- You should aim to include all relevant signatures along with these src artifacts. This would entail
MD5, SHA and ASC signatures for each artifact. More information on this can be found here - http://apache.org/dev/release-signing.html - copy the CHANGES.md to this directory as well
- finally, svn add all of the above artifacts and commit them to the Joshua dev release staging area
Next, progress to the creation of the VOTE thread as below...
Prepare the VOTE thread based on the artifacts
Send something like the following to the user@ and dev@joshua lists
To: "Apache Joshua Developers List" <dev@joshua.incubator.apache.org>, "Apache Joshua User List" <user@joshua.incubator.apache.org> Subject: VOTE Release Apache Joshua (Incubating) X.Y Hi Folks, Please VOTE on the Apache Joshua X.Y Release Candidate #Z. We solved 44 issues: http://url/of/jira/release/report Git source tag (c2d58dd1440b4e2c66c1f40a4b6d4169d79bb6d3): http://s.apache.org/Eyv Staging repo: https://repository.apache.org/content/repositories/orgapachejoshua-1001 Source Release Artifacts: https://dist.apache.org/repos/dist/dev/joshua/X.Y/ PGP release keys (signed using 48BAEBF6): http://joshua.incubator.apache.org/dist/KEYS Vote will be open for 72 hours. Thank you to everyone that is able to VOTE as well as everyone that contributed to Apache Joshua X.Y. [ ] +1, let's get it released!!! [ ] +/-0, fine, but consider to fix few issues before... [ ] -1, nope, because... (and please explain why)
The above email includes the following
- A link to the JIRA Release Report... this is critical for making it explicit what was addressed in this particular
development drive. - The SVN tag created by the mvn release plugin
- A link to the (closed) staging repository on repository.apache.org
- Link to the official release artifacts
- The KEYS file used containing developer signatures. This should be used to check signatures of release artifacts.
Double check the accuracy of this email and ship it to the masses!!!
N.B. DO NOT DELETE YOUR LOCAL COPY OF THE JOSHUA RELEASE YOU"VE JUST PUSHED
IT IS ABSOLUTELY ESSENTIAL THAT YOU KEEP THE LOCAL RELEASE COPY !!!!
Preparing for new development
Send out the RESULT thread
After the 72 hours waiting time, it is down to the release manager to close the VOTE thread. This is usually
done by replying to the VOTE thread but changing the title to the following
Subject: [RELEASE] WAS:VOTE Release Apache Joshua X.Y The RESULT thread should basically tally up the VOTE's something like the following would do nicely Hi Everyone, As the 72 hours period has come and gone I would like to bring this thread to a close. The VOTE's have been counted and RESULT's are as follows [7] +1, let's get it released!!! Tom Dick Harry Lewis John McGibbney * [0] +/-0, fine, but consider to fix few issues before... [0] -1, nope, because... (and please explain why) *Joshua PMC Binding VOTE I'll progress with the remainder of the release procedure.
If the release passes, progress to the next step, if not then head over to dev@joshua and discuss
how to revert the release. Assuming it passes however, progress to the next section.
Close the staging repos
Navigate to https://repository.apache.org and find the (closed) staging repos. Release this repository into
Apache Nexus. This will be pulled into Maven Central and in 12 or do hours the release artifacts should
be available at the following link - http://search.maven.org/#search%7Cga%7C1%7Cjoshua
Release the Source Artifacts
- svn mkdir https://dist.apache.org/repos/dist/release/incubator/joshua/
- svn cp https://dist.apache.org/repos/dist/dev/gora/ to https://dist.apache.org/repos/dist/release/gora/X.Y/
Make sure that the up-to-date KEYS file exists in https://dist.apache.org/repos/dist/release/gora
Once all artifacts and signatures have been copied over, delete the dev area
The release artifacts will be copied over to apache.org/dist in due course and available for public download.
Update the Website to reflect the release
This can be done easily by editing the News feed on the main page as well as the downloads.html page.
It is important that all links on downloads.html are accurate including the signatures links. Also the PGP
key reference to the signed artifacts should be updated to reflect the release managers KEY.
Announce the Release
Hi Folks, The Apache Gora team are pleased to announce the immediate availability of Apache Gora 0.6. The Apache Gora open source framework provides an in-memory data model and persistence for big data. Gora supports persisting to column stores, key value stores, document stores and RDBMSs, and analyzing the data with extensive Apache Hadoop™ MapReduce support. Gora uses the Apache Software License v2.0. Gora is released as both source code, downloads for which can be found at our downloads page [0] as well as Maven artifacts which can be found on Maven central [1]. The DOAP file for Gora can be found here [2] This release addresses a modest XXXXX issues with ... blah blah blah. The full Jira release report can be found here [3]. Suggested Gora database support is as follows Apache Avro 1.7.6 Apache Hadoop 1.2.1 and 2.5.2 Apache HBase 0.98.8-hadoop2 Apache Cassandra 2.0.2 Apache Solr 4.10.3 MongoDB 2.6.X Apache Accumlo 1.5.1 Thank you Lewis (on behalf of Gora PMC) [0] http://gora.apache.org/downloads.html [1] http://search.maven.org/#search|ga|1|g%3A%22org.apache.gora%22 [2] https://svn.apache.org/repos/asf/gora/committers/doap_Gora.rdf [3] URL for Release Report in Jira
- Send an ANNOUNCEMENT to the following lists
- HBase User - user@hbase.apache.org
- Accumulo User - user@accumulo.apache.org
- Cassandra User - user@cassandra.apache.org
- Hector User - https://groups.google.com/forum/#!forum/hector-users
- Avro User - user@avro.apache.org
- Giraph User - user@giraph.apache.org
- DynamoDB Forum - https://forums.aws.amazon.com/forum.jspa?forumID=131
- Solr User - solr-user@lucene.apache.org
- MongoDB User - https://groups.google.com/forum/#!forum/mongodb-user
- Nutch User - user@nutch.apache.org
- Finally the most important internal Apache Announcement list - announce@apache.org
Prepare for Next Development
- In the JIRA Administration Interface, go to
- Versions
- for the release tag you've just released, add a release date and then release it
- Update the DOAP to reflect the release
- File new issues over on JIRA for NUTCH, GIRAPH, CAMEL and CHUKWA. These projects consume Gora and it is through them that we can further improve Gora.
Thats about it folks... start on the next development drive.