Space Cat, Prince Among Thieves


There's been a fair deal of hubbub in the community about version numbers, including what is and isn't Semantic Versioning, what qualifies as a breaking change and how to use version numbers.

Underscore.js released a second digit "minor update" that was actually a breaking update for some people. They argue it was minor because not very many people would be affected. The community however was angry.

On the opposite side of things, PHP Internals announced they will be skipping version 6 and numbering the next version of PHP 7 to avoid confusion with the never released UTF-16 native version. Again the community was angry.

Using Version Numbers Well

If you are semantically versioning your library, the version represents a contract of trust between you and your developers regarding the public API. The contract declares that nothing you change in a 'less than major' release should break their code. Ever.

Break the contract, you can end up breaking their trust. Break their trust and they'll look elsewhere.

Version Numbers SHOULD NEVER Be Branding

If you're using your version numbers as branding, you are doing it wrong. Version numbers should show a clear history of the public facing interface, not what you sell or advertise it as.

Microsoft of all people understands this. While their version numbers aren't truly semantic, they are aimed at developers - and highly out of sync with the marketing designation because the version numbers denote a true relationship.

You can have both a release number and a sales version. This is the way to go if sales demands control of the version number, such as where I work.

Increment Early, Increment Often

Breaking changes always need to be a first digit release. Always. It doesn't matter if it's not a common use case. It shouldn't matter if you're saving the number for a "woo big new release" version. A breaking change in a minor release violates trust and brings the quality of your software into question.

WHENEVER a behavior or signature of ANY explicitly public member of your API has changed whereas the previous behavior was anything other than bold face wrong it is a first digit release.

Numbers are Cheap

Numbers are cheap. Numbers are infinite. Never reuse numbers, ever. There is no reason.

PHP in my strong opinion did the right thing by skipping 6. They sidestepped ANY potential confusion, minor as it may have been. The argument that they caused confusion about "Where did 6 go" is childish. People will be investing time in the largest digit release, regardless of gaps. No one (save some overly cautious IT people) is going to be using PHP 5.6 and on seeing 7 released think "I'll upgrade to 6".

Trying to not have gaps in your version numbers makes as much sense as if Git were to use ordered numbers instead of hashes.

Version numbers should be a universally unique identifier for a specific set of code. If there is ever any form of contention over what a version number represents, increment. Don't think about it - just do it.


Always avoid confusion; don't ever be afraid to increment your major release number. Only good things can come from it.

Trust is maintained.

Read More / Comment »

Require a Remote Zip File with Composer

I previously showed you how to Load a Github Gist with Composer, but sometimes you need to install code that isn't isn't even in a public facing VCS. I for instance wanted to use a library only distributed by Zip. It's actually fairly easy! In your composer.json file, you simply add a repositories s…

Read More / Comment »

All Glory to __invoke

Lost in the shiny new features (see: namespaces and closures) PHP 5.3 also added the __invoke method. While not plainly apparent, it is secretly an amazingly useful 'magic method' . If you're not taking advantage of __invoke, you should be. Why? It provides a uniform execution points for objects th…

Read More / Comment » donatJ

Fleet Foxes - Fleet Foxes
Gorillaz - Plastic Beach
Fleet Foxes - Helplessness Blues
The Wallflowers - Bringing Down The Horse
Fleet Foxes - Sun Giant [EP]
Arca - Xen
The Weepies - Sirens
Fischerspooner - #1
The Velvet Underground - The Velvet Underground & Nico

Flickr donatJ


Recent Comments

Thanks man! You saved me a lot of work!

Thanks This command helped pecl install memcache

How to install it for PHP CLI? Please help

This is a good program for building on terraria. You. Might add that into your description. This help me build biospheres.thanks!

Thanks you! Nice post

Tag Cloud