Resetting of pre-release and build versions...

[zafarkhaja]

According to the Specification, patch version must be reset to 0 when minor version is incremented and both patch and minor versions must be reset to 0 when major version is incremented. However, it doesn't specify the behavior of pre-release and build versions when the associated normal version is incremented. Supposedly, they shouldn't remain the same, and, if so, it should be explicitly stated in the Specification.

[haacked]

I'm not sure I agree. You might have multiple versions of a pre-release.

[Tieske]

Prerelease should be left out, imo you cannot determine anything regarding compatibility on a prerelease version. Only once released the final version is set and semver tells you what you can expect.

See #28 and #30

[haacked]

@Tieske yep. So I think we're agreeing there's nothing to do here, right?

[zafarkhaja]

Hold on, guys! :) Did I get You right? The normal version should not (is not supposed to) be incremented while it's at the development level, i.e. has some sort of pre-release or build version. Even if I'm partially/completely wrong shouldn't it (the right thing) be somehow mentioned in the Specification to avoid the ambiguity?

[Tieske]

Suppose we have 1.0.0
Now we work on a new update, backward compatible; 1.1.0-beta1 (intended to be released as 1.1.0)
Then we find out that the requested features cannot be done with backward compatibility, so we must bump major, final product gets released as 2.0.0

So when working on a next release, you define a prerelease tag, attached to the intended version. But only the final release version (2.0.0 in the example) really tells you what to expect. See the other issues I referenced above.

Hence also my remark that pre-releases should be left out in any compatibility comparison. You may assume that there will be no major changes between RC1 and RC2, but the spec is not about assumptions, it is supposed to be a guarantee.

[haacked]

@zafarkhaja forgive me for my lack of reading comprehension, but could you provide a concrete example (make up a version number scenario) of a transition that you'd expect should not be allowed that the spec allows.

It's hard to speak of abstractions. A clear example like @Tieske provides is very helpful.

@Tieske so if I understand you correctly, in your scenario you might have the following version sequence.

• 1.1.0-beta1
• 2.0.0-beta2
• 2.0.0

And that should be fine. We shouldn't have to reset the prerelease part. In fact, what does it even mean to reset that part, right? A prerelease string can be any alphanumeric string.

[Tieske]

@haacked

what does it even mean to reset that part, right?

indeed nothing.
It could be even worse;

• 1.1.0-beta1 in the version we find out that we need to break stuff to implement the feature requested, so major bump
• 2.0.0-beta2 so the feature is now in, but is deemed impractical. That one feature breaks, while the other X number of features where compatible, so we decide to drop the feature again.
• 1.1.0-beta3 is this where we are now? because we dropped it, we are now backward compatible again.

This gets awkward, so one should never assume any compatibility on any pre-release version. Compatibility is the sole property of major/minor/patch versions according to semver, pre-release and build numbers do not add anything to that equasion. Build numbers are harmless in determining compatibility, so you can ignore them when present. Pre-release versions might contain unexpected changes (hence pre-release), so if a pre-release tag is present, don't even start to determine compatibility with other API versions.
Anything containing a pre-release tag should be considered a 0.y.z version;

5.Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable.

[zafarkhaja]

@haacked I wasn't suggesting that there's something in the Specification that I thought shouldn't be allowed. Instead, I suggested that there is something that is not in the Specification and therefore should be specified.

@Tieske I wasn't talking about comparisons either, at least not in this issue. What I was talking about is the behavior of all versions when one of the normal version numbers is incremented. Well, it's not really "resetting" as I have called it in the title, but I think I made it clear in the description, or not...

Let me show what I mean in terms of Your example.

