Differences between revisions 33 and 34
Revision 33 as of 2014-03-16 00:29:03
Size: 13837
Editor: AaronMcCurry
Revision 34 as of 2015-07-02 21:02:16
Size: 13691
Editor: AaronMcCurry
Deletions are marked like this. Additions are marked like this.
Line 72: Line 72:
= Run Tests =

Run all the unit tests with the following:

mvn clean test -Dhadoop1

= Generate the Release Notes =
= Generate the HTML Release Notes =
Line 103: Line 95:
This will take some time to complete.
Line 104: Line 98:
mvn install -Dhadoop1
mvn site -Ddependency.locations.enabled=false -Dhadoop1
mvn site:stage -Dhadoop1
mvn package -DskipTests -Dhadoop1

release_scripts/build_release.sh <output directory>
Line 121: Line 113:
cd distribution/target cd <output directory>

This page describes how to make a release of Blur.

See also [Blur: To Contribute] for more background on building Blur.

First time as a release manager.

If you are not already a member of the Web Of Trust (WOT) it would be a good idea to do so. (ask on dev@). You can read more about key signing here.

You need to be a member of the "incubator" unix group on people.apache.org. Ask for help on the incubator general@ list. Here's an example http://bit.ly/9Wkdzg

Ensure that you have setup your ssh keys on people.apache.org, otherwise you'll have to enter your login password a number of times (best use ssh-agent for this as well). A good overview of this process can be found here (ssh-copy-id and ssh-agent in particular)

Create a Release Series Branch

If the release is 0.X.0 release then you will need to create a branch. However if the release is a 0.X.Y (or minor release) there should already be a branch for the release series. For example to release 0.2.0 a branch of apache-blur-0.2 will need to be created, however if the release was for 0.2.1 then you will reuse the existing branch and just tag the new release (this is later in the instructions).

For the first release of a release series:

  • Update CHANGES.txt in trunk for the new release.
    • Grab the text-based release notes for this release from JIRA

    • Prepend CHANGES.txt with those release notes, adding the title: Release X.Y.0 - YYYY-MM-DD.
    • Commit:

git add CHANGES.txt
git commit -m "Preparing for release X.Y.0-incubating" 
git push origin master
  • Create a branch for the release series:

git checkout -b apache-blur-X.Y
git push origin apache-blur-X.Y

For any release following in the same series:

  • Update CHANGES.txt.
    • Grab the text-based release notes for this release from JIRA

    • Prepend CHANGES.txt with those release notes, adding the title: Release X.Y.Z - YYYY-MM-DD.
    • Commit:

git checkout apache-blur-X.Y
git add CHANGES.txt
git commit -m "Preparing for release X.Y.Z-incubating" 
git push origin apache-blur-X.Y

NOTE: After the release has been voted on and is successful then bump of the version of master. (See instruction below)

Update the Release Branch

The version number in the release branch ends in -SNAPSHOT, but we need to remove this for the release. For example, 0.1.0-incubating-SNAPSHOT needs to be changed to 0.1.0-incubating

for file in $(find . -name pom.xml); do 
sed -i "" -e "s/0.1.0-incubating-SNAPSHOT/0.1.0-incubating/" $file; 

You will also need to verify/update the version in these files:

  • Update the version in docs/cluster-setup.html
  • Update the version in docs/data-model.html
  • Update the version in docs/getting-started.html
  • Commit these changes to the branch.

Generate the HTML Release Notes

JIRA has the ability to generate release notes automatically (this is why it is so important to keep the fix version number accurate).


Manually check this list for accuracy! I've repeatedly seen closed bugs that were not fixed (i.e., duplicate) marked with a fix version, so that they incorrectly show up in this list. Find those, edit them to remove the fix release (only actually fixed bugs should have a fix release) and re-run the report.

Select the correct version, in HTML format.

Update the release notes file:

  • Remove docs/release-notes.html

  • Copy docs/release-notes.template.html to docs/release-notes.html

  • Edit docs/release-notes.html replace "PUT HTML RELEASE NOTES HERE" with the contains of the html release notes

