[GH-ISSUE #540] Question about prelease specification #3112

New Issue

GiteaMirror · 2026-04-25T17:24:40-05:00

GiteaMirror commented

2026-04-25 17:24:40 -05:00

Originally created by @P1ng-W1n on GitHub (Nov 15, 2019).
Original GitHub issue: https://github.com/semver/semver/issues/540

According to the semver rules , section 9:

A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphen [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes.

Discussed this topic over https://github.com/python-semver/python-semver/issues/194, and we concluded that the current specification is clear when it comes to numbers, but it's a little bit misleading to strings (that could also start with a numeric zero).
Considering that prerelease versions are interpreted as strings, so I don't see the reasoning behind this rule

Could someone please help to clarify this?

Originally created by @P1ng-W1n on GitHub (Nov 15, 2019). Original GitHub issue: https://github.com/semver/semver/issues/540 According to the semver [rules ](urlhttps://semver.org), section 9: > A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphen [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Discussed this topic over https://github.com/python-semver/python-semver/issues/194, and we concluded that the current specification is clear when it comes to numbers, but it's a little bit misleading to strings (that could also start with a numeric zero). Considering that prerelease versions are interpreted as strings, so I don't see the reasoning behind this rule Could someone please help to clarify this?

GiteaMirror closed this issue

2026-04-25 17:24:40 -05:00

GiteaMirror commented

2026-04-25 17:24:41 -05:00

@wizzwizz4 commented on GitHub (Nov 15, 2019):

It means that logically numeric values (values that count up) mustn't have leading zeroes, but accidentally numeric values (e.g. the spyware release, 007) that should just be treated as arbitrary text are fine.

@wizzwizz4 commented on GitHub (Nov 15, 2019): It means that _logically_ numeric values (values that count up) mustn't have leading zeroes, but _accidentally_ numeric values (e.g. the spyware release, `007`) that should just be treated as arbitrary text are fine.

GiteaMirror commented

2026-04-25 17:24:41 -05:00

@P1ng-W1n commented on GitHub (Nov 15, 2019):

I see.
If my understanding is correct, then this would mean that 0.1.0-0abcdef is be considered a valid Semver version in that case. Is that actually being the case?

@P1ng-W1n commented on GitHub (Nov 15, 2019): I see. If my understanding is correct, then this would mean that 0.1.0-0abcdef is be considered a valid Semver version in that case. Is that actually being the case?

GiteaMirror commented

2026-04-25 17:24:42 -05:00

@runeimp commented on GitHub (Nov 16, 2019):

Yes-ish. When they say numeric identifiers the thought is (as I understand it) decimal values not hexadecimal, octal, or odd strings. The point is that systems that parse SemVer strings need to be able to sort these strings in a reasonably and consistent way. A decimal number should not have leading zeros because that could be confused as an octal number or possibly hex value i.e.; octal 052 for the decimal value 42 or hex 0xff for decimal 255. 0abcdef would just be an odd string though I'd guess it's intended as hex. But as there is no x after the 0 as used in classic hex notation it's impossible to be certain that it should be interpreted as hex. That effects sorting and you could easily end up intending it to be hex value and when parsed by another system is sorted as as string. So if you intend that to be hex then you should make it obviously hex if you intend that. If it's just a string you're probably fine. But a 3rd party with a more loose interpretation of what should be viewed as a hex value might still sort it as such which would likely change the sorting order. So I'd avoid it unless you absolutely, positively, swear on your great grandmothers grave, that you will never, ever let a third party have need of access to your semver number. 👼

@runeimp commented on GitHub (Nov 16, 2019): Yes-ish. When they say numeric identifiers the thought is (as I understand it) decimal values not hexadecimal, octal, or odd strings. The point is that systems that parse SemVer strings need to be able to sort these strings in a reasonably and consistent way. A decimal number should not have leading zeros because that could be confused as an octal number or possibly hex value i.e.; octal `052` for the decimal value `42` or hex `0xff` for decimal `255`. `0abcdef` would just be an odd string though I'd guess it's intended as hex. But as there is no `x` after the `0` as used in classic hex notation it's impossible to be certain that it should be interpreted as hex. That effects sorting and you could easily end up intending it to be hex value and when parsed by another system is sorted as as string. So if you intend that to be hex then you should make it obviously hex if you intend that. If it's just a string you're probably fine. But a 3rd party with a more loose interpretation of what should be viewed as a hex value might still sort it as such which would likely change the sorting order. So I'd avoid it unless you absolutely, positively, swear on your great grandmothers grave, that you will never, ever let a third party have need of access to your semver number. 👼

GiteaMirror commented

2026-04-25 17:24:42 -05:00

@P1ng-W1n commented on GitHub (Nov 16, 2019):

Hi @runeimp

The reason I raised this issue is because apparently different clients interpret that differently :)
To give some context 0abcdef in my scenario is a git hash.

According to the semver.org provided regexp examples that should pass the semver versioning:

$ echo '1.0.0-0fe6b123' |grep -P '^(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)(?:-(?P<prerelease>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?P<buildmetadata>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$'
1.0.0-0fe6b123
$ echo '1.0.0-0fe6b123' |grep -P '^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$'
1.0.0-0fe6b123

However, the situation is not that clear when it comes to python clients:

>>> import semver
>>> semver.parse('1.0.0-0fe6b123')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/ezlukga/.local/lib/python3.6/site-packages/semver.py", line 72, in parse
    raise ValueError('%s is not valid SemVer string' % version)
ValueError: 1.0.0-0fe6b123 is not valid SemVer string

>>> import semantic_version
>>> semantic_version.validate('1.0.0-0fe6b123')
True

According to python-semver's interpretation of the Backus–Naur Form Grammar for Valid SemVer Versions the above semver should not be valid, but according to your explanation it should be.
This also means (at least in my understanding) that the current definition could be read incorrectly, and further clarification might be required in the phrasing.

@P1ng-W1n commented on GitHub (Nov 16, 2019): Hi @runeimp The reason I raised this issue is because apparently different clients interpret that differently :) To give some context 0abcdef in my scenario is a git hash. According to the semver.org provided regexp examples that should pass the semver versioning: ``` $ echo '1.0.0-0fe6b123' |grep -P '^(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)(?:-(?P<prerelease>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?P<buildmetadata>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$' 1.0.0-0fe6b123 $ echo '1.0.0-0fe6b123' |grep -P '^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$' 1.0.0-0fe6b123 ``` However, the situation is not that clear when it comes to python clients: ``` >>> import semver >>> semver.parse('1.0.0-0fe6b123') Traceback (most recent call last): File "<stdin>", line 1, in <module> File "/home/ezlukga/.local/lib/python3.6/site-packages/semver.py", line 72, in parse raise ValueError('%s is not valid SemVer string' % version) ValueError: 1.0.0-0fe6b123 is not valid SemVer string >>> import semantic_version >>> semantic_version.validate('1.0.0-0fe6b123') True ``` According to [python-semver's interpretation](https://github.com/python-semver/python-semver/issues/194#issuecomment-554369564) of the [Backus–Naur Form Grammar for Valid SemVer Versions](https://semver.org/#backusnaur-form-grammar-for-valid-semver-versions) the above semver should not be valid, but according to your explanation it should be. This also means (at least in my understanding) that the current definition could be read incorrectly, and further clarification might be required in the phrasing.

GiteaMirror commented

2026-04-25 17:24:43 -05:00

@runeimp commented on GitHub (Nov 21, 2019):

@P1ng-W1n Yes, with the spec changing a bit over time your almost guaranteed to run into semver tools that are written against a different specification than what you may be expecting. Whether you expect the latest (ever changing over time), SemVer 1.0.0, etc. Reviewing the BNF for SemVer 2.0.0 and the RegEx I believe the Python module is incorrect. At least in regards to SemVer 2.0.0. A slightly earlier version (RC1, RC2, etc.) may have not allowed for it. But the SemVer 2.0.0 regex and BNF both support alphanumeric string with or without a leading zero in both of their list of supported options. Only purely numeric values should not start with a leading zero according to spec item 9.

@runeimp commented on GitHub (Nov 21, 2019): @P1ng-W1n Yes, with the spec changing a bit over time your almost guaranteed to run into semver tools that are written against a different specification than what you may be expecting. Whether you expect the latest (ever changing over time), SemVer 1.0.0, etc. Reviewing the [BNF for SemVer 2.0.0](https://semver.org/spec/v2.0.0.html#backusnaur-form-grammar-for-valid-semver-versions) and the [RegEx](https://semver.org/spec/v2.0.0.html#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string) I believe the Python module is incorrect. At least in regards to SemVer 2.0.0. A slightly earlier version (RC1, RC2, etc.) may have not allowed for it. But the SemVer 2.0.0 regex and BNF both support alphanumeric string with or without a leading zero in both of their list of supported options. Only purely numeric values should not start with a leading zero according to [spec item 9](https://semver.org/spec/v2.0.0.html#spec-item-9).

GiteaMirror commented

2026-04-25 17:24:43 -05:00

@jwdonahue commented on GitHub (Nov 25, 2019):

The semver spec says nothing about hex or octal numbers in any field. The only allowed numeric symbols are [0-9]. Neither the Backus-Naur or the regex interpret hex or octal fields. So -0fe6b123 would be interpreted as alpanumeric, where only ASCII sort order would apply.

@jwdonahue commented on GitHub (Nov 25, 2019): The semver spec says nothing about hex or octal numbers in any field. The only allowed numeric symbols are [0-9]. Neither the Backus-Naur or the regex interpret hex or octal fields. So `-0fe6b123` would be interpreted as alpanumeric, where only ASCII sort order would apply.

GiteaMirror commented

2026-04-25 17:24:44 -05:00

@jwdonahue commented on GitHub (Nov 25, 2019):

There are more incorrect regex's in use in the world today than there are correct ones. What a specific implementation says about a particular version string with regard to SemVer status, is not necessarily correct. That's why we spent the better part of a year, developing and vetting the regex's provided in the latest FAQ.

@jwdonahue commented on GitHub (Nov 25, 2019): There are more incorrect regex's in use in the world today than there are correct ones. What a specific implementation says about a particular version string with regard to SemVer status, is not necessarily correct. That's why we spent the better part of a year, developing and vetting the regex's provided in the latest FAQ.

GiteaMirror commented

2026-04-25 17:24:44 -05:00

@jwdonahue commented on GitHub (Nov 25, 2019):

To put it another way, the presence of any alpha characters [A-Za-z] in the field, make it an alphanumeric field, therefore the no leading zero rule doesn't apply. The spec clearly states

Numeric identifiers MUST NOT include leading zeroes

Numeric identifiers are [0-9]. Whoever wrote that python parser, got it wrong.

@jwdonahue commented on GitHub (Nov 25, 2019): To put it another way, the presence of any alpha characters [A-Za-z] in the field, make it an alphanumeric field, therefore the _no leading zero rule_ doesn't apply. The spec clearly states > Numeric identifiers MUST NOT include leading zeroes Numeric identifiers are [0-9]. Whoever wrote that python parser, got it wrong.

GiteaMirror commented

2026-04-25 17:24:45 -05:00

@jwdonahue commented on GitHub (Nov 25, 2019):

I would not embed git hashes in the prerelease tag. While they are the results of a numeric algorithm, they are highly randomized, therefore sorting them as alphnum's is pointless and may in fact be harmful. Prerelease tags are included in the sorting rules. Randomized data belongs in the build-meta tag, not the prerelease tag.

@jwdonahue commented on GitHub (Nov 25, 2019): I would not embed git hashes in the prerelease tag. While they are the results of a numeric algorithm, they are highly randomized, therefore sorting them as alphnum's is pointless and may in fact be harmful. Prerelease tags are included in the sorting rules. Randomized data belongs in the build-meta tag, not the prerelease tag.

GiteaMirror commented

2026-04-25 17:24:45 -05:00

@jwdonahue commented on GitHub (Jan 15, 2020):

@P1ng-W1n, unless you have further questions, or intend to issue a related PR, please close this issue at your earliest possible convenience.

@jwdonahue commented on GitHub (Jan 15, 2020): @P1ng-W1n, unless you have further questions, or intend to issue a related PR, please close this issue at your earliest possible convenience.

GiteaMirror commented

2026-04-25 17:24:46 -05:00

@P1ng-W1n commented on GitHub (Jan 21, 2020):

Hi @jwdonahue

Sorry for the late response. Yes, the ticket can be closed, but before that I would like to share part of my investigation with others, who might think about including a git hash in their release versioning schema (feel free to use this commit as a reference for others):

So as described above, git hashes could start with a leading zero, which could cause "misunderstanding" depending of the semver library used (and whether that's interpreted as a numerical or to an alphanumerical value).

One could argue if that should be accepted or not, however one has to realize that a git hash could actually contain only numerical values, and could start with a leading zero, such as 0123456...
In that case the hash should be interpreted as numerical, meaning that it would go against the
current semver directives.

TLDR: Don't use a git hash as part of your semver versioning.. Or if you have to, add a prefix to it (sha0123456...)

@P1ng-W1n commented on GitHub (Jan 21, 2020): Hi @jwdonahue Sorry for the late response. Yes, the ticket can be closed, but before that I would like to share part of my investigation with others, who might think about including a git hash in their release versioning schema (feel free to use this commit as a reference for others): So as described above, git hashes could start with a leading zero, which could cause "misunderstanding" depending of the semver library used (and whether that's interpreted as a numerical or to an alphanumerical value). One could argue if that should be accepted or not, however one has to realize that a git hash could actually contain only numerical values, and could start with a leading zero, such as 0123456... In that case the hash should be interpreted as numerical, meaning that it would go against the current semver directives. TLDR: Don't use a git hash as part of your semver versioning.. Or if you have to, add a prefix to it (sha0123456...)

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#3112