• 1.1.0-beta1 (Has a pre-release version)
• 2.0.0-beta2 (The pre-release version is NOT reset like the minor and patch versions BUT "incremented")
• 2.0.0 (Well, here in the final release version it's gone. No problem with it)
• 1.1.0-beta3 (Or, if we are back the pre-release version is "incremented" again)

Here's what I propose. It should be specified in the Specification that while minor and patch versions get reset when the normal version is bumped, the pre-release and build (?) versions are incremented.

I believe that the Specification should be as specific as possible because otherwise it would be hard to create a reference implementation due to ambiguities.

@Tieske as to the references You provided, I must say that I absolutely agree with You and wonder why hasn't it been pulled yet?

PS. Should I change the title of the issue?

[zafarkhaja]

I would like to renew the discussion. What does everybody think about this? Should it be specified in the Specification what to do with pre-release and build versions when normal version is incremented?

[softprops]

bump Any progress on this?

[icylace]

If we look at the wording of #6, #7, #8, and #9 of the Specification they do not make an explicit distinction that they refer to finalized releases. Though, I believe that is the assumption. So, technically speaking it seems that the scenario posed by @Tieske would be in violation of #9 because the major version number gets decremented.

I believe the Specification should do three things:

1. Explicitly state the types of release #6, #7, #8, and #9 refer to. Presumably it would be finalized production releases.
2. Prevent the major, minor, and patch numbers of pre-release versions from changing once after they have been set with the initial pre-release version for the relevant development cycle. The idea here is that for there to exist both a 1.1.0-beta1 and a 2.0.0-beta2 the implicit assumption is that at the very least there also exists a 1.1.0 and a 2.0.0-beta1. This of course would lead to confusion if those versions do not exist.
3. Introduce an optional convention that allows pre-release versions to express a potential alternate final normal version in order to communicate the presence of significant changes that initially occur in the middle of development. Perhaps double underscores would work (or double hyphens if underscores are too big of a change). Two underscores are used instead of one in order to promote readability.

So, given the aforementioned scenario:

• 1.1.0-beta1
• 2.0.0-beta2
• 1.1.0-beta3

My suggested changes would yield:

• 1.1.0-beta1
• 1.1.0-beta2__2.0.0
• 1.1.0-beta3

Let's extend the example to see how this convention works when we include build numbers.

• 1.0.0
• 1.1.0-beta1
• 1.1.0-beta2__2.0.0
• 1.1.0-beta3
• 1.1.0-beta4+5078__2.0.0
• 1.1.0-beta4+5278__2.0.0
• 1.1.0-beta5+5378
• 1.1.0-beta6
• 1.1.0-rc1
• 1.1.0-rc2
• 1.1.0

This shows that the next major version was considered but ultimately pushed back.

Also:

• 1.0.0
• 1.1.0-beta1
• 1.1.0-beta2__2.0.0
• 1.1.0-beta3
• 1.1.0-beta4+5078
• 1.1.0-beta4+5278__2.0.0
• 1.1.0-beta5+5378__2.0.0
• 1.1.0-beta6__2.0.0
• 1.1.0-rc1__2.0.0
• 1.1.0-rc2__2.0.0
• 2.0.0

This shows exactly why there is no 1.1.0 and why 2.0.0 is not a surprise.

And then we have:

• 1.0.0
• 2.0.0-beta1
• 2.0.0-beta2__1.1.0
• 2.0.0-beta3__1.1.0
• 2.0.0-rc1__1.1.0
• 1.1.0

This shows that the next major version was quickly shown to be too ambitious for the time being and that more moderate changes were made instead.

And finally:

• 1.0.0
• 2.0.0-beta1
• 2.0.0-beta2__1.1.0
• 2.0.0-beta3__1.1.0
• 2.0.0-rc1__1.1.0
• 1.1.0
• 1.2.0-beta
• 1.2.0
• 2.0.0-2beta1
• 2.0.0-2beta2__1.3.0
• 2.0.0-2beta3
• 2.0.0-2rc1
• 2.0.0

The 2 in front of beta and rc denotes a second attempt at creating a production-ready 2.0.0.

Hopefully this illustrates the point that with this convention we preserve the line of succession so to speak for the major, minor, and patch numbers while allowing for breaking changes to be communicated in the version number during development.

I hope this helps !

[Tieske]

IMO to complex. pre-release and buildnumbers are only included as metadata. This introduces another metadata element.

Finalize these discussions as per #30. Just stop making assumptions and stop comparing for compatibility once a pre-release tag has been added.

[icylace]

True, it adds complexity. IMO it also seems to handle all cases while staying communicative.

At the very least #6, #7, #8, and #9 of the Specification need to be refined IMHO.

If we stop making assumptions about future normal versioning while working on releases then how would you determine the pre-release versions of the successor to 1.0.0? How would such a naming scheme express the development progression toward the normal version of the successor? For that matter how would that naming scheme reflect the development history of the project as a whole once several releases have come to pass?

A couple possible scenarios that can come up when using #30 (or more precisely #28) are the following:

The first scenario:

• 1.0.0
• 1.1.0-beta1
• 2.0.0

The implied question here is "Where is 1.1.0?" At least that's the case for me but I can see this being easily addressed.

But what about this confusing scenario:

• 1.0.0
• 1.1.0-beta1
• 2.0.0-beta2
• 1.1.0-beta3
• 1.1.0
• 2.0.0-beta1
• 2.0.0-beta2
• 2.0.0

I suppose a potential workaround would be to append build numbers to everything to disambiguate things like 2.0.0-beta2 which also adds complexity because build numbers would have to become mandated. We could also try "retiring" 2.0.0-beta2 after its initial use so that during the 2.0.0 development cycle 2.0.0-beta1 would be followed by 2.0.0-beta3 but with this things are already counterintuitive. Either way would be against the reasonable assumption one would make when looking at a version number. The reasonable assumption being that 2.0.0-beta2 relates this particular beta2 to the development cycle for 2.0.0. We can't make that assumption in this case.

[haacked]

Since it is a pre-release, you have no guarantees that it's compatible. But it does communicate the intent that it should be, which is the point of SemVer. Communication of intent over any guarantees. As XKCD so eloquently pointed out, there are never any guarantees of backwards compat.

I just don't see the need to introduce time as another dimension to SemVer.

Let's look at the example that @Tieske addresses.

• 1.1.0-beta1 in the version we find out that we need to break stuff to implement the feature requested, so major bump
• 2.0.0-beta2 so the feature is now in, but is deemed impractical. That one feature breaks, while the other X number of features where compatible, so we decide to drop the feature again.
• 1.1.0-beta3 is this where we are now? because we dropped it, we are now backward compatible again.

In @Tieske's example, 1.1.0-beta3 is now where the tip of development is. But consider an alternate scenario with similar packages.

For example, you could release:

• 1.0.0 RTM Ship Party!
• 2.0.0 RTM woohoo!
• 1.0.1-beta <-- WHOOPS! Found a bug in 1.0.0 and we need to patch that shit after the fact.

This is common and there's nothing wrong with it. It doesn't matter that 1.0.1-beta came before or after 2.0.0. The only important part is that it communicates it's an intended minor update to 1.0.0 (though it might have breaking changes by virtue of being a beta).

Now there is a slight "problem" here in that when you are ready to work on 2.0.0 you've already released 2.0.0-beta2 which kind of sucks that you've taken that slot.

But this is really a problem of branching development. Suppose you started a branch for 2.0.0-beta2 and release it. And decide you don't like where that's going so you decide to start a completely different branch. You have the freedom to append a branch label to the version. 2.0.0-beta.crazyexperiment vs 2.0.0-beta.fixingcrap.

Am I making sense? Am I missing something? I'm trying hard to understand what changes are needed and I'm just not seeing anything yet.

[softprops]

Maybe my question was different because its not as complicated. My question was if the act of bumping ( and of the version segments ) implies the pre-release tag should be dropped?

If I have version

0.1.0-SNAPSHOT

and bump the minor version

Should users expect 0.1.1-SNAPSHOT ( pre-release tag intact) or 0.1.1 ( pre-release tag dropped)

Bumping without first dropping the pre-release tag seems like a user error for me but I wanted to know if this spec defines rules for this situation explicitly.

[haacked]

Honestly, I don't think the previous version has any effect on the answer.

In the example you gave I don't think it matters what you do here because according to SemVer, all versions less than 1.0.0 can be treated as pre-release. So it seems like it's really up to you what your second release should be. I don't think SemVer has any explicit rules around this intentionally.

But suppose we're talking about release versions.

You released a package with the version 1.1.0-SNAPSHOT. The question is, should the next version you release be 1.1.1 or 1.1.1-SNAPSHOT? Well, it depends on whether it's a pre-release or not.

If it is a released version, it clearly should be 1.1.1. If it's a pre-release of 1.1.1 then it should be 1.1.1-SNAPSHOT.

[softprops]

That's not the way I interpret "A pre-release version MAY be denoted by appending a dash and a series of dot separated identifiers immediately following the patch version."

0.1.0 is a release version do the the absence of the prerelease tag. 1.0.0 doesn't just imply a non pre-release. It carries semantic meaning for the contract around changing (stable) public apis.

[softprops]

"Version 1.0.0 defines the public API. The way in which the version number is incremented after this release is dependent on this public API and how it changes" just for context.

[haacked]

@softprops it's in rule 5

Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable.

In my mind, that's pre-release. It's certainly not release. :)

