9

I'm working on a project that uses Semantic Versioning. The commit history can be generalized as:

enter image description here

Also, the current version is present in source code (so that the software can use it for various purposes).

I'd like to start implementing a process that I've been seeing around:

  • Development commits contain a version such as x.y.z-dev. The idea is that x.y.z will be the next release, but we are currently developing it.
  • When development is over, the in-source version becomes x.y.z for the one commit that is a release.
  • After the release, the source code updates to use a new x.y.z-dev version.

This allows the software as seen on development commits to not erroneously suggest that it represents a release version.

The issue I'm running into is knowing which version to increment to after a release. Semantic Versioning has requirements for what kinds of changes can be found in a new version. For example, 1.0.0 to 2.0.0 indicates a backwards-incompatible change has been made to some interface. But, directly after a release (when the version is incremented to a new -dev version), it's hard to say what kinds of changes will be included in the future for the next release.

For example, if we just released 1.2.3, incremented to 1.2.4-dev, and then introduce a backwards-incompatible change, 1.2.4-dev is now invalid and should be 2.0.0-dev.

Should I just do another increment to the next -dev major version during the development cycle when we notice that such a change has occurred? It seems iffy that commits would then exist with a version that would never be released.

Improve this question
1
  • Damn good question! After the time goes by can you give a short report about your experience with the solution of your choice please? Did it work for you? Commented Apr 19, 2023 at 20:40

1 Answer 1

Reset to default
7

Mu. Releases have versions. Commits do not have versions. Version numbers are assigned during the release process. At least as far as SemVer is concerned.

Adding a pre-release like 1.2.4-dev would still be a release, albeit with special SemVer ordering semantics. But even for a pre-release: once you make the release, you're not allowed to use the version number for a different release.

Of course, this is a rather unsatisfactory response. We do want to summarize the state of the software in a single identifier, even for an unreleased development state. This is an inherent limitation in SemVer. One solution might be to use a deliberately non-SemVer label such as dev-1234abc where part of a Git commit ID is used in the label. One compromise could be to note that the version number is meaningless on unreleased project states, so that you should just build upon the previous release. One of my projects just keeps the last version numbers, and just accepts that you can't tell a dev version apart from the previous release.

Adding build information to a SemVer number could help, though the build information is ignored by SemVer ordering semantics. For example, you might add a Git hash like this to the previous release: 1.2.3+git.1234abc. This would give you a somewhat useful label, but this shouldn't be mistaken for a true SemVer number because it was not assigned to a release.

Improve this answer
2
  • 2
    I'm happy with this answer because it shows that my expectations for SemVer were incorrect. We had been persisting the last released version in our source code during development, and I think I'll just stick with that and note this in the project documentation. Commented Feb 14, 2021 at 1:04
  • 2
    This answer just about covers it. The only potential thing to consider is taking it a step further and enforcing that the versioning is part of the release process, rather than living in the source code. You can use combinations of things like Conventional Commits and other structured commit messages, tags, and branches to be able to generate version information in files without ever committing a version string. Commented Feb 14, 2021 at 2:43

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.