larlet-fr-david-cache/cache/2024/fd6eda56671045e0c1e2d215e07f1a6f/index.md

title: EffVer: Version your code by the effort required to upgrade
url: https://jacobtomlinson.dev/effver/
hash_url: fd6eda56671045e0c1e2d215e07f1a6f
archive_date: 2024-01-18
og_image: https://jacobtomlinson.dev/f5AJKsQ_5492213727072396532_huc4b23cc59301979e6c26bd5595602176_0_babdb9b3327c14bb629a3288d379177b.png
description: Version numbers are hard to get right. Semantic Versioning (SemVer) communicates backward compatibility via version numbers which often lead to a false sense of security and broken promises.
favicon: 
language: en_US

<p>Version numbers are hard to get right. Semantic Versioning <a href="https://semver.org/">(SemVer)</a> communicates backward compatibility via version numbers which often lead to a <a href="https://hynek.me/articles/semver-will-not-save-you/">false sense of security and broken promises</a>. Calendar Versioning <a href="https://calver.org/">(CalVer)</a> sits at the other extreme of communicating almost <a href="https://jacobtomlinson.dev/posts/2023/sometimes-i-regret-using-calver/">no useful information at all</a>.</p>
<p>Going forward I plan to version the projects I work on in a way that communicates <em>how much effort I expect a user will need to spend to adopt the new version</em>. I’m going to refer to that scheme as <strong>Intended Effort Versioning (<span>EffVer</span> for short)</strong>.</p>
<p>
<figure>
    <img src="https://jacobtomlinson.dev/effver/effver.png" alt="In EffVer you use a three number version separated by dots, referred to as Macro, Meso and Micro. You incremenet macro when adoption requires a large effort, meso when it requires some effort and micro when hopefully it requires little to no effort.">
    <figcaption>Overview of EffVer</figcaption>
</figure>