[haacked]

In any case, setting aside semantics, the clause "Anything may change at any time" leads me to believe it doesn't matter if you put the pre-release flag or not on anything below 1.0.0. Which I believe answers your question.

[softprops]

@haacked I think you are conflating pre-release, meaning a release made before something is final for a given version, and the semantics of the major segment of the version string.

If I depend on a have a library that depends on code for version 0.5.0 of a library, I can be safe from any changes made in future versions because that version won't change once published. If I depend on 0.5.0-SNAPSHOT on the other hand, it tells me that the library author may make changes before releasing 0.5.0. Those changes can potentially break my code by the release of 0.5.0. Its a pre-release and is subject to change by release time. This is fundamentally why you shouldn't depend on a pre-release version.

My question stays the same even if my example is 1.1.0-SNAPSHOT.

[haacked]

If I depend on a have a library that depends on code for version 0.5.0 of a library, I can be safe from any changes made in future versions because that version won't change once published.

@softprops I don't believe that is correct according to rule number 5. Let me highlight the relevant portion.

Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable.

This is referring to any release 0.* In other words, any release with the major version of 0 should be considered unstable. So if you depend on 0.5.0, then 0.6.0 can break everything. That's what I take away from Anything may change at any time means.

Do you have a different interpretation of rule 5 than I do?