Add to release:

git add docs/release-notes.html
git commit -m "Adding release notes for release."

Build and Deploy Artifacts

This will take some time to complete.

Build the artifacts:

release_scripts/build_release.sh <output directory>

Copy Release Artifacts

We are using these instructions after the artifacts are created:


To create the artifacts:

VERSION=X.Y.Z # For example 0.2.0-incubating
cd <output directory>
md5 apache-blur-$VERSION-bin.tar.gz > apache-blur-$VERSION-bin.tar.gz.md5
md5 apache-blur-$VERSION-src.tar.gz > apache-blur-$VERSION-src.tar.gz.md5
shasum apache-blur-$VERSION-bin.tar.gz > apache-blur-$VERSION-bin.tar.gz.sha1
shasum apache-blur-$VERSION-src.tar.gz > apache-blur-$VERSION-src.tar.gz.sha1
gpg --armor --output apache-blur-$VERSION-bin.tar.gz.asc --detach-sig apache-blur-$VERSION-bin.tar.gz
gpg --armor --output apache-blur-$VERSION-src.tar.gz.asc --detach-sig apache-blur-$VERSION-src.tar.gz

To upload the artifacts:

svn co https://dist.apache.org/repos/dist/dev/incubator/blur/
cd blur
mkdir X.Y.Z-incubating

Snapshot the KEYS file by pulling http://people.apache.org/keys/group/blur.asc and saving as KEYS.

copy [KEYS file + *.tar.gz + *.md5 + *.sha1 + *.asc] X.Y.Z-incubating/
svn add X.Y.Z-incubating
svn ci -m "Adding artifacts for Blur release X.Y.Z-incubating"

Sanity Check

