EffVer - Version your code by the effort required to upgrade

Version numbers are hard to get right. Maintainers want to communicate to users what the impact of adopting a new version will be, but poor communication can lead to a lot of frustration. There are a few popular version schemes in use today including Semantic Versioning (SemVer) and Calendar Versioning (CalVer). However, projects in the Python community often don’t strictly conform to these standards which leads to confusion.

In this talk we will discuss Intended Effort Versioning (EffVer), a new scheme that captures the reality of what many Python projects do today. This formalisation has been officially adopted by projects including Jupyter Hub, Matplotlib, JAX and many more.

It’s very common for projects in the Python ecosystem to try to follow Semantic Versioning (SemVer), a scheme that adds specific meanings to each version segment and guarantees backward compatibility in all but major releases. In practice many projects violate the semantics laid out in SemVer because often reality is more complex than the scheme allows for.

Some projects go another route and use Calendar Versioning (CalVer), a scheme that intentionally gives no meaning in the segments other than the date the software was released. This information causes challenges in other ways, such as not communicating how much effort it will be to adopt the new version or misleading users to believe that releases of different projects from the same time period will be compatible.

EffVer is forward and backward compatible with SemVer, making it easy to adopt for projects already loosely following SemVer. However, instead of communicating specific semantics about what a release contains, it communicates the magnitude of the effort required to adopt those changes. This is already what many Python packages do today, but by formalising things it makes it easy for maintainers to reason about what the next version of a project should be, and allows users to more clearly understand how much effort they need to spend to adopt a new version.

Transcript

