This page is prepared for Apache Avro committers. You need committer rights to create a new Apache Avro release.
Build environment
I often use Docker to build a clean and consistent build environment:
docker build -t avro-build-ci -f share/docker/Dockerfile . docker build -t avro-build -f share/docker/DockerfileLocal . docker run -v `pwd`:/avro/ -t -i avro-build bash
Branching
Skip this section if this is NOT the first release in a series (i.e. release X.Y.0).
- Update
CHANGES.txt
to include the release version and date (useUnreleased
for the date if it is unknown) and add a new section,Master (unreleased changes)
. Commit these changes to master.
git commit -am "Preparing for release X.Y.Z"
Create a release branch for the release series:
git checkout -b branch-X.Y
Set the version:
mvn versions:set -DnewVersion=X.(Y+1).0 -DgenerateBackupPoms=false
- Commit the update to the release branch.
git commit -am "Preparing for release X.Y.Z"
Return to the master branch.
git checkout master
- Update the default version in
share/VERSION.txt
on master to X.(Y+1).0-SNAPSHOT. Be sure not to leave a trailing newline. Update the version in the Maven POM files to match with
mvn versions:set -DnewVersion=X.(Y+1).0-SNAPSHOT -DgenerateBackupPoms=false
Commit these changes to the branch.
git commit -am "Preparing for X.(Y+1).0 development"
Push the master and branch changes:
git push apache master git push apache branch-X.Y
Updating Release Branch
These operations take place in the release branch.
Check out the branch with:
git checkout branch-X.Y
- Update
CHANGES.txt
to include the release version and date (this change must be committed to master and any intermediate branches between master and the branch being released). - Update the version number in
share/VERSION.txt
to be ''avro-X.Y.Z-SNAPSHOT''. Be sure not to leave a trailing newline. Update the version in the Maven POM files to match with
mvn versions:set -DnewVersion=X.Y.Z -DgenerateBackupPoms=false
Commit these changes.
git commit -am "Preparing for release X.Y.Z"
- Add the fix version X.Y.Z to the Avro JIRA
If not already done, cherry-pick desired patches from master into the branch and commit these changes. You can find the revision numbers using
svn log CHANGES.txt
in the branch and in master.git checkout branch-X.Y git cherry-pick <commit>
- For each patch merged, change the fix version for the JIRA issue to be X.Y.Z
- Go through CHANGES.txt, JIRA, and svn log to be sure that the issues included in the branch match in each location, then update the date in CHANGES.txt to be today.
- Update the version number in
share/VERSION.txt
to be ''X.Y.Z''. Be sure not to leave a trailing newline. Update the version in the Maven POM files to match with
mvn versions:set -DnewVersion=X.Y.Z -DgenerateBackupPoms=false
Update the version number in
lang/c/version.sh
(the variableslibavro_micro_version
,libavro_interface_age
andlibavro_binary_age
) according to the libtool versioning rules as described in that file. Note the libtool version number is completely unrelated to the Avro release version number.Commit these changes.
git commit -am "Preparing to build X.Y.Z"
Tag the release candidate (R is the release candidate number):
git tag -s release-X.Y.Z-rcR -m "Avro X.Y.Z rcR release."
Push the release tag and branch changes:
git push apache release-X.Y.Z-rcR git push apache branch-X.Y
Building
Unless you have set up the required dependencies to build Avro for all languages, the following should be run inside a Docker container (see BUILD.txt for instructions).
Build the release & run unit tests.
./build.sh clean test dist
- Check that release files look ok - e.g. unpack the sources and run tests.
Sign the release (see Step-By-Step Guide to Mirroring Releases for more information).
./build.sh sign
To sign a release, your key must be present in the dist/KEYS file. See the Apache guide to Signing Releases for more details. Also, if you've updated the dist/KEYS file, be sure to update the public Apache KEYS file as well:
svn co --depth=files https://dist.apache.org/repos/dist/release/avro/ archive-avro/ cd archive-avro/ MacBook-Pro-van-Fokko:archive-avro fokkodriesprong$ head -n 14 KEYS This file contains the PGP keys of various developers. Users: pgp < KEYS or gpg --import KEYS Developers: pgp -kxa <your name> and append it to this file. or (pgpk -ll <your name> && pgpk -xa <your name>) >> this file. or (gpg --list-sigs <your name> && gpg --armor --export <your name>) >> this file.
As you can see, the header of the KEYS file has instructions to add your key. Then commit using: svn commit -m "Add key for ..."
Copy release files to the public staging area https://dist.apache.org/repos/dist/dev/avro/
svn co https://dist.apache.org/repos/dist/dev/avro/ avro-dev-dist mkdir avro-dev-dist/avro-X.Y.Z-rcR cp -pr avro/dist/* avro-dev-dist/avro-X.Y.Z-rcR cd avro-dev-dist svn add avro-X.Y.Z-rcR svn commit -m "Artifacts for Avro X.Y.Z RCR"
Stage the default Hadoop 2 version of Java artifacts to the Maven repository:
mvn clean -P dist,sign deploy -DskipTests=true -Davro.version=X.Y.Z
Make sure that you've followed to guide to configure Maven: http://www.apache.org/dev/publishing-maven-artifacts.html
- Find the Staging Repository, and close it.
- Call a release vote on dev at avro.apache.org.
Include the URL of the staging repository.
Publishing
Once three PMC members have voted for a release, it may be published.
Tag the release:
git checkout release-X.Y.Z-rcR git tag -s release-X.Y.Z -m "Avro X.Y.Z release." git push apache release-X.Y.Z
Copy release files to the release repository (PMC permissions required):
svn copy https://dist.apache.org/repos/dist/dev/avro/avro-X.Y.Z-rcR \ https://dist.apache.org/repos/dist/release/avro/avro-X.Y.Z -m "Avro X.Y.Z release."
The release directory usually contains just two releases, the most recent from two branches, with a link named 'stable' to the most recent recommended version (PMC permissions required):
svn co https://dist.apache.org/repos/dist/release/avro/ avro-release-dist cd avro-release-dist svn rm avro-A.B.C; rm stable ln -s avro-X.Y.Z stable svn commit -m "Avro X.Y.Z release."
- Publish Java artifacts to the Maven repository:
Find the Staging Repository and release it. Publish Python artifacts to PyPI. To do this you'll need an account on PyPi, and write access to the Avro package - ask the existing owners for permission if you don't have it.
mkdir -p tmp/py cd tmp/py tar xvfz ../../dist/py/avro-X.Y.X.tar.gz cd avro-X.Y.Z python setup.py sdist upload
Publish Python3 artifacts to PyPI.
mkdir -p tmp/py3 cd tmp/py3 tar xvfz ../../dist/py3/avro-python3-X.Y.Z.tar.gz cd avro-python3-X-Y-Z python3 ./setup.py sdist twine upload dist/*
Publish Ruby artifacts to RubyGems. Again, you'll need an account and you need to be an owner.
gem push dist/ruby/avro-X.Y.Z.gem
Publish JavaScript artifacts to NPM. Again, you'll need an account and you need to be an owner.
npm publish dist/js/avro-js-X.Y.Z.tgz
- Wait 24 hours for release to propagate to mirrors.
Prepare to edit the website.
svn co https://svn.apache.org/repos/asf/avro/site
- Update the documentation links in
author/content/xdocs/site.xml
. - Update the release news in
author/content/xdocs/releases.xml
. Run Apache Forrest using Apache Ant. Example is with forrest installed using homebrew: http://macappstore.org/apache-forrest/
cd site ant -Dforrest.home=/usr/local/Cellar/apache-forrest/0.9/
Copy the new release docs, which are generated at the dist step, to website and update the
docs/current
link:tar xzf dist/avro-doc-X.Y.Z.tar.gz mv avro-doc-X.Y.Z ../site/publish/docs/X.Y.Z cd ../site/publish svn add X.Y.Z rm current ln -s X.Y.Z current svn commit -m "Adding documentation for release X.Y.Z."
- Send announcements to the user and developer lists once the site changes are visible.
- Update the version number in
share/VERSION.txt
to be ''avro-X.Y.N-SNAPSHOT'', where ''N'' is one greater than the release just made. Update the version in the Maven POM files to match with
mvn versions:set -DnewVersion=X.Y.N-SNAPSHOT -DgenerateBackupPoms=false
- In Jira, ensure that only issues in the "Fixed" state have a "Fix Version" set to release X.Y.Z.
- In Jira, "release" the version. Visit the "Administer Project" page, then the "Manage versions" page. You need to have the "Admin" role in Avro's Jira for this step and the next.
- In Jira, close issues resolved in the release. Disable mail notifications for this bulk change.