Proposing an extended SemVer -
🗿 Epoch Semantic Versioning
to communicate better about versions.
Thinking of adopting this to all my projects, and finally eliminating my lousy habit of forever zero-major practice 😜
What do you think? 👀
https://antfu.me/posts/epoch-semver
🗿 Epoch Semantic Versioning
to communicate better about versions.
Thinking of adopting this to all my projects, and finally eliminating my lousy habit of forever zero-major practice 😜
What do you think? 👀
https://antfu.me/posts/epoch-semver
Comments
My idea of “stardates” is the number of days since 00:00 01-Jan-1970 UTC, to one decimal place.
E.g. the stardate right now is 20096.2.
What!? I missed 20000.0, just about a minute and a half ago!?
Not possible unfortunately
As a heavy user of semantic-release, I'm wondering how we might denote the jump from 100.x.x to 200.x.x.
Semantic commits make it easier to manage smaller version jumps, but incrementally shipping big rewrites like this might be more challenging.
https://gist.github.com/Zekfad/f51cb06ac76e2457f11c80ed705c95a3
- fix github action
... (x commits later)
- F**** U GITHUB ACTION
The squashed commit needs to follow convco though, and that one erases all the CI ping pong.
https://github.com/franky47/actions-laboratory
Are most libs compatible? Npm's semver truncate after three parts.
I was tempted for a while to adopt a versioning where major is the current year (2025.0.0) but it limits major versions to one per year...
Otherwise, Epoch is fine but the truth is that SemVer has enough judgement calls in it that devs need to understand how major and minor updates are interpreted *per project*. (Hopefully, patches are truly only bug fixes).
It is amazing how "clever" some devs can be.
💯 Totally! Also, when using open-source projects, users are technically required to review every single change, as there are no warranties.
In reality, people tend to trust maintainers as well as versioning, which is why it's still important.
and trying to "improve" it by adding another numeric section seems silly.
the heck am I talking about? here, take a look:
https://m.youtube.com/watch?v=oyLBGkS5ICk
One thing I don't like is until you finish one epoch there's no way of telling you're using this scheme, so I'd say ESV should start at 101.0.0
I still think SemVer is fine, and:
- MAJOR should bump for *intentional* breaking changes—can't foresee unintentional ones like bug fixes
- we should decouple marketing from tech versionning (e.g. named releases)
The current status quo is still not ideal 😄
https://xavd.id/blog/post/versioning-as-communication/
Yours is an interesting approach, I'll be curious to hear how your users like it!
But I just came across a side effect: `peerDependencies`.
For example, I think UnoCSS used to be "unocss: ">= 0.31.13 < 1" and now it should be "unocss: ">= 0.31.13 < 100"
I think is an elegant solution the use of 100s for "major" versions. It is compatible! 🤘
Other than that, I think your new interpretation is fine. Doesn’t seem to me to be necessary as I don’t buy the “humans see it as log” thing.
- Adds complexity
- Non-standard in a way that users lose the ability to infer what's going on with major version skips until they read an explanation
I think going the other way around and removing complexity is a good approach and worth considering by collapsing patch into minor i.e.
minor - unintentional breaking change (includes bugfixes)
I think this is the most important distinction for users, is SemVer compliant, and doesn't require an explanation for users to upgrade versions intuitively
If not often, v1 still seems valuable to prevent number fatigue. So personally I wouldn't blanket adopt epoch semver 😅
Maintain clarity, ensure compatibility, and keep it user-friendly—all while staying in charge.
1. Normalize code mods.
- This should be much more common; perhaps AI can make these easier to produce.
- Tools auto apply Code Mods between your old and new versions.
2. Add a breaking indicator on the version.
- Don't rely on Major/Minor changing to indicate breaking changes.
My take: tiny marketing win at the cost of awkward gaps in the versioning scheme, meh.
In my experience, 10 breaking changes are not easier to deal with when spread as 7 majors instead of 1. The only thing that is easier: fewer breaking changes.
Downsides:
- flip-flopping changes (v11 changed an API, v16 changed it again, v21 yet again…);
- encourages maintainers to give low guidance for breaking changes.
I treat projects releasing 2+ majors a year as a red flag.
In all seriousness - this is a great proposal 👏. Not sure if you're aware but you make a cameo appearance in my talk about API design on slide 31 because of I first heard about Epoch Semantic Versioning from you 🚀
cacheTime(args);
}
/**
* @deprecated use gcTime(args)
*/
function cacheTime(args){
// ...
}
?
(What is "gcTime" supposed to mean? Garbage Collect? Why not "dispose"/"free"/"clear"?)