[haacked]

@softprops I believe this is a special rule for versions 0.*. In all other cases 1.0 and above, I believe you are correct in the interpretation of what changing the major version means. 😄

[softprops]

@haacked my experience is with dependency management systems that resolve based on unchanging version numbers. Some dependency managers use dynamic versions that are not specified with ~ or *'s in their dependency configuration. If I depend on version the version number 0.5.0 it doesn't matter if there are changes in 0.6.0. My projects dependency resolver will only pull in 0.5.0.

I was curious about what semver's stance was on dynamic versioning and it looks like it was already brought up. It was closed because it was considered out of scope. Since it's out of scope, changes made in version 0.6.0 will have no effect on a project that depends on version 0.5.0. Anything may change at any time doesn't mean 0.5.0 today will not be 0.5.0 tomorrow for me. It's a release. Upgrading is a different story. Does that make sense?

[haacked]

@softprops sure, but that same principle applies to any version. Consider rule 4.

Once a versioned package has been released, the contents of that version MUST NOT be modified. Any modifications must be released as a new version.

So if you depend on 0.5.0-SNAPSHOT, even though it's pre-release, it doesn't mean that it will change out from under you. It just means should you upgrade to 0.5.0-SNAPSHOT2 there are no guarantees of compatibility.

As I understand it, SemVer treats each version as immutable once released. Perhaps this has been the source of our confusion in this discussion.

[softprops]

It may be an artifact for the manager I use, ivy. version-SNAPSHOT is considered a version whose hosted contents may change. If I resolve the dependency today its contents may be different than if I resolve the same version tomorrow. I'm happy that semver considers all versions immutable! Any prerelease tag to me indicates that the release is not quite there yet so it's almost never worth depending on in your release. It's only there to test your current version against a "bleeding edge" version of a dependency.

I think all of this is getting away from my original question. Let me rephrase to try and avoid more confusion.

Should the act of bumping a version segment (x.y.z) on a non-normal version produce a new normal version without the prerelease tag?

This is the simplified version of the original post for this issue

According to the Specification, patch version must be reset to 0 when minor version is incremented and both patch and minor versions must be reset to 0 when major version is incremented. However, it doesn't specify the behavior of pre-release and build versions when the associated normal version is incremented. Supposedly, they shouldn't remain the same, and, if so, it should be explicitly stated in the Specification.

[haacked]

Ok, that clears things up. SemVer doesn't address "snapshot" style versions (effectively mutable).

