alpha.branchname, beta, rc tags instead of branchname, unstable, beta?

[o-o00o-o]

So, the default config for tags are set as follows (we are using GitFlow)

feature: useBranchName
develop: unstable
release: beta
hotfix: beta
master:

I may be missing something but I'm not sure why this is as it means that according to SemVer rules your feature branch is now a higher version than the release branch? i.e. v1.0.0-beta < v1.0.0-unstable which is never going to be the case.

This is causing a problem for us as we are checking the version and actively preventing deploys of versions < the current version.

The normal GitFlow is feature->develop->release->master
or
hotfix->master

So wouldn't it make sense to assign tags that allowed reflecting this?

so, to achieve this I would propose:

feature: alpha.useBranchName
develop: beta
release: rc
hotfix: rc
master:

This way feature < develop < (release | hotfix) < master

In order to achieve this I think we would need an extension to the way we can specify "useBranchName" to allow it to be specified in-line (I am assuming that this isn't currently the case from what I've seen but I could be wrong). We need this for features so that all features are always have lower precedence to develop regardless of the name of the branch.

The rest we can change now via the config but it would seem to me to be reasonable to also consider changing the defaults here to help people use SemVer correctly?

Interested in thoughts.

[JakeGinnivan]

This can be overridden in the config, that said this is intentional. Develop doesn't follow SemVer as the release process is what actually will determine the version number. With that in mind we always make develop (and feature branches targeting develop) a higher version.
The recommended approach is to have develop in a separate NuGet feed then anything which is actually released (from release branches or other) go to the official NuGet feed.

Without making develop higher there is no way to just upgrade to the latest on develop in an automated way, which breaks far more people who need a continuous integration scenario across multiple packages. nServiceBus is one example of this

[JakeGinnivan]

Oops, didn't mean to close. Does that answer the question, and if you have ideas to improve the docs on this suggestions are welcome

[o-o00o-o]

Ok so I guess there are couple of things here:

1. Practically (and most importantly) we can't do everything I suggested in the config. We can't create feature branches as being alpha.branchname. I've tried it in the config and it doesn't work unless there is a trick I don't know about. Currently I am working around this using the GitFlow config to force the "alpha." prefix to the actual branches but this is not ideal. It requires every member having this set correctly and it makes the branch names longer than they need to be (feature/ is enough of a qualifier to categorise). so it would be great if GitVersion would allow "useBranchName" as a token somehow, so I can configure feature branches to be "alpha.$BranchName$" or something to get this behaviour via config.

If we could add this feature then it would be fully configurable and we could all choose to prefer SemVer or to prefer simpler Nuget config. If this is agreed would it be better to create a separate issue for this feature and leave this as the conversation about the defaults or common patterns for documentation?

1. Philosophically regarding the defaults my perspective would be that GitVersion is orientated around SemVer, not NuGet. NuGet simply uses SemVer also - albeit SemVer v1. So any problem with Nuget regarding SemVer is really a problem for Nuget to fix, not GitVersion.

SemVer has support for version numbers and prerelease built in and the rules are clear. The sequence in GitFlow is also clear. This indicates that v1.0.0 feature < v1.0.0 develop < v1.0.0 release < v1.0.0 master and the alpha, beta, rc, pattern does this where the current branchname < unstable < beta default doesn't. This seems to me to be the overriding principal here that tells me that alpha, beta, rc is the more intuitive default with other patterns perhaps being needed in more specialised scenario's.

I have not run into the specific case you are referring to with CI, so perhaps a more detailed example that shows the problem would help me understand this and what the solution really should be. But creating separate feeds and changing the version numbers so they no longer follow semver definitely seems like a compromise that should be improved. I suspect it could be more appropriate to have a packages.xml transform step so consuming projects can dynamically find and set the appropriate dependency version according to whatever rules the CI process expects.

