Skip to content

7.md

Latest commit

 

History

History
351 lines (249 loc) · 13.9 KB

7.md

File metadata and controls

351 lines (249 loc) · 13.9 KB
Raw

Zen Versioning

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

Motivation

The field of software development has long been littered with overcomplicated versioning specifications that seem to be invented solely to waste the developers' time by inventing made-up requirements that, in truth, nobody has the time to follow. Developers are busy people.

We should consider not only that it takes time to calculate version numbers, but also that it takes mental strain: counting is hard. We do not want to spend time and effort that could be spent developing software on devising versions for our software.

You will never need to ask yourself "do I need to bump minor or major?" You will simply write software.

ZenVer was created to address the poor design choices of prior, unaffiliated specifications by proposing (but not enforcing) a simple, zen, specification that works anywhere, for anyone. It also removes the need to conjure up new, even dumber specifications a total of 7 people will use.

In other words, one spec to rule them all!

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.

Introduction

In the world of software management there exists a dreaded place called "dependency hell." The bigger your system grows and the more packages you integrate into your software, the more likely you are to find yourself, one day, in this pit of despair.

In systems with many dependencies, releasing new package versions can quickly become a nightmare. If the dependency specifications are too tight, you are in danger of version lock (the inability to upgrade a package without having to release new versions of every dependent package). If dependencies are specified too loosely, you will inevitably be bitten by version promiscuity (assuming compatibility with more future versions than is reasonable). Dependency hell is where you are when version lock and/or version promiscuity prevent you from easily and safely moving your project forward.

As a solution to this problem, we propose a simple set of rules and requirements that dictate how version numbers are assigned and incremented. These rules are based on but not necessarily limited to pre-existing widespread common practices in use in both closed and open-source software. For this system to work, you first need to declare a public API. This may consist of documentation or be enforced by the code itself. Regardless, it is important that this API be clear and precise. Once you identify your public API, you communicate changes to it with specific increments to your version number. Consider a version format of X.Y.Z (Major.Minor.Patch). Bug fixes not affecting the API increment the patch version, backward compatible API additions/changes increment the minor version, and backward incompatible API changes increment the major version.

We call this system "Semantic Versioning." Under this scheme, version numbers and the way they change convey meaning about the underlying code and what has been modified from one version to the next.

― From https://semver.org

On paper, this all seems great. Except for one problem: all of that is bullshit2. The clear solution, as most of my peers who have formerly worked on designing a good versioning specification fail to realise3, is to avoid complications while versioning our software, and obviously, to increment VERSION every time you make a change to remain as straightforward as possible. To remain Zen.

API documentation this, minor revision that. BULLSHIT4.

We will see that the underlying problem in existing versioning specifications is that there is no good, consistent specification that is not demanding of the developer. Consistency comes from simplicity, and we cannot achieve neither simplicity nor consistency with those overcomplicated specifications that require more from the developer.

0.40.3? 1.5.0? You hit your head pretty hard, get up we are going back to proper versioning.

To all problems previously (poorly) addressed by SemVer and ZeroVer, ZenVer proposes a simple set of rules that are based on necessarily pre-existing widespread common practices in use in both closed and open-source software5.

For this system to work, you must know how numbers work6. That is about all, you need not to document anything, nor to enforce it by the code itself.

Once you identify your own software (i.e. software that you are working on), which should not be too difficult, you may consider a version format of X (VERSION). Bug fixes increment the VERSION by one, backward compatible API additions/changes increment the VERSION by one, and backward incompatible incompatible API changes increment the VERSION by one. In fact, anything increments the VERSION by one. A butterfly flapping wings on the other side of the earth may increment VERSION by one if you are not careful.

While incrementing by one is the common practice in Zenver, we acknowledge the needs of a developer and propose that if you are, in any given time, feeling a bit down, then you may consider bumping VERSION arbitrarily to feel better.

In former iterations of this specification, some users that major7 changes do not impose the sense of importance that they need to. To that, ZenVer's answer is incrementing: not by one, but by two (or perhaps more) depending on how major the change really is.

Our motivation? Two is larger than one.

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 version7.

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 limitations8.

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. If this has not yet been made obvious to you, then I feel responsible for informing you that this is a joke. I harbor no ill will towards SemVer or any other versioning specification. Though, I prefer ZeroVer over SemVer because it has a more interesting premise. You will find obvious references to the ideas behind both specifications. ↩

  3. Once again, this is a joke. Better men than me have worked on versioning specifications, and this is mostly a joke. Unless? ↩

  4. An obvious Max0r reference because I find his writing darn pretty funny ↩

  5. We should probably learn about versioning from Microsoft. Confused? Take a look at Windows' versioning scheme. At the time of writing, the latest supported revision is 22631.3527. What the hell does that even mean? ↩

  6. If you have having trouble with this, then there is not much I can do for you. May I suggest revising on your elementary school mathematics? ↩

  7. 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. ↩ ↩2

  8. 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. ↩