What version number should we set on our develop branch now?

[rartino]

Our wiki new release page states that after merging develop into master as fast forward, we shall create a PR to change the version number in the specification document in the develop branch before merging more PRs.

Increase the patch version number to reflect the next release target in the title of the optimade.rst

However, we are now at v1.0.0-rc.1, next release may be v1.0.0-rc.2 or v1.0.0. It most certainly will not be v1.0.1.

The key issue seems to be: can we set a version string for the developer branch that is SemVer-sorted later than the just released version, but before any actual release we may do in the future? It turns out, this isn't easily solved, and others have noted the same. I found a discussion among the SemVer github issues: semver/semver#124.

They land in recommending to update the version number continuously based on what changes are merged into develop. I.e., starting from v1.0.0, as soon as a patch is merged, the PR with that patch should also change the version string to v1.0.1-develop. As soon as new functionality is merged, the PR that adds functionality should change the version string to v1.1.0-develop. As soon as something backward breaking is merged: v2.0.0-develop.

If we follow this, we should go with v1.0.0-rc.2-develop now. There will be no big issues with this scheme right now, since anything can go in the release candidates that turn v0.x.x into v1.0.0.

But, I'm not super enthusiastic, because:

• In the future, this will make many PRs mess around with the version number, causing unnecessary merge conflicts.
• For every PR we consider we will have to look at the development history and ask "has the version number already been bumped sufficiently for this PR?"

As an alternative proposal, we could instead in our development branch use a version string that adds develop in a way that purposely breaks (!) SemVer as <last release>~develop. E.g, v1.0.0-rc.1~develop.

Why? Because development versions are not properly SemVer ordered anyway; between releases the version string is just a placeholder to clarify that you are looking at a file in which active development has been added on top of the last release. Unless we actually bump up the patch number for every PR we merge we are anyway breaking the spirit of SemVer by there being multiple versions with the same version string. To me it seems to be a feature, rather than an issue, that any code that tries to treat these version strings according to SemVer explicitly breaks.

Then, as soon as we are ready to release, we remove the non-SemVer ~develop suffix, and the version strings we use for releases are all SemVer-compliant.

We also could attempt to petition SemVer to add support for ~develop :-)

[merkys]

This is a very interesting issue. Our group stumbles upon it quite frequently.

But, I'm not super enthusiastic, because:

* In the future, this will make many PRs mess around with the version number, causing unnecessary merge conflicts.

This is at max 3 version number bumps between two subsequent releases, thus not much, but merge conflicts might emerge indeed.

* For _every PR we consider_ we will have to look at the development history and ask "has the version number already been bumped sufficiently for this PR?"

I don't think this is a large overhead, but it is at least some. One would have to compare version of the previous release with the current one for each PR.

As an alternative proposal, we could instead in our development branch use a version string that adds develop in a way that purposely breaks (!) SemVer as <last release>~develop. E.g, v1.0.0-rc.1~develop.

I like this option the best. I also use dev suffix in some of my projects, although without intentional breakage of SemVer. But this also poses a nice property, just as explained.

[rartino]

• this will make many PRs mess around with the version number, causing unnecessary merge conflicts.

This is at max 3 version number bumps between two subsequent releases, thus not much, but merge conflicts might emerge indeed.

Just as an example of this, let's say that right after a release, we have five PRs posted, some patches, some new features. Should all these PRs modify the version string? Should they be adjusted with new commits when another PRs is merged? This seems like a lot of fiddling around with the version string until we coverge on a new version.

Also a further (but perhaps weaker) argument: I like being able to just look at a -dev version number and be able to immediately see which stable version it stems from, so I can do diffs and, e.g., see if some oddity goes back to that version or has been introduced during development. This would be more tricky if the version number in the dev tree changes.

[merkys]

Just as an example of this, let's say that right after a release, we have five PRs posted, some patches, some new features. Should all these PRs modify the version string? Should they be adjusted with new commits when another PRs is merged? This seems like a lot of fiddling around with the version string until we coverge on a new version.

Following this scheme, every PR should modify the version string according to their content. There should be at most three different version strings (based on the previous stable version) among all the PRs at any time. As PRs are merged, the open PRs have to be adjusted to the version string in the develop branch. So there is some fiddling indeed.

Also a further (but perhaps weaker) argument: I like being able to just look at a -dev version number and be able to immediately see which stable version it stems from, so I can do diffs and, e.g., see if some oddity goes back to that version or has been introduced during development. This would be more tricky if the version number in the dev tree changes.

Agree, this is yet another nice property of ~dev scheme.

[CasperWA]

Closed by #256.