Equality and build metadata #688

New Issue

GiteaMirror · 2026-02-17T12:16:42-06:00

GiteaMirror commented

2026-02-17 12:16:42 -06:00

Originally created by @edouardhue on GitHub (Jul 4, 2025).

When build metadata was added to SemVer, its existence was justified with such examples (citing #77):

For example, folks might use it for cache busting, layering custom behavior on top of SemVer, bookkeeping to tie when and where a build was made, etc.

SemVer 2.0 also states this at chapters 10 and 11:

"Precedence refers to how versions are compared to each other when ordered."
"Build metadata MUST be ignored when determining version precedence."

The spec does not say anything about equality out of precedence calculation. Build metadata must be ignored when determining precedence, but what about determining equality? Should 1.0.0+cafe be equal to 1.0.0+beef? If yes, what about the ability of performing cache busting and such?

Most tools today seem to consider that what is said about precedence also holds for equality, and as just ignore build metadata (as hinted in Masterminds/semver#271). In Helm or NPM, expressing a dependency to a version such as 1.0.0+cafe is just the same as 1.0.0. If the repository contains several builds for the given version, the actual resolved dependency is at best specific to the tool and well-documented, at worse unpredictable. One cannot expect consistent behaviour between tools.

It is in many situations useful to be able to reference a specific build number for a given version, especially during development and testing. One does not want to increment the version or pre-release version just for the sake of testing a different build.

I would like to see added to the spec a chapter about equality so that SemVer-compatible dependency management tools operate in a consistent way. Such rules would state that two versions are equal when they have the same component set and each of their component are equal, from major to build. E.g:

1.0.0+cafe == 1.0.0 is false: if build metadata is defined on the left-hand, don't ignore it and perform an exact match;
1.0.0+cafe == 1.0.0+cafe is true: obviously;
1.0.0+cafe == 1.0.0+beef is false: two versions equal but for build metadata are not equal;
1.0.0 == 1.0.0 remains true.

It remains up to the tools to provide other comparison operators or ranges, in the likes of NPM's ^ and ~, for which precedence rules take over equality rules. For backward compatibility, it could also be made such that, when expressing a dependency without indicating a build number, precedence rules apply, but when the build number is expressed, strict equality rules apply.

Originally created by @edouardhue on GitHub (Jul 4, 2025). When build metadata was added to SemVer, its existence was justified with such examples (citing #77): > For example, folks might use it for cache busting, layering custom behavior on top of SemVer, bookkeeping to tie when and where a build was made, etc. SemVer 2.0 also states this at chapters 10 and 11: * "Precedence refers to how versions are compared to each other when ordered." * "Build metadata MUST be ignored when determining version precedence." The spec does not say anything about equality out of precedence calculation. Build metadata must be ignored when determining precedence, but what about determining equality? Should `1.0.0+cafe` be equal to `1.0.0+beef`? If yes, what about the ability of performing cache busting and such? Most tools today seem to consider that what is said about precedence also holds for equality, and as just ignore build metadata (as hinted in Masterminds/semver#271). In Helm or NPM, expressing a dependency to a version such as `1.0.0+cafe` is just the same as `1.0.0`. If the repository contains several builds for the given version, the actual resolved dependency is at best specific to the tool and well-documented, at worse unpredictable. One cannot expect consistent behaviour between tools. It is in many situations useful to be able to reference a specific build number for a given version, especially during development and testing. One does not want to increment the version or pre-release version just for the sake of testing a different build. I would like to see added to the spec a chapter about equality so that SemVer-compatible dependency management tools operate in a consistent way. Such rules would state that two versions are equal when they have the same component set and each of their component are equal, from major to build. E.g: * `1.0.0+cafe == 1.0.0` is `false`: if build metadata is defined on the left-hand, don't ignore it and perform an exact match; * `1.0.0+cafe == 1.0.0+cafe` is `true`: obviously; * `1.0.0+cafe == 1.0.0+beef` is `false`: two versions equal but for build metadata are not equal; * `1.0.0 == 1.0.0` remains `true`. It remains up to the tools to provide other comparison operators or ranges, in the likes of NPM's `^` and `~`, for which precedence rules take over equality rules. For backward compatibility, it could also be made such that, when expressing a dependency without indicating a build number, precedence rules apply, but when the build number is expressed, strict equality rules apply.

GiteaMirror commented

2026-02-17 12:16:43 -06:00

@ljharb commented on GitHub (Aug 13, 2025):

equality is just a full comparison tho - no two different semver strings are equal. npm certainly elides the build metadata as much as it can, and treats them the same, but that's because npm predates build metadata and doing so was the least turbulent path forward.

@ljharb commented on GitHub (Aug 13, 2025): equality is just a full comparison tho - no two different semver strings are equal. npm certainly elides the build metadata as much as it can, and treats them the same, but that's because npm predates build metadata and doing so was the least turbulent path forward.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#688