Numberphilia

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.

Conclusion

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

Trust is maintained.