The Pre-Release Dash should not be in v1.0.0

[theory]

This change somehow made it into the 1.0.0 spec. That doesn't seem quite right. I should think that this commit would be considered the last in v1.0.0. Am I mistaken? Because otherwise there are three different versions to recognize:

• v1.0.0 which disallows a dash between the patch version and the pre-release version.
• v1.0.0 which requires a dash between the patch version and the pre-release version.
• v2.0.0 which requires the dash and dotted integers.

This makes it difficult to write a parer to properly handle all the cases.

[haacked]

Hi @theory, I'm not sure I understand the question. In your bulleted list you mention v1.0.0 twice. What specifically are you concerned about?

[theory]

v1.0.0 was changed in this commit to require the dash. For a long time before that (years?), v1.0.0 required no dash (indeed, it forbade it). So it changed the spec without changing the version. I wrote a couple of parsers back before that commit and now folks are running into the fact that they forbid the dash even though the spec has since been changed to require the dash. This clouds the definition of v1.0.0, IMO.

I think that either 1.0.0 should not require the dash, or v1.1.0 should be released requiring the dash. I prefer the former, but given that the change was made 10 months ago, the latter might make more sense.

[haacked]

@theory That section only applies to "pre-release" versions. For example, if you want to denote that your version is an alpha release, you must use the dash. 1.0.0-alpha. But once your library is stable, you can remove the pre-release designation: 1.0.0. A stable release must not have a dash.

Does that make sense?

[theory]

Yeah, I understand that. The point is that the dash used to not be required before the prelease version, but that commit added that requirement -- without changing the version of the spec itself.

In other words, I wrote parsers against v1.0..0 of the spec, and the spec then changed so that my parsers now fail, even though the spec still claims to be v1.0.0.

[haacked]

Ah! I see! Well that unfortunately wasn't a stable version of 1.0.0. Unfortunately, it's not very clear by looking at just that file. As you can see in this later commit, the version of SemVer itself was made more clear: b8f12d7

So in summary: in the stable 1.0.0 the dash is required and that's never changed since 1.0.0 has been released. The changes the version spec happened in a pre-release version of SemVer. Sorry for the confusion!

[theory]

b8f12d7 Went from v1.0.0 to the lower version v1.0.0-rc~1. You can see that, because of that error, the spec was later changed to v2.0.0 in this commit. It had been published as v1.0.0 for a long time before the semver project was forked from semver.org.

[haacked]

Maybe @mojombo can shed some light on this. My theory is that while the text of the file says 1.0.0, it wasn't actually 1.0.0. I know that's confusing, but it's not unlike saying that it's the beta draft of the 1.0.0 spec. You don't want to change the text of the spec for each pre-release version update. However, I would have expected something external to the spec would identify what version it actually was.

I vaguely remember there being some indicator because when we implemented the version scheme in NuGet, we knew it was an RC at the time and not the final spec. I don't recall how we knew other than I think we asked.

[theory]

See @mojombo's comment here.

[haacked]

Thanks! Well that does leave us in a conundrum. 1.0.0 stable has been out for some time now and I imagine even more software has been written that parses that variant of 1.0.0 than the version that disallows the dash.

I don't think it makes sense to try and change 1.0.0 at this point as that ship has sailed and only compounds the problem.

So are you proposing that 2.0 allow cases without the dash?

[theory]