</p>
<p><span>EffVer</span> follows the same pattern of incrementing numbers to communicate with users that SemVer does, and is forward and backward compatible with SemVer (you don’t need to use something like a <a href="https://packaging.python.org/en/latest/specifications/version-specifiers/#version-epochs">Python version epoch</a> to switch between the two schemes). The difference is that instead of quantifying the orthogonality of a change EffVer tries to quantify the intended work required to adopt the change.</p>
<p>If a change fixes a small bug, adds a new feature that is orthogonal with existing features or is generally a noop for existing users then you should bump the <strong>Micro</strong> version. This signals to users that <strong>“this change doesn’t intend for you to need to do anything”</strong>.</p>
<p>If a change fixes a larger bug that some users may have grown accustom to or put workarounds in place for, or makes small breaking changes to features in a way that may require some adoption then you should bump the <strong>Meso</strong> version. This signals to users that <strong>“some small effort may be required to make sure this version works for you”</strong>.</p>
<p>If you make a huge breaking change or overhaul some large aspect of your project you should bump the <strong>Macro</strong> version. This signals to users that <strong>“you will need to dedicate some significant time to upgrading to this version”</strong>.</p>
<h2 id="why-use-span-stylecolor-0097a7effverspan">Why use <span>EffVer</span>?</h2>
<p><span>EffVer</span> may sound like “SemVer-lite” or just “SemVer done a certain way” but there are a few key things that makes <span>EffVer</span> different and worth considering.</p>
<ol>
<li><span>EffVer</span> communicates intentions. Software is created by humans (for now) and that while humans have the best of intentions around the impacts that new versions have, sometimes things are more impactful than expected. Instead of trying to quantify the techinical scope of a change <span>EffVer</span> tries to communicate the expected downstream impact.</li>
<li><span>EffVer</span> respects that all releases impact users and will require effort to adopt them, even if that’s some simple testing or updating a lock file. By trying to quantify and communicate the effort required to adopt a release developers demonstrate respect for their user’s time.</li>
<li><span>EffVer</span> doesn’t make a distinction between bugs fixes, enhancements and features (because developers struggle to make that distinction too). Instead we focus only on the effort required for existing users to adopt new versions.</li>
<li><span>EffVer</span> users can more clearly reason that <em>any</em> change can result in them needing to do some work, but that the developer using <span>EffVer</span> is trying to give them information to help them quantify and plan this work.</li>
</ol>
<h2 id="fixing-mistakes">Fixing mistakes</h2>
<p>Another core principle of <span>EffVer</span> is to acknowledge that sometimes code gets released with the wrong version number, and responsible developers should reactively fix that.</p>
<p>Imagine 1% of my users are experiencing a bug, so I make a bug fix release where I intend for only those users notice that positive change. So I increment the <em>micro</em> version number and cut a release.</p>
<p>However I was wrong, other users are negatively impacted by the change and have to make a small adjustment to their workflow to work around it. On reflection I am still happy with the change and don’t intend to revert it, but I should’ve incremented the <em>meso</em> version number instead to signal a larger impact. I made the change that I wanted to make, but I have accidentally generated work for others and I should respectfully communicate that to them.</p>
<p>With <span>EffVer</span> we encourage developers to take some steps to update the communicated impact by cutting a few more releases.</p>
<ul>
<li>Imagine my starting point was version <code>2.3.4</code>.</li>
<li>My bug fix was then released as <code>2.3.5</code>.</li>
<li>The unhappy users open issues on GitHub and I want to change the version number to communicate the impact better.</li>
<li>I check out the original <code>2.3.4</code> tag and create another new tag for this commit called <code>2.3.6</code>, this effectively reverts the impactful release so that no more users pick up the change.</li>
<li>Then I check out <code>2.3.5</code>, the impactful change, and create a new tag called <code>2.4.0</code>.</li>
</ul>
<p>Now users who have pinned to <code>~2.3.4</code> will be upgraded to <code>2.3.6</code> which is exactly the same commit and therefore doesn’t cause them any impact. And users who have pinned to <code>^2.3.4</code> will be upgraded to <code>2.4.0</code> which correctly communicates that there may be some small intentional impact.</p>
<p>I haven’t needed to change my code or make any new commits, I just add more tags to fix my communication.</p>
<h2 id="zero-version">Zero version</h2>
<p>In SemVer the <code>0.x.x</code> version has become known as the YOLO version because anything goes. Any change can be breaking and so the semantics around backward compatibility become meaningless.</p>
<p>In <span>EffVer</span> the meaning of the zero version still denotes a codebase under development but should be treated as <code>0.Macro.Micro</code>. In a development project it is more likely that changes will have a large impact, that’s just in their nature, but it’s still useful to be able to quantify the impact between each release.</p>
<p>You could also use a four segment version number with <code>0.Macro.Meso.Micro</code> if you would prefer to have the full fidelity of <span>EffVer</span> communication during development.</p>
<p>As your project matures you will likely find yourself incrementing the <em>Macro</em> version less and the <em>Micro</em> version more which is a good signal for developers that it’s time to switch to a <code>1.0.0</code> release.</p>
<h2 id="projects-using-span-stylecolor-0097a7effverspan">Projects using <span>EffVer</span></h2>
<p>Here are some notable projects that use EffVer:</p>

<p><em>Want to add your project to this list, <a href="https://github.com/jacobtomlinson/website/blob/master/content/posts/2024/2024-01-15-effver/index.md">make a PR here</a>.</em></p>
<h2 id="supporting-span-stylecolor-0097a7effverspan">Supporting <span>EffVer</span></h2>
<p>Do you like the sound of <span>EffVer</span>? If so that’s great! You can support the movement by sharing this post with people and by adding the <a href="https://jacobtomlinson.dev/effver">
<img src="https://img.shields.io/badge/version_scheme-EffVer-0097a7" alt="Static Badge">

