ØMQ Distributions

Stable release patch policy

To lower the risk of insufficiently tested code breaking ØMQ stable releases (which has happened a couple of times recently), we recommend (and use ourselves) this policy for moving patches into a stable release:

  • Every patch MUST be identified by a clean issue (i.e. one that covers precisely that problem).
  • The patch MUST be have a clear test case that reproduces the problem.
  • This test case MUST be written in C and be stored in the issues repository.
  • The issue SHOULD have an external reporter, i.e. a ØMQ user who can confirm an eventual fix.

Pulling patches from libzmq

When the libzmq repository is defined as a remote, you can pull specific commits from it:

git fetch --no-tags libzmq
git cherry-pick -n 43e885
(review changes)
git commit -c 43e885

On official distributions we use the issue tracker to log libzmq commits that we wish to apply to the distribution. This means we can review, discuss, and track these changes.

Making a Distribution Release

By "release" we mean a set of downloadable packages. If there were any changes to the ØMQ ABI (as defined by http://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html) then the ABI version must be updated as the last thing before a public release. The ABI version is set in configure.in (search for LTVER).

To make a new distribution release:

  1. Run the selftests: 'make check'.
  2. Update NEWS based on the git log, and commit that.
  3. Create a tag with the appropriate version number: git tag v3.1.9 -m "This is release 3.1.9"
  4. Push the tag to github: git push —tags origin
  5. Run ./autogen.sh and ./configure, and make dist to get .zip and .tar.gz packages.
  6. If the release is not considered mature enough for production use (i.e. stable), add -alpha, -beta, or -rc before the file extension.

If you are making an official release, then also:

  1. Upload the .tar.gz and .zip files to the downloads.zeromq.org site (you need access for this).
  2. Recreate the SHA1 and MD5 hashes for these new files.
  3. Add the new version to the reference manual at http://api.zeromq.org, and rebuild that site.
  4. Update the download page at http://www.zeromq.org/intro:get-the-software
  5. Email the release announcement to zeromq-dev and (separately) to zeromq-announce, so that Reply-To works properly.
  6. Announce the release on Freshmeat, Twitter, and the #zeromq IRC channel.

Precautions: don't make an official release immediately after applying changes. Allow at least one day for the automated builds to test on all platforms. If the changes are not 100% safe, ask for review of the repository master on email or IRC.

Setting a new version number

Set the new version number immediately after a release, so that the release repository always holds the next in progress version. The version number is located in {{include/zmq.h}:

#define ZMQ_VERSION_MAJOR 2
#define ZMQ_VERSION_MINOR 1
#define ZMQ_VERSION_PATCH 2