[zeromq-dev] Process for evolving the API

[Pieter Hintjens]

Hi folks,

This question has come up and I've answered it a few times but it
needs to be documented.

Here is the proposed safe process for evolving the API (and other
formal contracts) without the pain of major version breaks.

It is at http://www.zeromq.org/docs:policies#toc2.

Comments as usual, welcome.

-Pieter


++ 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 fully, or may be left as legacy features.
* Old names MUST NOT be reused by new features, ever.