ZeroMQ

Evolution of Public Contracts

By “public contracts,” I mean APIs and protocols. Up until the end of 2011, libzmq’s naturally happy state was marred by broken promises and broken contracts. We stopped making promises (aka “road maps”) for libzmq completely, and our dominant theory of change is now that it emerges carefully and accurately over time. At a 2012 Chicago meetup, Garrett Smith and Chuck Remes called this the “drunken stumble to greatness,” which is how I think of it now.

We stopped breaking public contracts simply by banning the practice. Before then it had been “OK” (as in, we did it and everyone complained bitterly, and we ignored them) to break the API or protocol so long as we changed the major version number. Sounds fine, until you get ØMQ version 2.0, 3.0, and 4.0 all in development at the same time, and not speaking to each other.

All Public Contracts (APIs or protocols) SHOULD be documented.

You’d think this was a given for professional software engineers, but no, it’s not. So, it’s a rule. You want C4 certification for your project, you make sure your public contracts are documented. No “It’s specified in the code” excuses. Code is not a contract. (Yes, I intend at some point to create a C4 certification process to act as a quality indicator for open source projects.)

All Public Contracts SHALL use Semantic Versioning.

This rule is mainly here because people asked for it. I’ve no real love for it, as semantic versioning is what led ...