But also, if you are changing the feed (and I guess therefore the nuget config to specifically include only specific repo's for different branch petterns) then you wouldn't need to fudge the version number anyway would you? if feature/deploy went to one repo and release/master went to another. The consumer will be deciding which repo they want to use, so no clashes from any of the others... But then on the feature/develop repo, feature branches would sometimes be a higher version and sometimes a lower version than develop? (e.g 1.0.0-FixLoginProblem < 1.0.0-unstable < 1.0.0-ZebraEffectProfile) so I think the same problem exists here that the alpha.branchname. feature would solve.

If you have more details on the exact common scenario that the current default solves that will help us work through the best solution for this and we can then document this for the help pages.

Cheers

[JakeGinnivan]

Practically (and most importantly) we can't do everything I suggested in the config. We can't create feature branches as being alpha.branchname. I've tried it in the config and it doesn't work unless there is a trick I don't know about. Currently I am working around this using the GitFlow config to force the "alpha." prefix to the actual branches but this is not ideal. It requires every member having this set correctly and it makes the branch names longer than they need to be (feature/ is enough of a qualifier to categorise). so it would be great if GitVersion would allow "useBranchName" as a token somehow, so I can configure feature branches to be "alpha.$BranchName$" or something to get this behaviour via config.

That is a good idea, would you mind creating an issue with this. I suggest using string interpolation which will align with my suggestions at #660 (comment)

Philosophically regarding the defaults my perspective would be that GitVersion is orientated around SemVer, not NuGet. NuGet simply uses SemVer also - albeit SemVer v1. So any problem with Nuget regarding SemVer is really a problem for Nuget to fix, not GitVersion.

In an ideal world, but NuGet are not fixing ecosystem issues anytime soon so we have to deal with the way things are and do our best.

SemVer has support for version numbers and prerelease built in and the rules are clear. The sequence in GitFlow is also clear. This indicates that v1.0.0 feature < v1.0.0 develop < v1.0.0 release < v1.0.0 master and the alpha, beta, rc, pattern does this where the current branchname < unstable < beta default doesn't. This seems to me to be the overriding principal here that tells me that alpha, beta, rc is the more intuitive default with other patterns perhaps being needed in more specialised scenario's.

The sequence in GitFlow is clear, but that is a progression on how code moves through the process. The specific problem we have not been able to solve without using unstable is:

1. Last release is 1.2.1
2. release/1.3.0 exists and 1.3.0-beta.1 has been released to the official NuGet feed
3. How can I consume CI builds from my CI feed without turning off the official NuGet feed?

Turning off the CI Feed is not a problem if you need to upgrade to beta packages but turning off the official will break package restore and installing of dependencies which then puts you into the situation of replicating dependencies and other pain.
Having develop producing higher version numbers than release branches and master is the only way we have thought about how to solve this issue. The thing is that the public will not be using your CI packages, they are untested and unstable so we have made an assumption that you never release from develop. Hence the SemVer can be higher as it will never be released to override the packages higher than it.

But then on the feature/develop repo, feature branches would sometimes be a higher version and sometimes a lower version than develop? (e.g 1.0.0-FixLoginProblem < 1.0.0-unstable < 1.0.0-ZebraEffectProfile) so I think the same problem exists here that the alpha.branchname

Yes this would cause an issue. I don't have a good solution for this.

[o-o00o-o]

That is a good idea, would you mind creating an issue with this. I suggest using string interpolation which will align with my suggestions at #660 (comment)

Done #664

1.Last release is 1.2.1
2.release/1.3.0 exists and 1.3.0-beta.1 has been released to the official NuGet feed
3.How can I consume CI builds from my CI feed without turning off the official NuGet feed?

Turning off the CI Feed is not a problem if you need to upgrade to beta packages but turning off the official will break package restore and installing of dependencies which then puts you into the situation of replicating dependencies and other pain.
Having develop producing higher version numbers than release branches and master is the only way we have thought about how to solve this issue. The thing is that the public will not be using your CI packages, they are untested and unstable so we have made an assumption that you never release from develop. Hence the SemVer can be higher as it will never be released to override the packages higher than it.

Sorry, I'm not 100% sure I'm following the problem, but the 1.2.1 and 1.3.0-beta.1 are dependencies to a CI process for another system right? So this other system has a packages.xml file that currently specifies which version should be used?

I'm not sure which would you would consider to be the correct version to use for each case but could you use allowedVersions in packages.xml to control the correct version to pick up?
http://docs.nuget.org/Create/Versioning. MSBuild could help set this automatically if needed for your CI rules?

Having multiple feeds and changing nuget configuration for different branches to pick which nuget repo to use seems equivalent but a less intuitive way of solving the same problem that allowedVersions solves?

But then on the feature/develop repo, feature branches would sometimes be a higher version and sometimes a lower version than develop? (e.g 1.0.0-FixLoginProblem < 1.0.0-unstable < 1.0.0-ZebraEffectProfile) so I think the same problem exists here that the alpha.branchname

Yes this would cause an issue. I don't have a good solution for this.

Actually this would be solved by #664 also.

[JakeGinnivan]

1.2.1 is the last stable release, 1.3.0-beta.1 is the last beta release. Develop will be producing 1.3.0-develop.50

Take GitTools, we are creating GitTools.Core and because we track it quite tightly we probably want to verify we work with the latest CI build of it to make sure changes coming in GitTools.Core which break GitVersion are detected right away. If GitTools.Core has 1.3.0-beta.1 how do I install 1.3.0-alpha.50 which comes from develop without explicitly checking latest CI version then upgrading to the specific version?

[o-o00o-o]

Thanks for the clarification. Does this setting in the packages.xml file not work?

Package id="GitTools.Core" version "1.3.0" allowedVersions="(,1.3.0-alpha9999]"

This should limit the version obtained and you could customise the rule you want to apply for each branch as determined by the specific CI requirements?

[judgeaxl]

I, also, got confused by the IMO unintuitive develop/-unstable ordering being higher than beta/rc, and I think it comes in part from the fact that develop's version doesn't increment until the release branch has been finally merged to master/develop.

Let's say develop is at 0.9.0 and I create my release branch, release/1.0.0, then develop will stay at the previous version, for each new commit, 0.9.0-unstable.N, although it seems to me like it really should be generating 1.1.0 at this point. (Note that at this point, the unstable-tag doesn't solve the problem with CI builds) Similarly, if I created a release/0.9.0 branch, I'd expect develop to generate 0.10.0 versions, but it stays at 0.9.0.

