zeromq

This page captures policies that act as contracts between ØMQ developers and users.

Goals

The goals of these policies are to provide assurances about the nature of changes users can expect. We hope to deliver increasingly stable and reliable versions of a product, while also developing increasingly interesting functionality in parallel.

Versioning

• The product version consists of Major.Minor.Update, e.g. 2.0.7.
• The wire level protocol (ZMTP) has its own version numbers.
• The ABI has its own version numbers.
• You can apply new update to your production environment safely. Updates don't change API, ABI, command lines, wire protocol or semantics. They contain only bugfixes. If a bugfix involves change in API, ABI, command line, wire protocol or semantics, it won't be part of an update.
• New minor version allows for new functionality (i.e. new APIs), slight changes to the semantics etc. The contract for minor version will be made more precise as we go on. In overall, new minor version should at least compile with your old applications. It may even run, however, you should read the NEWS file so you are sure that changes made won't affect your application behaviour in subtle ways.
• New major version means no contract. Anything can change. Major versions are meant for delivering backwards incompatible changes. You will have to tweak your applications to work with new major version.

API Evolution

The question of backwards compatibility often comes up on the list. Here is the process by which we introduce improvements:

• New features are introduced in unstable code, and gradually make their way to stable code, being refined along the way.
• New features MUST NOT break old features, but MUST always be backwards compatible extensions.
• This means, in practice, using new names for new features.
• Old features replaced by new ones are deprecated in a systematic fashion:
  • Until the new features are stable, the new ones are marked "experimental" in the API docs.
  • When the new features are stable, the old ones are marked "deprecated" in the API docs.
  • When sufficient time has passed (usually a year), the old features are marked "legacy" in the API docs.
  • When further sufficient time has passed, the old features MAY be removed, or may be left as legacy features.
• Old names MUST NOT be reused by new features, ever.
• Implementations of old names that are removed MUST assert when the old name is used.

Current Releases

We maintain four branches of ZeroMQ at present:

• 2.0.x is the deprecated 2.x release, which receives user-contributed bug fixes only.
• 2.1.x is the stable 2.x release, which receives downstreamed bug fixes only.
• 2.2.x is the 2.x ongoing release, which receives downstreamed bug fixes, new functionality, and additional layers, e.g. czmq. This is mainly a placeholder for continuing 2.x maintenance after 2.1 is frozen. One goal with 2.2.x is to expand the ZeroMQ distribution package to include essential core language bindings.
• 3.1.0 is the new 3.x unstable release.

2.x and 3.1 implements the same wire level protocol, ZMTP/1.0. 3.0 (deprecated) uses an incompatible version of ZMTP.