I think this is a nice way to clarify the different use cases for version numbers:
- SemVer is a communication tool for when an author needs to tell a potential user what to expect from a new version.
- TrunkVer is an auditing/engineering tool for when you need to give a unique identifier to a version for technical reasons.
I think this page is a nice codification of a useful practice, but it does itself a disservice by positioning itself against SemVar and claiming to be a "drop-in" replacement.
It's a "drop-in" replacement in the sense that it's compatible with the format and with the rough semantics of SemVer. That is, if your libraries / packages all use SemVer, but the final executable / image uses TrunkVer, the latter does not need to be special-cased. TrunkVer gives a stream of "major versions" that's strictly increasing and all incompatible, and uses non-version fields to convey useful info. All SemVer-based tools will accept a TrunkVer value and do the right thing (that is, always prefer the newest build).
In what way is this „SemVer-compatible“ when you just ignore the „Major increment <=> breaking changes“ convention? It has 3 numbers separated by dots? This just increments major version every time a build is started, even though there might not be breaking changes.
The formal spec technically only tells you that you MUST increment Major for breaking changes, and not that you can’t do it every time, but the FAQ makes it clear what the spirit of the rule is. I can’t see how TrunkVer can be called SemVer compatible with this construction method.
It sounds like a disaster. Trunk-based deployment does not imply such an extreme degree of instability, because all development may happen on other branches. I see what you're trying to say though. I think the real keyword is "continuous integration."
Why do you think so? It shouldn't be used for something like a library or an external API that other people rely on where communicating about breaking changes is actually important.
For something like a web application, I don't think it matters much. Do you know which version of Google Docs you're using? Do you care?
Saying it's semver compatible mostly means that you can use existing tools that work with semver and make assumptions about how version numbers can be sorted.
You're not technically wrong but using the 3 numbers this way is in fact going to create problems for people trying to use this info. It means that you can never know if any version is compatible with others, and even if they were you could not easily link it.
It’s not creating a new problem that didn’t already exist.
In many situations at work, trying to follow SemVer would be a technical solution to a non-technical problem.
You know who your users are. Before you make any breaking change, you already have cross-product team meetings with possible executive buy in.
In those scenarios, by time you assign a version number, everyone is already on the same page. The actual version number is meaningless and conveys no useful information. Spending any time on deciding the version creates unnecessary toil.
It is creating a problem that didn't exist because using this instead of SemVer eliminates the option to communicate meaningful compatibility information.
>You know who your users are. Before you make any breaking change, you already have cross-product team meetings with possible executive buy in.
Generally none of these things are true. You don't know your users or how they intend to use your product. The executives certainly don't care about version numbers.
There are some cases where nobody cares about version numbers, which mainly occur when there is one or a handful of consumers of a product and they are likewise committed to very frequent releases. This is not how most distributable libraries work. Furthermore, people care less about version numbers when the numbers are not correctly assigned in the first place. If you aren't using SemVer then it's just an increasing sequence for the most part.
well, yes, this is the only safe thing to do. The build system has no information what has changed since last build - maybe it was a complete interface rewrite - so it does the safe thing.
I’ve been happily using date base version numbers in any user facing product (e.g apps) for a while now. It’s been great.
While semver makes great sense on paper, and even allows nifty little algebras in dependency declarations, it is been my experience that the delineations are not always as easy to decode and different team members can quibble over the exact realization of the boundaries.
Furthermore, it’s very much been my experience that semver changes, like all code comments, only communicate the intent of the developer and not always the reality. A minor roll may be anticipated as backwards compatible, until an unrealized use case pops up and makes the minor change very breaking.
semver is useful for libraries and other things that have a very clear programmer interface.
For most applications it's fairly pointless. There are often many "breaking changes" in any significant release, and there is no strong agreement at all on what a "breaking change" even is.
> Furthermore, it’s very much been my experience that semver changes, like all code comments, only communicate the intent of the developer and not always the reality.
This is the truth and the reason why SemVer is fundamentally wrong for almost all cases that people use it for. Fools with keyboards and big salaries hallucinate a contractual certainty where none exists.
If you understand that the "sem" in semver is specifically about semantics and not about anything else, and that an API includes its current semantics in the semver, then it makes sense.
The issues I've struck with other developers:
1. Defining the boundaries of the API
2. Defining the semantics of the API from the perspective of the user
The funny thing about trunkver being "compatible" with semver is that it is not semantically compatible, only format compatible.
You could (but not necessarily should) combine them by making the trunkver the "patch" part of semver.
In our work, the semver is kept separate from the build version. We use a build versioning of vYYYY-MM-DD[.hhh] where hhh is for a "hotfix" of a previously released version.
The version of the "next" release can be set (either in advance, or based on a sprint or just the current date).
The EBNF in the page does not match the textual description:
- "ALPHANUMERIC" is only letters, not numbers
- "BUILD_REF" can contain dashes/hyphens "-"
- "GIT_COMMIT_REF" is the letter "g" and a single hex character
- "BUILD_REF" and "SOURCE_REF" may be empty, since they are 0 or more repetitions
- "TIMESTAMP" is arbitrary numbers, so month or hour may be "99" for example
While I understand the point you're making, some of these don't seem like they should _technically_ be an issue in terms of whether a parser following the textual descriptions would work on the actual thing. Any parser written to accept an alphanumeric string should presumably accept a purely alphabetic one, and I'm pretty sure a "ref" in git doesn't just mean a hash but also refers to branches and tags, either of which could have a name in the format you describe. Given that the point of EBNF is to define grammar to a degree of precision and conciseness that textual descriptions can't match, I don't think it's a super big deal. From the perspective of building a parser from EBNF, the names of the tokens don't matter.
On the git part: the text only mentions "git commit checksum", not "branches and tags" -- and it couldn't, since these are not immutable nor are they restricted to hex characters.
My point above is that the EBNF defines "GIT_COMMIT_REF" to be the letter "g" and a _single_ hex character. So "GIT_COMMIT_REF" may be "g0", "g1", ... "g9", "gA", ... "gF", "ga", ..., "gf". That's it. Which obviously contradicts the text and the intention.
> don't seem like they should _technically_ be an issue
Sure, people can ignore the EBNF. But if you expect that, then why publish it at all? EBNF is specifically used to describe formats and get rid of ambiguities present in text description. Not being careful with it just undermines whole idea.
I'm not saying to ignore the EBNF; I'm saying to ignore the identifiers used in the EBNF. It doesn't matter that ALPHANUMERIC is alphabetic only because the identifier is just used as a shorthand for the tokens it represents. You could literally put anything down instead of ALPHANUMERIC and it would work the same, so the fact that the name isn't a perfectly precise description isn't a big deal.
For example the text talks about "ASCII alphanumerics [09-A-Za-z]", the relevant EBNF rule is called "ALPHANUMERIC", but its definition is only letters.
It's not the problem that it's called "ALPHANUMERIC" -- it's that it should describe alphanumerics and it doesn't.
A sequential build/release number would suffice in many cases.
If the thing you're shipping isn't meant to be a dependency for other projects, then semantic versioning doesn't really fit.
In trunkver though, using the timestamp of the build time is a little weird, since you could inadvertently end up building an earlier version of trunk at a later time.
Putting an identifier of the job that built the release in the version number also seems heavy for what could just be an entry in a log file for when you need those forensics.
Time is sequential. Otherwise, sequential build numbers are kind of hard to orchestrate in a distributed architecture. Not impossible. But it introduces complexities if you have many build machines.
I don't think semver compatibility is that relevant/meaningful here. Normally I'd also want the branch name as part of the version tag. We do that with our docker containers. Adding the timestamp at the beginning is a good idea as it helps sort things by recency. I might copy that. The CI build id is nice, but I typically don't archive these anyway. All this concatenated gets a bit long.
What happens with build number is you end up going back to the CI system and looking up what change it actually built and when it happened. I can see the advantage of having all 3 in the build name, I have done similar in the past for continuously released server software where there is no need for versioning numbers although typically I too have shortened it to just the build number because we have the CI system to go into if we need to.
Generally agree with your points about how semver isn't really necessary. I suppose the benefit here would be that dep management tools like dependabot could automatically raise pull requests when a new version is released, which would be pretty cool. If only my peer engineers actually paid attention to dependency updates.
As an aside, instead of an auto incrementing build number I'd suggest the git sha since it's:
1. Already there and points to a specific version of the code in the repo
2. Globally unique
3. Can assist with reproducible builds (i.e. 6afed54 was acting weird, let's build it locally and take a look)
4. Gives you an easy diff target to dump "release notes". Just diff to the previous and dump the merge commit messages.
The problem with sequential build/release number is that you have to keep it in git (so you could increment), which results in a number of complications and annoyances.
Often the version string is baked somehow into the artifact. If it contains volatile data that is not functionally dependent on the source (the when and how) it prevents the build from being reproducible.
My opinion is that the pure semver should be part of the source and be baked in the artifact. Date and build metadata should be recorded close but separate from the artifact.
Right, just like if I were to write in english while only following the grammar rules, but without making any sense, it would be "english compatible" i guess.
It's called _semantic_ versioning, and trunkver loses the whole point of it.
The whole concept would have been better if it didn't even try to mention semver in the first place.
Versioning could also be determined from:
1. User-centric: Has --help changed? If not, it is minor bump.
2. Developer-centric: Will conflicts occur if a new commit is cherry-picked onto the prior release?
I like linear Git histories, but image if we could "widen" a linear history maximally - so all non-conflicting commits "branch out" and only merge when needed.
This is needed because people misunderstand the purpose of semver (IMNSHO).
Semver is about the semantics of the software (it's in the name), so it's entirely about that software's interface (whether to the programmer via API, other software, users).
It's not about the implementation (except perhaps the "patch" component). If you fix a bug that doesn't change the interface, then there's no bump to the semver.
"Trunkver" is about the implementation, but in a semver compatible format.
What kills me with that website is that an example version string is nowhere to be found. The same thing almost plagues the TrunkVer page (unless you realize that you are supposed to ignore the newlines in that gray intro box), except at the very bottom you can see a dogfooded TrunkVer of the spec page itself.
If you want your thing to be popular, make sure someone dumb like me skimming the marketing blurp can quickly understand what the thing looks like in the wild.
I've been using something like this for the Unity game I'm working on where I need regular updates. However, I don't think it let me use 14 numbers in the major field. So I've stuck with something along the lines of <year>.<month>.<date>-<hours*60+minutes> to better saturate. It's nice to know there's a standard for this though.
I can see using this if what you're building is at the end of the supply chain, and there is really less need to make the claims that SemVer does. Conversely, if you have downstream consumers, I can't imagine taking away the compatibility statements in SemVer.
It depends whether the consumers have any choice about whether to receive the update. If what you're versioning is a web app, they're getting the update no matter whether they think current and next are compatible or not. And if they aren't compatible in a way that's going to cause problems, you need to be communicating richer information to them than a change in a version number anyway.
What if the CI vendor decides to use the same for its ids? Then you have even longer version numbers.
And if CI vendors aren't expected to adopt this, why expect a lot of devs to?
On my computer, the CI version ID wraps, because between the other parts of the version and the padding, there isn't enough space. I think that says something about the length of the version identifier.
This breaks efficient dependencies resolution. SemVer is called that because versions carry semantic meaning, TrunkVer appears no better than using UUIDs for each version name. You know nothing of the relation between two versions in this scheme, other than which came first.
Here's the thing about versions: they are never "complete", Because you never have just one version.
Whatever you are looking at is most likely an amalgam of many different things, which all have their own versions. Your one perfect holy version number does not tell you those versions, so you have to look them up at some point (you did save the versions of all your dependencies and pack them into a BOM, right?).
This trunk version similarly does not encode all the information you need. And what is it going to be used for? A python package? Every python package? A docker container? What about all the versions of stuff in that container? What about the helm chart that will ship this container, what's it's version? What about the version of all your helm charts that have been tested as working in stage before shipping them to prod?
If you're going to have a "generic incremented trunk version", just make it a plain-old continuously incrementing integer (or hex, or whatever) with no semver. Because you're going to have to look up more information about what's inside it later anyway, and everything's going to have its own version as you modify individual items.
Packing all this extra information in is actually counter-productive, because it's now much longer and more complex (which makes it harder to just compare a list side by side), yet it doesn't give you enough info. Ok, datestamp; where's the timezone? Ok, git sha; which repo (and has history been rewritten, or the files moved to a different repo)? Ok, CI build number; which build system (if you have multiple, or you moved from one to another)?
Maybe some of it you can intuit, but eventually you'll wish it was different again. Might as well just make it a plain integer you can pass to a script that dumps out everything related to it.
Semver's primary use case is not identifying what's inside or where it came from. The numbers are little more than a simple incrementor, and the use case is just a user who wants to know how afraid they should be. It's intended solely to communicate how likely this thing is to fuck your shit up. If it's a major version change, here be dragons. If it's minor, be cautious. If it's a patch, it should be harmless. Semver is a threat indicator. And it's easy to work with because it's so simple; comparing versions is easy. Comparing a wall of these TrunkVers will be like staring at The Matrix code.
(SemVer's supposed to tell you what dependencies it can work with (>major, >major.minor, etc), but you still need the entire dependency DAG to have a pair of package name and version in order to make sense of it; you could do the exact same thing with a list of names and simple integers (foo >= 23456, foo<1234); now imagine with this TrunkVer (foo >= 20241127214906.0.0-g1f8292a-12058740477-1)...)
This is pretty much what we do already. Every docker image we push to the registry has a version like trunkVer (with only the first 2 components). The version is also put inside the image (in a file named /TAG) and is put in:
* first log line
* last log line
* response headers
* on some about page of the web app
Difference with trunkVer: we do not have the last component (the CI bit), the first bit we use a more semVer-like scheme (major is bumped for marketing reasons, minor is bumped when it requires a new db schema, tiny is bumped for releases that are db schema compatible).
It allows repeatable builds because it uses the "git height" as the increment source.
This is an implicitly updated value that is centrally coordinated, but isn't a separate system. If you have Git, you have a Git commit history, and hence an incrementing counter.
NBGV can stamp binary outputs such as .NET EXEs and DLLs, generates compile-time sources with version strings, works with Node.js projects as well, and integrates with Azure DevOps pipelines automatically.
That's the only version that should really matter. Release branches, if used, tend to be pretty stable in terms of git shenanigans.
The versions of dev branches don't really matter, and if it's a huge concern, you can simply bump the version in the NGBV config file to ensure that versions increase the way you want them to.
Not intentionally! But actually I think the concern is unwarranted because looking again it seems they don't include the hash for release versions, so if someone did force push master/main the artifact repository should reject it.
Main problem is it's not ordered. It works if your software is deployed imperatively in a CI pipeline, but doesn't work if some other system is going to pull it later.
I think this is a nice way to clarify the different use cases for version numbers:
- SemVer is a communication tool for when an author needs to tell a potential user what to expect from a new version.
- TrunkVer is an auditing/engineering tool for when you need to give a unique identifier to a version for technical reasons.
I think this page is a nice codification of a useful practice, but it does itself a disservice by positioning itself against SemVar and claiming to be a "drop-in" replacement.
It's a "drop-in" replacement in the sense that it's compatible with the format and with the rough semantics of SemVer. That is, if your libraries / packages all use SemVer, but the final executable / image uses TrunkVer, the latter does not need to be special-cased. TrunkVer gives a stream of "major versions" that's strictly increasing and all incompatible, and uses non-version fields to convey useful info. All SemVer-based tools will accept a TrunkVer value and do the right thing (that is, always prefer the newest build).
> but it does itself a disservice by positioning itself against SemVar
I didn't read it like that at all!
In what way is this „SemVer-compatible“ when you just ignore the „Major increment <=> breaking changes“ convention? It has 3 numbers separated by dots? This just increments major version every time a build is started, even though there might not be breaking changes.
Edit: When looking at the SemVer page: https://semver.org/#if-even-the-tiniest-backward-incompatibl...
The formal spec technically only tells you that you MUST increment Major for breaking changes, and not that you can’t do it every time, but the FAQ makes it clear what the spirit of the rule is. I can’t see how TrunkVer can be called SemVer compatible with this construction method.
In semver terms, I believe this translates to "every change might be breaking", which sounds right for trunk-based deployments.
from their FAQ:
"TrunkVer always defensively implies breaking changes between versions."
It sounds like a disaster. Trunk-based deployment does not imply such an extreme degree of instability, because all development may happen on other branches. I see what you're trying to say though. I think the real keyword is "continuous integration."
> It sounds like a disaster.
Why do you think so? It shouldn't be used for something like a library or an external API that other people rely on where communicating about breaking changes is actually important.
For something like a web application, I don't think it matters much. Do you know which version of Google Docs you're using? Do you care?
Saying it's semver compatible mostly means that you can use existing tools that work with semver and make assumptions about how version numbers can be sorted.
It’s semver compatible because it can be parsed, accepted and compared by any system that expects or requires a semver formatted version?
The whole point of this is that in trunk-based releases the version isn’t significant, so why not call each one breaking.
20241127214906.0.0 will be marked as incompatible with 20241127214907.0.0 by any such system that parses them.
Sure, but it does parse them and it does rightly understand that one is an newer version.
That’s… compatibility.
Newer is not always compatible. That's why SemVer looks like work to authors. They don't like to think about compatibility.
You’re misunderstanding, try re-reading the thread or other comments in the chain.
That's (in-)compatibility between versions, not compatibility between versioning schemes.
You're not technically wrong but using the 3 numbers this way is in fact going to create problems for people trying to use this info. It means that you can never know if any version is compatible with others, and even if they were you could not easily link it.
It’s not creating a new problem that didn’t already exist.
In many situations at work, trying to follow SemVer would be a technical solution to a non-technical problem.
You know who your users are. Before you make any breaking change, you already have cross-product team meetings with possible executive buy in.
In those scenarios, by time you assign a version number, everyone is already on the same page. The actual version number is meaningless and conveys no useful information. Spending any time on deciding the version creates unnecessary toil.
It is creating a problem that didn't exist because using this instead of SemVer eliminates the option to communicate meaningful compatibility information.
>You know who your users are. Before you make any breaking change, you already have cross-product team meetings with possible executive buy in.
Generally none of these things are true. You don't know your users or how they intend to use your product. The executives certainly don't care about version numbers.
There are some cases where nobody cares about version numbers, which mainly occur when there is one or a handful of consumers of a product and they are likewise committed to very frequent releases. This is not how most distributable libraries work. Furthermore, people care less about version numbers when the numbers are not correctly assigned in the first place. If you aren't using SemVer then it's just an increasing sequence for the most part.
This is not for libraries. This is for internal services that are continually released from the main branch of a repository.
I think you’ve deeply misunderstood the problem this is solving.
In short: What specific version tag is GitHub.com running right now? Even if you knew, is that version information meaningful?
well, yes, this is the only safe thing to do. The build system has no information what has changed since last build - maybe it was a complete interface rewrite - so it does the safe thing.
> A TrunkVer is syntactically compatible with SemVer, although it does not respect its semantic interpretation of the version number.
The document specifically disclaims semantic compatibility.
It would be somewhat more "compatible" with semver if it placed the timestamp in the MINOR or PATCH segment, rather than in the MAJOR:
I’ve been happily using date base version numbers in any user facing product (e.g apps) for a while now. It’s been great.
While semver makes great sense on paper, and even allows nifty little algebras in dependency declarations, it is been my experience that the delineations are not always as easy to decode and different team members can quibble over the exact realization of the boundaries.
Furthermore, it’s very much been my experience that semver changes, like all code comments, only communicate the intent of the developer and not always the reality. A minor roll may be anticipated as backwards compatible, until an unrealized use case pops up and makes the minor change very breaking.
semver is useful for libraries and other things that have a very clear programmer interface.
For most applications it's fairly pointless. There are often many "breaking changes" in any significant release, and there is no strong agreement at all on what a "breaking change" even is.
> Furthermore, it’s very much been my experience that semver changes, like all code comments, only communicate the intent of the developer and not always the reality.
This is the truth and the reason why SemVer is fundamentally wrong for almost all cases that people use it for. Fools with keyboards and big salaries hallucinate a contractual certainty where none exists.
If you understand that the "sem" in semver is specifically about semantics and not about anything else, and that an API includes its current semantics in the semver, then it makes sense.
The issues I've struck with other developers:
1. Defining the boundaries of the API
2. Defining the semantics of the API from the perspective of the user
The funny thing about trunkver being "compatible" with semver is that it is not semantically compatible, only format compatible.
You could (but not necessarily should) combine them by making the trunkver the "patch" part of semver.
In our work, the semver is kept separate from the build version. We use a build versioning of vYYYY-MM-DD[.hhh] where hhh is for a "hotfix" of a previously released version.
The version of the "next" release can be set (either in advance, or based on a sprint or just the current date).
It would be semver compatible if they used 0.DATE.0 or 0.0.DATE instead.
from semver spec:
4) Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.
The EBNF in the page does not match the textual description:
While I understand the point you're making, some of these don't seem like they should _technically_ be an issue in terms of whether a parser following the textual descriptions would work on the actual thing. Any parser written to accept an alphanumeric string should presumably accept a purely alphabetic one, and I'm pretty sure a "ref" in git doesn't just mean a hash but also refers to branches and tags, either of which could have a name in the format you describe. Given that the point of EBNF is to define grammar to a degree of precision and conciseness that textual descriptions can't match, I don't think it's a super big deal. From the perspective of building a parser from EBNF, the names of the tokens don't matter.
On the git part: the text only mentions "git commit checksum", not "branches and tags" -- and it couldn't, since these are not immutable nor are they restricted to hex characters.
My point above is that the EBNF defines "GIT_COMMIT_REF" to be the letter "g" and a _single_ hex character. So "GIT_COMMIT_REF" may be "g0", "g1", ... "g9", "gA", ... "gF", "ga", ..., "gf". That's it. Which obviously contradicts the text and the intention.
> don't seem like they should _technically_ be an issue
Sure, people can ignore the EBNF. But if you expect that, then why publish it at all? EBNF is specifically used to describe formats and get rid of ambiguities present in text description. Not being careful with it just undermines whole idea.
I'm not saying to ignore the EBNF; I'm saying to ignore the identifiers used in the EBNF. It doesn't matter that ALPHANUMERIC is alphabetic only because the identifier is just used as a shorthand for the tokens it represents. You could literally put anything down instead of ALPHANUMERIC and it would work the same, so the fact that the name isn't a perfectly precise description isn't a big deal.
No, it's the opposite problem.
For example the text talks about "ASCII alphanumerics [09-A-Za-z]", the relevant EBNF rule is called "ALPHANUMERIC", but its definition is only letters.
It's not the problem that it's called "ALPHANUMERIC" -- it's that it should describe alphanumerics and it doesn't.
A sequential build/release number would suffice in many cases.
If the thing you're shipping isn't meant to be a dependency for other projects, then semantic versioning doesn't really fit.
In trunkver though, using the timestamp of the build time is a little weird, since you could inadvertently end up building an earlier version of trunk at a later time.
Putting an identifier of the job that built the release in the version number also seems heavy for what could just be an entry in a log file for when you need those forensics.
Time is sequential. Otherwise, sequential build numbers are kind of hard to orchestrate in a distributed architecture. Not impossible. But it introduces complexities if you have many build machines.
I don't think semver compatibility is that relevant/meaningful here. Normally I'd also want the branch name as part of the version tag. We do that with our docker containers. Adding the timestamp at the beginning is a good idea as it helps sort things by recency. I might copy that. The CI build id is nice, but I typically don't archive these anyway. All this concatenated gets a bit long.
git describe gives you what you want.
It gives you the nearest tag, the number of commits from that tag and the git commit ID.
We don't use git tags for ordinary deploys. Every push to production gets deployed. And a timestamp is useful for sorting lists of container images.
What happens with build number is you end up going back to the CI system and looking up what change it actually built and when it happened. I can see the advantage of having all 3 in the build name, I have done similar in the past for continuously released server software where there is no need for versioning numbers although typically I too have shortened it to just the build number because we have the CI system to go into if we need to.
Generally agree with your points about how semver isn't really necessary. I suppose the benefit here would be that dep management tools like dependabot could automatically raise pull requests when a new version is released, which would be pretty cool. If only my peer engineers actually paid attention to dependency updates.
As an aside, instead of an auto incrementing build number I'd suggest the git sha since it's: 1. Already there and points to a specific version of the code in the repo 2. Globally unique 3. Can assist with reproducible builds (i.e. 6afed54 was acting weird, let's build it locally and take a look) 4. Gives you an easy diff target to dump "release notes". Just diff to the previous and dump the merge commit messages.
The problem with sequential build/release number is that you have to keep it in git (so you could increment), which results in a number of complications and annoyances.
Often the version string is baked somehow into the artifact. If it contains volatile data that is not functionally dependent on the source (the when and how) it prevents the build from being reproducible.
My opinion is that the pure semver should be part of the source and be baked in the artifact. Date and build metadata should be recorded close but separate from the artifact.
> Semver compatible
Right, just like if I were to write in english while only following the grammar rules, but without making any sense, it would be "english compatible" i guess.
It's called _semantic_ versioning, and trunkver loses the whole point of it.
The whole concept would have been better if it didn't even try to mention semver in the first place.
Versioning could also be determined from: 1. User-centric: Has --help changed? If not, it is minor bump. 2. Developer-centric: Will conflicts occur if a new commit is cherry-picked onto the prior release?
I like linear Git histories, but image if we could "widen" a linear history maximally - so all non-conflicting commits "branch out" and only merge when needed.
This is needed because people misunderstand the purpose of semver (IMNSHO).
Semver is about the semantics of the software (it's in the name), so it's entirely about that software's interface (whether to the programmer via API, other software, users).
It's not about the implementation (except perhaps the "patch" component). If you fix a bug that doesn't change the interface, then there's no bump to the semver.
"Trunkver" is about the implementation, but in a semver compatible format.
Another (simpler) versioning "standard" using calendar-based versioning: https://calver.org
What kills me with that website is that an example version string is nowhere to be found. The same thing almost plagues the TrunkVer page (unless you realize that you are supposed to ignore the newlines in that gray intro box), except at the very bottom you can see a dogfooded TrunkVer of the spec page itself.
If you want your thing to be popular, make sure someone dumb like me skimming the marketing blurp can quickly understand what the thing looks like in the wild.
I've been using something like this for the Unity game I'm working on where I need regular updates. However, I don't think it let me use 14 numbers in the major field. So I've stuck with something along the lines of <year>.<month>.<date>-<hours*60+minutes> to better saturate. It's nice to know there's a standard for this though.
I’m still bitter that PEP 440 didn’t win: https://peps.python.org/pep-0440/
It’s way better than semver and has all the metadata you may want.
Undoubtedly because semver has a nice website that immediately makes sense to everyone that reads it.
I can see using this if what you're building is at the end of the supply chain, and there is really less need to make the claims that SemVer does. Conversely, if you have downstream consumers, I can't imagine taking away the compatibility statements in SemVer.
It depends whether the consumers have any choice about whether to receive the update. If what you're versioning is a web app, they're getting the update no matter whether they think current and next are compatible or not. And if they aren't compatible in a way that's going to cause problems, you need to be communicating richer information to them than a change in a version number anyway.
What if the CI vendor decides to use the same for its ids? Then you have even longer version numbers.
And if CI vendors aren't expected to adopt this, why expect a lot of devs to?
On my computer, the CI version ID wraps, because between the other parts of the version and the padding, there isn't enough space. I think that says something about the length of the version identifier.
> If the source reference is a git commit checksum, it may be truncated to 7 characters (--short)
Doesn't the length of shortened git hashes depend on the size of the repo (whether or not shortened hashes of a given length collide)?
This breaks efficient dependencies resolution. SemVer is called that because versions carry semantic meaning, TrunkVer appears no better than using UUIDs for each version name. You know nothing of the relation between two versions in this scheme, other than which came first.
Here's the thing about versions: they are never "complete", Because you never have just one version.
Whatever you are looking at is most likely an amalgam of many different things, which all have their own versions. Your one perfect holy version number does not tell you those versions, so you have to look them up at some point (you did save the versions of all your dependencies and pack them into a BOM, right?).
This trunk version similarly does not encode all the information you need. And what is it going to be used for? A python package? Every python package? A docker container? What about all the versions of stuff in that container? What about the helm chart that will ship this container, what's it's version? What about the version of all your helm charts that have been tested as working in stage before shipping them to prod?
If you're going to have a "generic incremented trunk version", just make it a plain-old continuously incrementing integer (or hex, or whatever) with no semver. Because you're going to have to look up more information about what's inside it later anyway, and everything's going to have its own version as you modify individual items.
Packing all this extra information in is actually counter-productive, because it's now much longer and more complex (which makes it harder to just compare a list side by side), yet it doesn't give you enough info. Ok, datestamp; where's the timezone? Ok, git sha; which repo (and has history been rewritten, or the files moved to a different repo)? Ok, CI build number; which build system (if you have multiple, or you moved from one to another)?
Maybe some of it you can intuit, but eventually you'll wish it was different again. Might as well just make it a plain integer you can pass to a script that dumps out everything related to it.
Semver's primary use case is not identifying what's inside or where it came from. The numbers are little more than a simple incrementor, and the use case is just a user who wants to know how afraid they should be. It's intended solely to communicate how likely this thing is to fuck your shit up. If it's a major version change, here be dragons. If it's minor, be cautious. If it's a patch, it should be harmless. Semver is a threat indicator. And it's easy to work with because it's so simple; comparing versions is easy. Comparing a wall of these TrunkVers will be like staring at The Matrix code.
(SemVer's supposed to tell you what dependencies it can work with (>major, >major.minor, etc), but you still need the entire dependency DAG to have a pair of package name and version in order to make sense of it; you could do the exact same thing with a list of names and simple integers (foo >= 23456, foo<1234); now imagine with this TrunkVer (foo >= 20241127214906.0.0-g1f8292a-12058740477-1)...)
This is pretty much what we do already. Every docker image we push to the registry has a version like trunkVer (with only the first 2 components). The version is also put inside the image (in a file named /TAG) and is put in:
* first log line
* last log line
* response headers
* on some about page of the web app
Difference with trunkVer: we do not have the last component (the CI bit), the first bit we use a more semVer-like scheme (major is bumped for marketing reasons, minor is bumped when it requires a new db schema, tiny is bumped for releases that are db schema compatible).
I much prefer Nerdbank Git Versioning (NBGV): https://github.com/dotnet/Nerdbank.GitVersioning
It allows repeatable builds because it uses the "git height" as the increment source.
This is an implicitly updated value that is centrally coordinated, but isn't a separate system. If you have Git, you have a Git commit history, and hence an incrementing counter.
NBGV can stamp binary outputs such as .NET EXEs and DLLs, generates compile-time sources with version strings, works with Node.js projects as well, and integrates with Azure DevOps pipelines automatically.
I have been using MinVer for dotnet projects, which is similar but a little easier (IMO) to work with since its all based on tags.
What if you rebase/force push? Seems dangerous to rely on "protected branches" and the like to avoid version clashes.
On master/main? What are you, a savage?
That's the only version that should really matter. Release branches, if used, tend to be pretty stable in terms of git shenanigans.
The versions of dev branches don't really matter, and if it's a huge concern, you can simply bump the version in the NGBV config file to ensure that versions increase the way you want them to.
Not intentionally! But actually I think the concern is unwarranted because looking again it seems they don't include the hash for release versions, so if someone did force push master/main the artifact repository should reject it.
Git commit sha produces a good enough version for most software.
Main problem is it's not ordered. It works if your software is deployed imperatively in a CI pipeline, but doesn't work if some other system is going to pull it later.
Add a metalayer to turn version names into memorable word phrases imo lol.
Great, now sell this to your marketing department
And the best part is you can completely disregard the need to maintain backwards compatibility, because every build implies a breaking change! /s
Is what?