This documents the Apache Gora release procedure. It is a dynamic document and it is
up to successive release managers to maintain it. If there is something missing, inaccurate
or just terribly worded please update the change Good luck.
What you need
- 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 Gora release process.
- Gradle is a software build system similar to Apache Maven. It follows same Convention-over-Configuration principle and same project layout. In Apache Gora, we provides a Gradle plugin which simplify processing of Avro schema files. This plugin will scan for *.avsc files and generate corresponding Java persistent objects. We will use Gradle to build Gora Gradle plugin as part of release process. NB: For now, plugin release process is separate from main release process.
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://www.apache.org/dev/publishing-maven-artifacts.html (in particular pay close
attention to 'Staging a release')
- Create a new release in JIRA. If you do not already have these privileges
ask your PMC Chair.
- 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 Gora 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 Gora trunk e.g.
git clone https://git-wip-us.apache.org/repos/asf/gora.git
(ensuring that there are no local modifications).
- Build the project, running tests e.g.
mvn clean package
- At this stage it might be best to run the example from the main Gora tutorial.
- Edit CHANGES.md to reflect the current release (please include release report from JIRA as well as a link to the JIRA release report), this may also be required for other essential files such as NOTICE.md, README.md 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.
- If you have never made a Gora release, you are required to append your gpg key to the Gora KEYS file, this will then be used to sign all release artifacts. Much more about this can be found here http://apache.org/dev/release-signing.html N.B. This is extremely important.
- For Gora Gradle plugin edit the "version" attribute in gora-gradle-plugin/gradle.properties
- Commit these changes. 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 and
- cleans out all release-based module directories, and,
- 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 to tag area which increases the workload.
- Check all Maven release artifacts produced as output, we wish to iron out any discrepancies at this stage. This includes looking in to the propose pom.xml files as well as any MANIFEST entries, 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.
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=gora.git;a=tags which you can view.
- finally, it commits the update of all module artifacts within the Gora pom.xml files and commits these to trunk 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 gora 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
Check out Gora 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 Gora site. e.g.
- In your local copy of Gora master, navigate to $GORA_HOME/target directory and copy the src.tar.gz and src.zip 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 gora 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@gora lists
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 GORA 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
If the release passes, progress to the next step, if not then head over to dev@gora and discuss
how to revert the release. Assuming it passes however, progress to the next section.
Release 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%7Cgora
Release the Source Artifacts
- svn mkdir https://dist.apache.org/repos/dist/release/gora/X.Y/
- svn cp https://dist.apache.org/repos/dist/dev/gora/ https://dist.apache.org/repos/dist/release/gora/
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.
Release the Gradle Plugin
For the Gradle plugin, run the following
cd gora-gradle-plugin; ./gradlew clean assemble
This command will
- Download Gradle Wrapper
- Launch compile and assemble Gradle tasks
- Artifacts will be stored in build/libs
Then run the following :
./gradlew clean publishPlugins
This does the following
- Relaunch compile / assemble tasks
- Upload those artifacts to Gradle Plugins Portal (web interface : https://plugins.gradle.org/plugin/org.apache.gora)
Announce the Release
- Send an ANNOUNCEMENT to the following lists
- HBase User - email@example.com
- Accumulo User - firstname.lastname@example.org
- Cassandra User - email@example.com
- Hector User -
- Avro User - firstname.lastname@example.org
- Giraph User - email@example.com
- DynamoDB Forum -
- Solr User - firstname.lastname@example.org
- MongoDB User -
- Nutch User - email@example.com
- Finally the most important internal Apache Announcement list - firstname.lastname@example.org
Prepare for Next Development
- In the JIRA Administration Interface, go to
- 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.