No, I like the dash. I wish I had noticed this ten months ago. I think what makes sense, really, is to revert 1.0.0 to disallow the dash, but release a 1.1.0 that requires it. That way, older parsers can say the adhere to v1.0.0, and those that read the spec in the last ten months can say they adhere to v1.1.0. (Though how we let people know such a thing has happened I'm not sure).

[haacked]

Yeah, that is tricky. Hmmm, here's what I'm thinking.

For the sake of discussion, let's distinguish the initial 1.0.0 as ~1.0.0 to avoid confusion. And I'll use 1.0.0 to refer to the current 1.0.0.

As I understand it, some software implemented support for ~1.0.0. But given the amount of time that 1.0.0 has been out, I'd venture to guess much more software has implemented support for 1.0.0.

If we made the change you suggest so that 1.0.0 becomes 1.1.0 and ~1.0.0 becomes 1.0.0, this would "fix" a few parsers but would break nearly every other SemVer parser that claims to parse 1.0.0. They'd have to immediately claim to only support 1.1.0 (and above) and could not claim to support for 1.0.0. That seems like a lot to ask of everybody.

The alternative is to consider ~1.0.0 a bug in the spec that was corrected by 1.0.0. So it's fine for most software to only support 1.0.0. The few pieces of software that supported the ~1.0.0 syntax can continue doing so as an error correction mechanism.

In practice, this is pretty much the same thing as your plan, but with different labels. So other than making this change:

• 1.0.0 becomes 1.1.0
• ~1.0.0 becomes 1.0.0

I propose we do this:

• 1.0.0 stays 1.0.0
• ~1.0.0 is referred to as 1.0.0-beta

That way, all existing parsers can claim 1.0.0 support. And a select few can claim 1.0.0-beta support as well.

I know it's not pretty, but the only pretty solution would be to get a time machine and prevent this from happening. But if I had a time machine, I'd probably go back and give my younger self a sports almanac and forget to handle this. :)

What do you think?

[theory]

I could get on board with that, especially if the 1.0.0-beta you propose (1.0.0beta?) was published somewhere that older parsers could point at it, at least until they can be updated.

[haacked]

Cool! I'll confer with @mojombo to figure out exactly how we should handle it. I assume we'd want to point this version to this commit (semver/semver.org@a16c419), right?

[theory]

Yeah, that looks right to me. Thanks.

[theory]

BTW, thanks @haacked, for getting back to me so promptly and engaging in a productive discussion. Much appreciated.

[haacked]

No problem! BTW, I'm still planning to do this. I've just been busy with so much other stuff going on. I haven't forgotten!

[theory]

In the meantime, I've released new versions of semver PostgreSQL extnesion and the SemVer Perl module to support the hyphen, though they both will parse SemVers without the hyphen.

[haacked]

Hi @theory I haven't forgotten about this. Just been real busy. BTW, I'm going to close this an open an issue at https://github.com/mojombo/semver.org where this really belongs.

Even better would be if you wouldn't mind submitting a PR of how you think the website should be updated. 😄 That'd make it easier to discuss and update the site.

[haacked]

Opened semver/semver.org#52 so I can close this.

[theory]

Man, so confused. Just trying to get things straight:

• semver/semver.org@a16c419, dated March 27, 2011, is the last v1.0.0 change on semver.org (maybe should be tagged v1.0.0-beta1?)
• 38db63f, dated June 8, 2011, is tagged v1.0.0-beta1, thanks to The Pre-Release Dash should not be in v1.0.0 #49 (this issue).
• 05a00df, dated June 19, 2011, adds the hyphen between the patch and prerelease versions
• ec80195, dated September 6, 2011, is tagged v1.0.0
• b8f12d7, dated November 19, 2011, changes the version to v1.0.0-rc~1
• ec092b7, dated November 24, 2011, changes the version to 1.0.0-rc.1, which looks more like the eventual 2.0.0 prerelease version format.
• semver/semver.org@9906c3f does the same for semver.og on November 26, 2011.
• 24eda4f finally increments the version to 2.0.0-rc.1 on December 7, 2011, noting that 1.0.0 had already been released.
• semver/semver.org@79343bf does the same for semver.org on Dec 22, 2011.

I was confused as to why the version was decreased in b8f12d7 from v1.0.0 to v1.0.0-rc~1 after the tagged v1.0.0, but 24eda4f makes it clear that was a mistake.

So I think all the tags are in the right places. This note is more to spell out where things changed, for my own reference and sanity.