Skip to content

8.md

Latest commit

 

History

History
250 lines (170 loc) · 8.67 KB

8.md

File metadata and controls

250 lines (170 loc) · 8.67 KB
Raw

Zen Versioning

an elegant, post-modern versioning specification for the adventurous that does not suck1.

Synopsis

ZenVer is a simple, and straightforward versioning specification that demands nothing from the developer, and less than nothing from the end-user. The specification can be broken down as follows:

Given a version number VERSION, increment the:

  1. VERSION version when you make incompatible API changes
  2. VERSION version when you add functionality in a backward compatible manner
  3. VERSION version when you make backward compatible bug fixes
  4. VERSION version when you change practically anything

No additional labels, titles or subtitles for pre-release and build metadata shall be appended to the VERSION format. Those can be used outside the version string e.g., in release pages, however it should be avoided in package meta information.

Zen Versioning Specification (ZenVer)

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as you choose to interpret them as.

Remember that this specification is a suggestion, and your feelings are more important than a silly document that tells you what to do.

  1. Zen versioned software MUST always use positive integers.

  2. Software using Zen Versioning MAY declare a public API. This public API MAY be declared in the code itself, or exist strictly in documentation. If it is done, it MAY be precise and comprehensive. This is RECOMMENDED, but not enforced.

  3. A normal version number SHOULD take the form X where X is a non-negative integer, and MAY consider zeroes. X is the version. This element MAY increase numerically. For instance: 1 -> 2 -> 3. Alternatively: 1 -> 4 -> 5

  4. Once a versioned package has been released, the contents of that version SHOULD NOT be modified, however, it MAY be modified. Any modifications SHALL be released as a new version, however, that is not enforced.

  5. All versions are for development. Everything MUST change. The public API MAY be considered stable.

  6. Version 1 defines absolutely nothing at all. They are numbers, you MUST NOT assign arbitrary meaning to numbers on your screen.

  7. When displaying a version, a one letter prefix (z) MAY be prepended to the version. It is NOT required.

  8. In order to differentiate from other versioning schemes, the one letter prefix (v) MUST NOT be used.

Why Use Zen Versioning?

This is, unlike Semantic Versioning, a new and a revolutionary idea. In fact, you probably never did something remotely close to this before. The (biggest) problem here is that you are unimaginative, and formal specifications are boring.

Zen Versioning establishes a simple and straightforward specification that communicates your intentions to the users of your software. Those intentions are, and always have been clear: number go up, software go new.

As a responsible developer you will, of course, want to make sure that any package upgrade makes sense from the get go.

Number go up = upgrade.

The real world is a messy place, and the world of software development is worse. What you can do to remedy the unfortunate status quo is to follow a sane versioning specification while releasing and upgrading packages.

Larger is greater, greater is larger. Larger number means better software.

FAQ

How should I deal with revisions in the X for initial development phase?

Start with 1. Increment by one every time you change something. Increment by one whenever you feel like. Your software will never be final, and the version should always reflect that.

How do I know when to release 1?

If your software exists, then it's good to go. Release it, what are you waiting for?

Doesn't this discourage rapid development and fast iteration?

No. Are you illiterate?

If even the tiniest backward incompatible changes to the public API require version bump, won't I end up at version 42 very rapidly?

You will, and that is a good thing. Larger number means better software, and you will almost certainly never run out of numbers to assign to your software.

Documenting the entire public API is too much work!

Then don't, nobody cares.

What do I do if I accidentally release a backward incompatible change?

Release a new version.

What should I do if I update my own dependencies without changing the public API?

Increment version by one. Two if you feel brave that day, or alternatively bump the same number as the dependencies you have updated.

How should I handle deprecating functionality?

If a given version of a release is below latest available version, then that version is deprecated.

No takesies backsies.

Here is a useful illustration for the less mathematically inclined:

Latest version: 15
Your version: 13

This means your version is deprecated. That is because, believe it or not, 15 is larger than 13.

How should I communicate breaking changes?

You shouldn't. The entire specification of ZenVer seeks to be self-explanatory. Larger number means newer software. Users are to expect breakage in each version2.

Let the users do the heavy lifting for you!

Does ZenVer have a size limit on the version string?

Nope. You can have an 12 billion character version for all I care. If you find yourself running out of numbers, then consider that your software may be too good.

Is v1 a valid zen version?

No, because in ZenVer it is required to prefix versions with a z instead of v; however, using only a number is still allowed. In an identical case, z1 and 1 would both conform to ZenVer spec.

Is there a suggested regular expression (RegEx) to check a ZenVer string?

Yeah just check if it's a number, optionally prefixed with z.

My cat rolling on my keyboard has conjured the following expression:

^(z)?\d+$

How is this any different compared to to SemVer?

Zen Versioning ("ZenVer") is SemVer, if it had only the MAJOR patch version and if everything else was omitted.

A ZenVer release from 3 -> is just a SemVer release from 3.0.0 to 4.0.0.

Examples

  • Case one: your software, currently versioned 3, has received a complete refactor.
Version: 3 -> 4
  • Case two: an example software, currently at version z45 has breaking API changes.
Version: z45 -> z46

About

The Zen version has been conjured in roughly 3 minutes as a joke, however, it made too much sense to discard. This has lead to the release of specification v1. ZenVer draws inspiration from SemVer and ZeroVer, but addresses their limitations3.

If you'd like to leave feedback, please open an issue on GitHub.

License

Creative Commons ― CC BY 3.0 license.

Footnotes

  1. This is software. Strictly speaking, it does not have the ability to suck. ↩

  2. You might have seen the recent changes to keepassxc in Debian Sid repositories where users were blamed for not reading arbitrary NEWS files of their distribution. We think users are to be blamed even more, so we doubled down on this approach. ↩

  3. You should ask yourself: how major is my major change? If it's more major than major, then increase the number in accordance. If it's less major than major, then repeat above instructions. I think I'm repeating myself here. ↩