Skip to content

1.md

Latest commit

 

History

History
219 lines (156 loc) · 9.38 KB

1.md

File metadata and controls

219 lines (156 loc) · 9.38 KB
Raw

Zen Versioning

A post-modern versioning scheme for the adventurous.

Summary

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

Additional labels for pre-release and build metadata are available as extensions to the VERSION format.

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

Yeah well you see, all of that is bullshit. The clear solution to avoid complications while versioning our software, obviously, is to increment VERSION every time you make a change.

To all problems previously addressed by Semver, I propose a simple set of rules that are based on necessarily limited to pre-existing widespread common practices in use in both closed and open-source software1. For this system to work, you must know how numbers work. You need not to document anything, or enforce it by the code itself. Once you identify your own software, which is not too difficult, then you may consider a version format of X (VERSION). Bug fixes increment the VERSION by one, backward compatible API additions/changes increment the VERSION and backward incompatible incompatible API changes increment the VERSION. In fact, anything increments the VERSION. If you are feeling a bit down on that particular day, you may consider bumping VERSION to feel a bit better.

Some may be concerned that major changes do not impose a sense of importance on the user, and to that I propose incrementing Version by two. Because two is larger than one, believe it or not.

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 wish to interpret them as.

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

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

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

  4. All versions are for development. Anything MUST change. The public API may be considered stable.

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

  6. Version 1.0.0 defines the public API. The way in which the version number is incremented after this release is dependent on this public API and how it changes.

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

A simple example will demonstrate how Semantic Versioning can make dependency hell a thing of the past. Consider a library called "Firetruck." It requires a Semantically Versioned package named "Ladder." At the time that Firetruck is created, Ladder is at version 3.1.0. Since Firetruck uses some functionality that was first introduced in 3.1.0, you can safely specify the Ladder dependency as greater than or equal to 3.1.0 but less than 4.0.0. Now, when Ladder version 3.1.1 and 3.2.0 become available, you can release them to your package management system and know that they will be compatible with existing dependent software.

As a responsible developer you will, of course, want to verify that any package upgrades function as advertised. The real world is a messy place; there's nothing we can do about that but be vigilant. What you can do is let Semantic Versioning provide you with a sane way to release and upgrade packages without having to roll new versions of dependent packages, saving you time and hassle.

If all of this sounds desirable, all you need to do to start using Semantic Versioning is to declare that you are doing so and then follow the rules. Link to this website from your README so others know the rules and can benefit from them.

FAQ

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

Start with 0. 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 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.

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 version of a release is below latest version, then that version is deprecated. 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 15 is larger than 13.

Does ZenVer have a size limit on the version string?

Nope. You can have an 12 billion character version for all I care.

Is "v1" a valid zen version?

Yes, because you see v usually refers to version and in this example 1 is the version. For anyone with common sense, that is a valid version.

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

Yeah just check if it's a number.

About

The Semantic Versioning specification was originally authored by Tom Preston-Werner, inventor of Gravatar and cofounder of GitHub.

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

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

License

This specification file has been partially copied from SemVer in order to address its limitations. Credits to go the respective authors of SemVer contributors.

Creative Commons ― CC BY 3.0

Footnotes

  1. We should probably learn about versioning from Microsoft. Confused? Take a look at Windows' versioning scheme. ↩