Download the artifacts and try out some of these things:

  • Blur Getting Started Getting Started

  • Check the MD5 checksums
  • Licensing check: (download RAT and run java -jar apache-rat-*.jar on the Blur tarballs.

Known violations in the source artifact include:

Basic text files


  • CHANGES.txt




  • **/README.textile

  • **/.classpath

  • **/.project

  • **/.settings/**

Contains a list of english words that are used for load testing, adding a header would make the simple parsers more complex.

  • **/src/main/resources/org/apache/blur/thrift/util/words.txt

For some reason the BSD License for d3 is not picked up in RAT, but they are accounted for in the LICENSE file.

  • **/src/main/webapp/js/d3.v2.js

  • **/src/main/webapp/js/d3.v2.min.js

License and Notice files for Blur.

  • **/src/main/resources/license-notes.txt

  • **/src/main/resources/NOTICE-src.txt

  • **/src/main/resources/NOTICE-bin.txt

Default configuration files used by Binary Blur artifact.

  • **/src/main/scripts/conf/controllers

  • **/src/main/scripts/conf/default_zoo.cfg

  • **/src/main/scripts/conf/shards

  • **/src/main/scripts/conf/zookeepers

Generated Thrift files.

  • **/src/main/scripts/interface/gen-html/Blur.html

  • **/src/main/scripts/interface/gen-html/index.html

Used to create empty directories in git.

  • **/.empty

Blur Console Exclusions

Blur Admin is a Ruby on Rails application in the blur contributions (contrib/blur-console) and it has many embedded javascript and css libraries.

These javascript libs are accounted for in the LICENSE-src file in distribution/src/main/resources.

  • contrib/blur-console/blur-admin/vendor/assets/javascripts/d3/**

  • contrib/blur-console/blur-admin/vendor/assets/javascripts/backbone/**

  • contrib/blur-console/blur-admin/vendor/assets/javascripts/flot/**

  • contrib/blur-console/blur-admin/vendor/assets/javascripts/jquery.*.js

  • contrib/blur-console/blur-admin/vendor/assets/javascripts/modernizr.js

  • contrib/blur-console/blur-admin/vendor/assets/javascripts/sorttable.js

  • contrib/blur-console/blur-admin/vendor/assets/javascripts/underscore.js

  • contrib/blur-console/blur-admin/vendor/assets/javascripts/datatables.fnReloadAjax.js

These css libs are accounted for in the LICENSE-src file in distribution/src/main/resources.

  • contrib/blur-console/blur-admin/vendor/assets/stylesheets/jquery*.css

  • contrib/blur-console/blur-admin/vendor/assets/stylesheets/ui.dynatree.css

Ruby gems.

  • contrib/blur-console/blur-admin/vendor/gems/cancan/**

Generated during the rails build process in the blur-admin project.

  • contrib/blur-console/blur-admin/Gemfile.lock

Known violations in the binary (additional to the site) artifact include:

The maven site that is generated

  • docs/site/**

Commit and Tag

Commit any changes in the branch and create a release tag:

git commit -am "Preparing for release X.Y.Z-incubating" 
git push origin apache-blur-X.Y
git tag -a release-X.Y.Z-incubating -m "Blur X.Y.Z-incubating release" 
git push origin release-X.Y.Z-incubating

Run the Vote

Run the vote on the dev@blur.

Here is an example email:

To: "Blur Developers List" <blur-dev@incubator.apache.org>
Subject: [VOTE] Release Blur version X.Y.Z-incubating 

This is the first release candidate for Apache Blur, version X.Y.Z-incubating. 

It fixes the following issues: 

*** Please download, test and vote by [3 working days after sending]. 

Note that we are voting upon the source (tag), binaries are provided for convenience. 

Source and binary files: 

The tag to be voted upon: 

Blur's KEYS file containing PGP keys we use to sign the release: 

The release needs 3 +1 votes from the PMC.

Bump Version in master

NOTE: Master branch in Blur is strange state, skip this section for now.

  • Bump the version number in trunk (the update-versions script mangles the whitespace in the root XML element):

git checkout master
for file in $(find . -name pom.xml); do 
sed -i "" -e "s/0.1.0-SNAPSHOT/0.2.0-SNAPSHOT/" $file; 
git add {all pom.xml files}
  • Bump the version in docs/cluster-setup.html
  • Bump the version in docs/data-model.html
  • Bump the version in docs/getting-started.html
  • Commit these changes to trunk.

git add {html files above}
git commit -m "In prep for release, moving master to new version."
git push origin master

Roll Out

Assuming the vote passes, the release can be rolled out as follows:

Move Artifacts into Place

This step makes the artifacts available on the mirrors. For reference:


svn move https://dist.apache.org/repos/dist/dev/incubator/blur/X.Y.Z-incubating https://dist.apache.org/repos/dist/release/incubator/blur/X.Y.Z-incubating

Build and deploy documentation

  • To be written.

Wait 24 Hours

It takes up to 24 hours for all the mirrors to sync, so don't announce the new release just yet.

Build and Deploy Site

  • To be written.

Announce the Release

TODO: Add a news section to the website.

Send an email to announce@apache.org (the from: address must be @apache.org). E.g.

To: announce@apache.org, blur-user@incubator.apache.org, blur-dev@incubator.apache.org, general@incubator.apache.org
Subject: [ANNOUNCE] Apache Blur 0.2.0-incubating released 

The Apache Blur team is pleased to announce the release of Blur 0.2.0-incubating. 

This is the first release of Apache Blur, an open source search platform 
capable of querying massive amounts of data at incredible speeds. Apache Blur
is built on top of Apache Lucene, Apache Hadoop, Apache Thrift, and Apache ZooKeeper.

The release is available here: 

The full change log is available here: 

We welcome your help and feedback. For more information on how to 
report problems, and to get involved, visit the project website at 

The Apache Blur Team 

Apache Blur is an effort undergoing incubation at the Apache Software
Foundation (ASF), sponsored by the Incubator PMC.

Incubation is required of all newly accepted projects until a further review
indicates that the infrastructure, communications, and decision making process
have stabilized in a manner consistent with other successful ASF projects.

While incubation status is not necessarily a reflection of the completeness
or stability of the code, it does indicate that the project has yet to be
fully endorsed by the ASF.

HowToRelease (last edited 2015-07-02 21:02:16 by AaronMcCurry)