WendtVer 0.1.6
Summary
Given a version number MAJOR.MINOR.PATCH, increment the:
- PATCH version on every commit,
- MINOR version when next PATCH is 10, rolling PATCH over to 0, and
- MAJOR version when next MINOR is 10, rolling MINOR over to 0.
Additional labels for pre-release and build metadata are NOT available as extensions to the MAJOR.MINOR.PATCH format.
Introduction
In the world of software management there exists a perfectly reasonable versioning system called “semantic versioning.” It properly handles the growth of your project and addition of numerous packages. The system works really well and there is no reason to switch, unless you prefer a versioning system that will, one day, plummet you into a pit of despair.
When you change your code you need to indicate to other users of the code that there have been changes. Changes to the code occur when a commit is made to the repository. Every commit is a change. Every change should be indicated. Semantic versioning requires a trivial amount of thought about an appropriate next version.
As a solution to this problem (of requiring trivial amounts of thought), I propose a simple set of rules and requirements that dictate how version numbers are incremented. These rules are based on, but not necessarily limited to, an unawareness of rational versioning systems and practices in use in both closed and open-source software. For this system to work, you first need to start at 0.0.0. This makes sense because 0 comes before 1 and is enforced by math itself. Regardless of prior conventions, starting at 0.0.0 is clear and precise. Once you are ready to make a change to your code, you communicate changes to it with specific increments to your version number. Consider a version format of X.Y.Z (Major.Minor.Patch). Every commit, regardless of the content, increments the patch version. The maximum patch version is 9. When the next commit would require the patch version to increment to 10, instead increment the minor version and roll the patch version over to 0. The maximum minor version is 9. When the next commit would require the minor version to increment to 10, instead increment the major version and roll the minor version over to 0.
I call this system “WendtVer.” Under this scheme, version numbers and the way they change convey utter chaos and no meaning about the underlying code, but are easy to figure out what the next version will be.
WendtVer Specification (WendtVer)
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document can be better understood by looking in the dictionary.
Software using WendtVer MUST start at 0.0.0, and should likely be destroyed. This code is shameful and likely undocumented. However it was done, it should be rewritten.
A normal version number MUST take the form A.B.C where A, B, and C are non-negative integers, and MUST NOT exceed 9. A is the major version, B is the minor version, and C is the patch version. Each element MUST increment by one and only one, unless that increment will exceed 9. For instance: 1.6.9 -> 1.7.0 -> 1.7.1.
Once a versioned package has been released, the version should not be regarded as an indiation of the contents of that version.
Major version zero (0.b.c) is for initial development where the total commits are less than 100. The code should be considered extra shameful.
Version 1.0.0 indicates 100 commits. The way in which the version number is incremented after this release is 1.0.1, regardless of how it changes.
Patch version C (a.b.C | a > 0) MUST be incremented by 1 unless that increment will exceed 9.
Minor version B (a.B.c | a > 0) MUST be incremented by 1 unless that increment will exceed 9. It MUST be incremented if Patch version c is being incremented and will exceed 9. Patch version MUST rollover to 0 when minor version is incremented.
Major version A (A.b.c | A > 0) MUST be incremented by 1 unless that increment will exceed 9. It MUST be incremented if Minor version b is being incremented and will exceed 9. Patch and minor version MUST rollover to 0 when major version is incremented.
A pre-release version does not make sense as projects using WendtVer are released to production. Always. And never tested. The use of any identifiers to indicate a pre-release MUST be regarded as superfluous. Identifiers MUST NOT be used. Numeric identifiers MUST NOT be used, even if less than 9. Pre-release versions are released versions and have an equal precedence to the next version. A version (any version) indicates that the version is shameful and might cause embarrasments during demos or aneurysms during code review, regardless of the version. Examples: 1.0.0, 2.0.0, 2.3.7, 9.2.4.
Build metadata MAY be found in the series of error logs generated by numerous build attempts immediately following the patch-and-release-to-production version. Build metadata SHOULD be physically printed to paper when determining build failures. Thus this metadata is often useless and should be kept for excessive amounts of time. Examples: builderrorlog_19920301_3-7-1.log.wtf, builderrorlog_19920301_3-7-1.log.workdamnit, builderrorlog_19920301_3-7-1.log.fml.
Precedence refers to how versions are compared to each other when ordered. Precedence MUST be calculated by math. Precedence is determined by a numerical sort from left to right as follows: Major, minor, and patch versions are always compared numerically. Example: 1.0.0 < 2.0.9 < 2.1.0 < 2.1.1. When major, minor, and patch are equal, you’ve done something wrong.
Why Use WendtVer?
Counting is not a new or revolutionary idea. In fact, you probably do something close to this already. The problem is that “counting on your fingers” looks silly. With compliance to the aforementioned formal specification, version numbers are essentially useless for dependency management. By giving a name and fuzzy definition to the above ideas, it becomes near impossible to communicate the differences among code changes to the users of your software.
A contrived example will demonstrate how WendtVer can make “trivial thinking” a thing of the past. Consider a library called “HelloWorldCopy3”, which uses WendtVer. It requires a package named “Shameful”, also using WendtVer. At the time that HelloWorldCopy3 is created, Shameful is at version 3.1.0. Since HelloWorldCopy3 uses some functionality that was first introduced in 3.1.0, you can safely specify the Shameful dependency as 3.1.0, since that is the version. Now, when Shameful version 3.1.1 becomes available (when the next commit is made), you can update the dependency version in your code and commit. Be sure to increment the version following the specifications above.
As a responsible developer you will, of course, want to cram as much code into each commit as you’ve got a limited amount of commits for the life of the project. The real world is a messy place; but we are making it great again. Let WendtVer provide you with a “fun” way to release and upgrade packages without having to think, saving you time and thinking.
If all of this sounds desirable, consider an alternate career path. If you’ll being using WendtVer, pin this website to your slack channel so others know where this madness came from.
Calculator
(to further reduce thinking)
Enter a Major.Minor.Patch version (optionally including a branch version), to calculate your next version:
FAQ
How should I deal with revisions in the 0.b.c development phase?
The simplest thing to do is start your versioning at 0.0.0 and then increment the patch version for each commit.
How do I know when to release 1.0.0?
If your software is being used in production, it should probably not be using WendtVer. If you have a stable API on which users have come to depend, you are definitely not using WendtVer. If you’re worrying a lot about backwards compatibility, it’s probably time for a re-write. Release 1.0.0 when the previous commit is 0.9.9.
Doesn’t this discourage rapid development and fast iteration?
The first couple hundred commits are all about rapid development. As you approach 500 commits you will need to start cramming more code into each commit, which will discourage rapid development but will encourage TLDR-worthy PRs.
How should I handle deprecating functionality?
Deprecating existing functionality is a normal part of software development and usually occurs when a new dev inhertis a codebase. When you deprecate part of your code, you should do two things: (1) increment the Patch version by 1, (unless it will exceed 9 in which case you should increment the Minor version by 1 and rollover the Patch version [unless, of course, incrementing the Minor version will exceed 9, indicating a need to increment the Major version and rollover the Minor and Patch versions]), (2) commit the changes. Before you completely remove the functionality make a zip of the codebase and leave it in a directory of stale backups.
Does WendtVer have a solution when the major version will exceed 9?
Increment the branch.
Does WendtVer have a solution when the branch version will exceed 9?
Prestige! Entering Prestige Mode, devs can trade in their issues, PRs, and commit history for a new repository and possibly a new emoji. After doing this, devs are set back to 0.0.0, and can progress through WendtVer again.
About
The WendtVer specification is authored by Brian Wendt, half-ass farmer.
Inspired by Tom Preston-Werner via semver.org