1. EffVer jacobtomlinson.dev/effver Version your code by the effort required to upgrade
2. 2.4.8
3. 2.4.8 2.5.0
4. 2.5.0 Semantic Versioning (SemVer) MAJOR incompatible API changes MINOR backward compatible features PATCH backward compatible bug fixes https://semver.org/
5. 2.5.0 Semantic Versioning (SemVer) Adoption will require effort I can adopt without thinking https://semver.org/
6. 2.5.0 Semantic Versioning (SemVer) Adoption will require effort https://semver.org/
7. 2.5.0 Semantic Versioning (SemVer) Adoption will require effort https://semver.org/
8. 2.5.0 Semantic Versioning (SemVer) Adoption will require effort https://semver.org/
9. 2.5.0 Semantic Versioning (SemVer) Adoption will require effort https://semver.org/
10. Hyrum’s Law Further reading https://xkcd.com/1172/ https://www.hyrumslaw.com/ https://hynek.me/articles/semver-will-not-save-you/ With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody.
11. Example: Exception changes are breaking They just usually don’t affect many people Bug: https://github.com/pandas-dev/pandas/issues/52812
13. Is there another way?
14. 2025.7.8
15. 2025.7.8 2025.8.0
16. 2025.8.0 Calendar Versioning (CalVer) YEAR year of release MONTH month of release INCREMENT Monotonic index (allows multiple releases in a day) https://calver.org/
17. 2025.8.0 Calendar Versioning (CalVer) https://calver.org/ I have no idea if this upgrade will require effort, so I must assume all upgrades require effort
18. Example: Ubuntu They use CalVer right? Ubuntu 24.04.2 LTS https://calver.org/#ubuntu
19. Ubuntu 25.04.0 Ubuntu 24.10.0 Ubuntu 24.04.2 LTS Ubuntu 23.10.1 Ubuntu 23.04.0 Ubuntu 22.10.0 Ubuntu 22.04.5 LTS Example: Ubuntu They use CalVer right? https://calver.org/#ubuntu
20. Ubuntu 25.04.0 Ubuntu 24.10.0 Ubuntu 24.04.2 LTS Ubuntu 23.10.1 Ubuntu 23.04.0 Ubuntu 22.10.0 Ubuntu 22.04.5 LTS Example: Ubuntu They use CalVer right? https://calver.org/#ubuntu
21. Example: Ubuntu Oh wait do they use SemVer? (or at least semantics, because communication is important) Ubuntu 24.04.2 LTS Adoption will require effort I can adopt without thinking https://calver.org/#ubuntu 💀
22. https://jacobtomlinson.dev/posts/2023/sometimes-i-regret-using-calver/
23. SemVer • Good for strongly defined code (inputs, outputs and side-effects) • Good for small teams maintaining 100% of their code and dependencies • Good for projects with rigorous software engineering practices • Bad for community open source projects with large API surfaces CalVer • Good for things with behaviour changes but no API changes. E.g models, configuration • Good for distributions. Opinionated collections of many packages. • Bad for communicating information to humans about impact
24. Is there another way?
25. Is there another way? Many Python projects already do things differently, let’s give it a name!
26. EffVer Used by And likely many more… jacobtomlinson.dev/effver
27. Macro Meso Micro Upgrading to a new version intends to require: no effort some effort a large effort EffVe jacobtomlinson.dev/effver
28. “Version numbers are a social contract and can’t exist in isolation” Angus Hollands MyST, Project Jupyter, 2i2c, Awkward Array
29. How do I choose a new version number?
30. Risk Modelling https://en.wikipedia.org/wiki/Risk_matrix
31. What happens if more people are impacted than I thought?
32. v2.1.1 a6c9e5
33. v2.1.1 a6c9e5 c1a77e
34. v2.1.1 v2.1.2 a6c9e5 c1a77e
35. v2.1.1 v2.1.2 a6c9e5 c1a77e
36. v2.1.1 v2.1.2 a6c9e5 c1a77e v2.1.3
37. v2.1.1 v2.1.2 a6c9e5 c1a77e v2.1.3 v2.2.0
38. v2.1.1 v2.1.2 a6c9e5 c1a77e v2.1.3 v3.0.0
39. What if I add a huge new feature that has no impact at all on existing users?
40. Macro Meso Micro Over bumping a segment can draw more attention to a release ignore me notice me really notice me EffVe jacobtomlinson.dev/effver
41. What about 0.x.x?
42. “[In SemVer] the promise is that as long as MAJOR doesn’t change ... nothing will break ... unless MAJOR is a zero, which means YOLO time for the maintainer: anything goes.” Semantic Versioning Will Not Save You Hynek Schlawack https://hynek.me/articles/semver-will-not-save-you/
43. 0 Macro Meso Projects early in development can and should still communicate impact even on a zero version some/no effort large effort EffVe jacobtomlinson.dev/effver
44. Benefits of EffVer • EffVer communicates intentions to busy humans writing software • EffVer respects that all releases require effort from downstream developers • Users can more easily decide when to read the CHANGELOG of an EffVer project • EffVer doesn’t differentiate between features and bugs, only impacts • EffVer helps you fix “broken” releases where the wrong version was chosen • EffVer lets you develop with a 0.x.x version that contains useful information jacobtomlinson.dev/effver
45. EffVer Used by And likely many more… jacobtomlinson.dev/effver Probably not new, but now it has a name
46. 0000001111101000011111000100000111100101011110010110100001110100011110100001000111110 0111001100000100010000011111000001101110100100001111000000101101000100101010110111010 0010111000111011111101110011010101010101001101101100011101101010011110000101000000000 0011111010000111110001000001111001010111100101101000011101000111101000010001111100111 0011000001000100000111110000011011101001000011110000001011010001001010101101110100010 1110001110111111011100110101010101010011011011000111011010100111100001010000000000011 1110100001111100010000011110010101111001011010000111010001111010000100011111001110011 0000010001000001111100000110111010010000111100000010110100010010101011011101000101110 0011101111110111001101010101010100110110110001110110101001111000010100000000000111110 1000011111000100000111100101011110010110100001110100011110100001000111110011100110000 0100010000011111000001101110100100001111000000101101000100101010110111010001011100011 1011111101110011010101010101001101101100011101101010011110000101000000000001111101000 0111110001000001111001010111100101101000011101000111101000010001111100111001100000100 0100000111110000011011101001000011110000001011010001001010101101110100010111000111011 1111011100110101010101010011011011000111011010100111100001010000000000011111010000111 1100010000011110010101111001011010000111010001111010000100011111001110011000001000100 0001111100000110111010010000111100000010110100010010101011011101000101110001110111111 0111001101010101010100110110110001110110101001111000010100000000000111110100001111100 0100000111100101011110010110100001110100011110100001000111110011100110000010001000001 1111000001101110100100001111000000101101000100101010110111010001011100011101111110111 0011010101010101001101101100011101101010011110000101000000000001111101000011111000100 0001111001010111100101101000011101000111101000010001111100111001100000100010000011111 0000011011101001000011110000001011010001001010101101110100010111000111011111101110011 0101010101010011011011000111011010100111100001010000001011010000111010110100010111000 Thank You @jacobtomlinson.dev https://jacobtomlinson.dev/effver