I think the feature/alpha, develop/beta, release/rc pattern suggested above makes a lot of sense, in terms of understanding the relative order, although it may then be applying different values into those names compare to what we are used to. In a sense, -unstable feels like a workaround to cover up that develop is not incremented until the release has been merged.

[asbjornu]

@judgeaxl Does #673 describe your use-case sufficiently?

[judgeaxl]

@asbjornu not really. I'm using standard GitFlow (AFAIK), where release and hotfix branches are merged into master and develop. My concern is similar to what @o-o00o-o is talking about. -unstable is considered a later version than -beta and -rc. And IMO, as soon as the release branch has been created, develop is no longer on that same version, it should be at least a minor version up. Currently this doesn't happen until the release has been merged back to develop. (I should point out that I'm using a complete default config, no changes at all)

   /-C (release/0.1.0)
A-B-D (develop)

A=0.1.0-unstable.1, B=0.1.0-unstable.2, C=0.1.0-beta.1, D=0.2.0-unstable.1

C is branched from B, D is additional development. This is how I would expect things to work, but currently D will get the version 0.1.0-unstable.3 instead, meaning it's considered newer than C, and while that is correct in a way, if develop is really on the next version, it would make more sense to me.

Although, feature branches do present a similar problem, where the semantic version will be considered behind or ahead of develop depending on the name. Again, while these builds are not meant to be released, it would be great to have the system work in the same way across all branches.

So, to summarize:

1. develop doesn't bump to the next minor release when I create a release branch, only when I finally merge it back to develop.
2. -unstable is sorted in the wrong place (IMO) compared to -alpha, -beta, and -rc builds.
3. feature branches will be sorted before or after develop only based on their name, not based on policy or convention.

[judgeaxl]

Also, I don't want to say what's right or wrong here, perhaps the current way works well for some people, but I've been going at different angles on this whole versioning problem for decades, and there never seems to be a perfectly pure solution, although GitVersion is very promising. :)

[o-o00o-o]

Thanks for the thoughts @judgeaxl and the support of the alpha/beta/rc default.

I can see that the change of behaviour you describe is potentially another solution to the problem it seems that the feature/unstable/beta pattern was implemented to solve. To ensure that develop is always the latest version which rescues CI processes from having to do anything actively to ensure they are always using the latest develop version. It would be an elegant solution to that problem.

The only problem I can see is if it happens that the release branch is deleted before merging into master. If this could be true you may change history of your develop branch (e.g. you branched from the wrong point on develop). I have never experienced this case and I can't think when it really might happen but it could be difficult and complex to recover from apart from to skip an entire version by force.

E.g. from your example D is now 0.2.0-unstable.1 but then we delete branch release/0.1.0 and now we are back to D is 0.1.0-unstable.3 etc .. (changed history=bad). if you then create the 0.1.0 release branch from a different base from develop branch later, your new 0.2.0-unstable.1 will now be a totally different commit but with the same version number.. this is bad. If you have created any automatic build packages with the old 0.2.0-unstable.1 you will now get clashes, or ignores from the build pipeline.

Having said that I think this could be another good configuration option worth considering so that GitVersion implementers can decide the behaviour and tradeoff's that they are willing to live with.

[judgeaxl]

True, that could become a problem. One possible solution could be to not just delete the release, but merge it back to develop anyway as a discarded release, assuming that the merge commit version strategy would pick that up. Now, you'd end up with a gap in your release-list, but since you have already generated one or more builds for that release, you cannot really re-create it later without ending up with the same problem, but on the release branch, could you? I mean git allows for all kinds of history rewriting, so there's no safe way to fully avoid ambiguities. Just rules and patterns to reduce the risk.

Sometimes I think develop and feature branches should just have no version at all, or 0.0.0, but that would again cause problems when you want to use the latest by version.

[o-o00o-o]

Yep I like that solution for the rare case. I don’t mind burning a release number and it isn’t against the semver rules.

I guess it would be best to create a new issue for this suggestion as it is really independent but to reference this in as they are related.

I do think it would be a good solution to the problem that the old unstable/beta pattern was designed to solve. I’d be interested to know if @JakeGinnivan agrees.

[judgeaxl]

I've created a new issue #695, as you suggested @o-o00o-o .

[JakeGinnivan]

Is this discussion actually sorted if #664 and #695 are done? Or are there still open questions?

if there are still open questions/discussions then let me know and I will re-read/digest this thread and give my thoughts

[o-o00o-o]

I guess I was hoping that this thread would drive the changing of the default configuration or at least having this as a standard preset or well documented option.

Of course we have to have the configuration available first via #664 and #695 but once done I think there is a good case for changing this default to prevent most people eventually finding the same issue to then have to switch their config..

[GeertvanHorrik]

Sorry for jumping in, but I actually wanted to achieve something similar. Currently GitVersion defaults to unstable for the develop branch. Although this sounds logical, it's killing for semver because it doesn't allow me to release alpha/beta for the same version.

I think it should either point to alpha (alpha means the first ever versions to be released anyway), then once you start going into a release branch, it will become beta (it already does this), and finally becomes stable. I think this fixes a lot of "semver issues" (because semver only looks at the numeric values of text, not the meaning of it).

[JakeGinnivan]

@GeertvanHorrik that works assuming you stop work on develop and switch to the release branch.

This may sound stupid, but it almost is like while a release[/-] branch does not exist, the tag should be alpha. But any builds which happen while there is a release branch active should be marked as unstable. This will complicate the GitVersion logic a lot though, so not sure I would like to go that road.

The thing is that if you take a release branch to stabilise while continuing dev on development, then unstable makes perfect sense.

Bumping develop as soon as you take a release branch is another case where maybe release branches are special for develop, same as above.

[GeertvanHorrik]

But what's the diff between alpha and unstable in your definition? To me they are the same. Alpha == unstable, even beta is considered unstable but is coming from a release branch. The only thing is that SemVer officially sees 1.2.0-unstable23 > 1.2.0-alpha23, which makes it really hard to use this with tools like Squirrel (they just use alphanumeric sorting like in SemVer).

This means that as soon as I create a release branch (and versioning starts with beta, Squirrel won't see the updates because .beta < .unstable). I have created a separate fork of Squirrel that takes care of this, but it would be great if I could go back to Squirrel without having to maintain the fork.

[JakeGinnivan]

@GeertvanHorrik I have rethought this all, so v4 will be using the more logical naming scheme

[GeertvanHorrik]

Awesome, thanks.