But back to your question. When you say "bumping a version segment" I read that as "releasing a new package with an incremented version segment". In that case, I think the answer is, "only if this new version is a release package and is not a pre-release package".

Think of it this way. Suppose SemVer did state you must reset the pre-release version when incrementing a version. How could that make sense?

Suppose you release 1.0.0-prerelease. You mean you wouldn't be allowed to release 1.0.1-prerelease next but MUST release 1.0.1 first? Really? That seems like an onerous restriction.

[softprops]

It may make sense if the prerelease tag is specific to the normal version it's preceded by.

1.0.0-rc2 > bump minor > 1.0.1-rc2.

But I haven't put out an rc1 for 1.0.1 yet! The user would have to reset the prerelease tag manually. I agree it is onerous to require you to reappend a new prerelease for the new normal version but I can see not doing so will produce non-sensible versions like the one mentioned above. I'm also including additions to the prerelease tag like the build version in this reset discussion. That's an even stranger case if I don't drop the whole prerelease tag side of the version.

1.0.0-rc2+build123 > bump minor > 1.0.1-rc2+build123

I now have a new version with starting at the second release candiate with 123 builds!

I should also add some context here. When I say user I mean the library author while developing. I'm writing a library managing structured version this in scala projects. I want the behavior of bumping to be expected but the spec doesn't mention this what the expected behavior should be. That's what I'm trying to get to the bottom of.

[haacked]

Ah, I see. Yeah, I think the spec is intentionally silent on this point. When you think about the Major, Minor, and Patch version parts, it's clear what reset means. Go back to 0. I think this is pretty universally understood.

But it's not so clear when you talk about the prerelease tag given the tag can be anything at all. From a SemVer perspective, the contents of the prerelease tag are effectively opaque and only used to determine 2 things, whether it's pre-release or not and version precedence.

Going back to your example, yeah, that intuitively doesn't make sense.

1.0.0-rc2+build123 > bump minor > 1.0.1-rc2+build123

But this might make sense. Maybe you've decided that the next version should really be a beta of 1.1.0 and not 1.0.1.

1.0.1-alpha > bump minor > 1.1.0-beta

Or maybe your prerelease tags look like

1.0.1-sthoeuone > bump minor > 1.1.0-ohteuidhoeun

I don't think the spec needs to (nor can) specify what to do here. Perhaps the FAQ can add a bit of guidance, but I just don't foresee this as a big problem. Use your best judgment here is what I say. :)

[zafarkhaja]

It took me a long time to read all the relevant discussions and come back to this one. After all I finally am starting to realize that I might have considered the Specification too "specifically".

The problem I have with it is very similar to that of @softprops and more of an implementation than a specification. I am also developing a library which is supposed to be an implementation of SemVer in Java. The following code snippet illustrates the problem I encountered:

Version v1 = Version.valueOf("1.2.3-alpha+build");
Version v2 = v1.incrementMajorVersion();

String normal     = v2.getNormalVersion();     // "2.0.0"
String preRelease = v2.getPreReleaseVersion(); // "" OR "alpha" OR "alpha1" OR "alpha2" ?
String build      = v2.getBuildVersion();      // "" OR "build" OR "build1" OR "build2" ?

I am aware of the discussions which eventually led to the PR #77 after merging of which the build version will become just a piece of metadata and will be left out of all sorts of comparisons. But the problem still remains for the build metadata if it was present in the version prior to incrementing.

So the main problem here is that the Specification is not specific enough in this regard to handle the issue programmatically, and I think I understand why. There is no exact rules to follow, hence it seems like every such implementation would have to decide what to do in such cases on its own.

@haacked, it would be great if some common practices regarding such cases were described in the FAQ section to help the implementations.

[softprops]

@zafarkhaja +1

@haacked I agree with your points after rereading taking a different perspective than the one I have writing tooling based on the the spec.

The rub for me now is that since the spec doesn't address it and implementors and tool developers writing tools based on the spec and having to arbitrarily decide whether to perform or not perform behavior in a scenario applicable to any client usage leads to inconsistent tooling. The point of having a specification is so that changing tools shouldn't have a big impact on the expected behavior for end users. It would be great if we could some how agree at least one what the expected behavior for semver tooling should be for this scenario.