</a> badge to any projects that are using it.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown"><span class="line"><span class="cl"><span class="gh"># Badge URL
</span></span></span><span class="line"><span class="cl"><span class="gh"></span>https://img.shields.io/badge/version_scheme-EffVer-0097a7
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="gh"># Markdown
</span></span></span><span class="line"><span class="cl"><span class="gh"></span>[<span class="nt">![EffVer Versioning</span>](<span class="na">https://img.shields.io/badge/version_scheme-EffVer-0097a7</span>)](https://jacobtomlinson.dev/effver)
</span></span></code></pre></div>
<h2 id="background-and-history">Background and history</h2>
<p>At PyCon UK in 2023 I gave a lightning talk based on my blog post <a href="https://jacobtomlinson.dev/posts/2023/sometimes-i-regret-using-calver/">“Sometimes I regret using CalVer”</a>. My talk was immediately followed by <a href="https://hynek.me/about/">Hynek Schlawack</a> who aside from creating great Python libraries like <a href="https://github.com/python-attrs/attrs"><code>attrs</code></a> and <a href="https://github.com/hynek/structlog"><code>structlog</code></a> is known for his blog post <a href="https://hynek.me/articles/semver-will-not-save-you/">“Semantic Versioning Will Not Save You”</a>.</p>
<p>Interestingly many folks assumed that our dislike of different version schemes meant we vehemently disagreed with each other, but far from it. We totally agreed that the two most popular versioning schemes were imperfect and this resulted in some excellent post-conference pub discussion.</p>
<p>Ever since then I’ve not been able to stop thinking “there has to be another option”.</p>
<h3 id="the-challenges-of-existing-schemes">The challenges of existing schemes</h3>
<p>Both my and Hynek’s blog posts go into detail about the failings of existing schemes, but I want to focus on the attributes that translate to work required by downstream users.</p>
<h4 id="semver">SemVer</h4>
<p>SemVer attempts to communicate if an upgrade is safe or not, but can easily get this wrong.</p>
<p>When you fix a bug in your code you can argue that the code is now “more correct”. SemVer assumes it is safe for <em>everyone</em> to adopt this new code immediately because of this increased “correctness”, but the trap that SemVer falls into is the fact that every bug has users.</p>
<p>
<figure>
    <img src="https://jacobtomlinson.dev/effver/xkcd-1172-workflow.png" alt="xkcd 1172: workflow. A comic strip showing a user who is upset that holding the space bar no longer makes their computer overheat because they relied on that behaviour">
    <figcaption><a href="https://xkcd.com/1172">xkcd #1172: Workflow</a></figcaption>
</figure>

</p>
<p>People trust SemVer to not break their code and then feel angry when things go wrong because when SemVer fails users have to react and often have urgent work to do.</p>
<h4 id="calver">CalVer</h4>
<p>CalVer attempts to communicate that no upgrade is safe, but in doing so strips all useful information from the version number.</p>
<p>For example if you fix a small bug in your code and make a release, then the next day you delete half the API and make another release, nobody can tell the difference between the two versions.</p>
<p>
<figure>
    <img src="https://jacobtomlinson.dev/effver/happy-new-year.png" alt="A meme showing two scary dragons and a derpy one to describe major version releases. The first is ChangeVer and says there are major new and exciting things, the second is SemVer and says we broke something and the third is CalVer which says happy new year.">
    <figcaption>If you're wondering what ChangeVer is, it's what I call the 90s boxed software version scheme where you were obliged to make visible changes to your prouct and increment the major version in order to get people to upgrade from the old version. Change for the sake of change.</figcaption>
</figure>

</p>
<p>People feel anxious about upgrading CalVer projects because they don’t know if the change will be small or huge. As a result they are more likely to pin their dependencies and upgrade in a more proactive and managed way, which is good, but the lack of information makes upgrading hard to schedule and so it often gets put off.</p>
<p>If you read the CalVer website they <a href="https://calver.org/#ubuntu">highlight Ubuntu</a> as a high-profile user of CalVer. However, Ubuntu has shoehorned in a bunch of semantics to their versioning scheme by only creating April and October releases to make it clearer to users which versions are <em>major</em> versions. They wanted to communicate which versions take more effort to migrate between because communicating user impact is important.</p>
<h3 id="momentum">Momentum</h3>
<p>The biggest challenge for switching version scheme is the momentum of other schemes in the ecosystem. SemVer is well established, and CalVer is also very common. Because of that <span>EffVer</span> is intentionally identical in structure to SemVer. This means that any tooling or process assumptions built around SemVer will work for <span>EffVer</span>.</p>
<p>Any SemVer project can switch to <span>EffVer</span> by just changing how they decide the version number of the next release. If you try <span>EffVer</span> out and would prefer to go back to traditional semantics then switching back is also just the same process change.</p>
<p>Switching to CalVer is more of a one way street, and although some languages have a <a href="https://packaging.python.org/en/latest/specifications/version-specifiers/#version-epochs">process for switching back</a> it’s not guaranteed to be a smooth ride. So if you ever do switch to CalVer can I suggest you use <code>YY.MM.DD</code> instead of <code>YYYY.MM.DD</code>, that way you could switch back to <span>EffVer</span>/SemVer and keep your <em>major</em> version number below 100.</p>