Regardless of the contents of the numeric version segments, I believe that the prelrease tag is indeed opaque with regards to the semver spec but it does encode metadata specific to the previous numeric version segment tuple. As such, I think it loses meaning when applied to a different set of numeric version segments. That's why I think it should be dropped when moving to the next number version segment tuple.

What's uncomfortable for me though is that this is just what I think. It's subjective in that regard. I was hoping to get some consensus in this gh issue because of the issues title. If the spec can't address the expected behavior then can we document it elsewhere?

[haacked]

@zafarkhaja ah, I see. I think it's hard to really say anything about what incrementMajorVersion should do without understanding the context of your library. What is the person using it want out of it.

I'm going to speculate here and suggest the reason you call incrementMajorVersion is in preparation for a new version of the library. In that case, Have two overloads, one that takes a pre-release string and one that doesn't.

Version v2 = v1.incrementMajorVersion("alpha"); //2.0.0-alpha
Version v2 = v1.incrementMajorVersion(); // 2.0.0

I don't think we have to all agree on what that label must be.

[softprops]

@haacked I think we are both right tools that provide a user interface for bumping essentially. The question is if you make the second call

Version v2 = v1.incrementMajorVersion(); // 2.0.0

without the prerelease tag and v1 already had a prelease tag. Should the v1 pre-release tag be reset/dropped as it doesn't apply to the v2?

[haacked]

I think that's really up to your implementation. SemVer is mostly concerned about the output of your program. Is the version SemVer compliant or not. Either implementation will produce a SemVer compliant package. The real question is will both implementations meet user expectations?

In practice, I don't think you'd ever ship a 2.0.0 package as the successor to 1.0.1-beta. Chances are you're going to ship 2.0.0-alpha or 2.0.0-preview or whatever pre-release tag you wish.

One way to address this is to omit the parameter less overload. That way incrementing a major version requires an explicit choice to either make it prerelease or not by passing in a prerelease string or passing in null.

[softprops]

I think semver outlines more than just compliance. It outlines expectations for the result of actions ( bumping ). Unfortunately it just outlines expectations for the LHS of the dash as a result of bump and not the RHS of the dash. Otherwise the number of replies in this gh issue we be fewer in number :)

Regardless. Your last statement is what I've been looking for. Thanks! The act of bumping should explicitly specify a prelease tag or the previous prerelease tag will be dropped. It would be great to get that into a footnote of the spec so implementors are not left guess what the expected behavior should be. I think I'm good now.

[zafarkhaja]

@haacked, you were right in your speculation about the intended use of the incrementor methods. Indeed, they could be used as a version bumping utility, which could bump the version in compliance with the SemVer Specification. And, by the way, good idea about the overloading thing. I myself was about to ask if anyone had an idea how to solve the dilemma and you provided one. Thank you very much :)
What I think now is that this could be done but without much magic on the side of the library by asking the client for some more information.

@softprops, I agree with you on that it is somewhat inconvenient and inconsistent of the Specification not to specify about the pre-release version while specifying about the normal version. But honestly, at the moment I can't see how this could be achieved.

[haacked]

Hmm, maybe I'll add a FAQ question if this comes up a lot. Or see if one of the existing examples could incorporate this scenario. I don't think this comes up too often because usually people don't increment the major version until they ship the previous version.

In which case you go from

• 1.9.0 ship party!
• to 2.0.0-alpha get back to work everybody!

But none of these are requirements. Which is why I don't see there's much to add to the spec. :)

Glad I helped clarify things. I'll think about how the spec could be more clear about this as well.

[zafarkhaja]

I think we exhausted the issue and now if nobody has anything else to say on the subject it can be closed.

In case somebody interested in how I solved the dilemma, I solved it by providing overloaded methods which take pre-release version as an argument (thank @haacked). Build metadata is always dropped, if present. Examples can be found at the project's README page (https://github.com/zafarkhaja/java-semver/blob/master/README.md).

By the way, I've also implemented incrementors for pre-release version and build metadata as follows

alpha[.0]  -> increment ->  alpha.1
alpha.1    -> increment ->  alpha.2

build[.0]  -> increment ->  build.1
build.1    -> increment ->  build.2

[haacked]

Thanks for following up!