What does a version number represent?
A release is the output generated by following a defined process using build tools on source code.
So, if the release process or build tools change, even when used on the same source code, then the release should be considered a different version. It is because of this, that the version number should be managed by the CI/CD pipeline, and not within the source code, and should be generated as a unique label each time the the release process is performed.
Who / What cares about the version number?
Which version of the Google search engine did you use to find this question on Stack Overflow?
Okay, you probably don't know (or care), but I'd bet my house that Google knows.
The key thing to think about is the audience of the version numbers. For an internal release,
branch.build_number.commit_hash contains the key information. From the branch name you know the maturity of the release, the build number allows you to determine relative age between two releases, identify build parameters and tooling used from the CI/CD pipeline logs, and the git commit hash allows you to identify the source code used. If your product is your website, this format can also be used on your production releases too.
However, if you are releasing a series of discrete version of the application over time for other organisations to use as a component of their product, then your customers should be version aware. Upgrading your component version in their product should be something they consider as a change to their product that needs to go through their test and release process. Using version numbering to provide information about the significance of the changes is a common approach. For example,
major.minor.patch[.build] is a common format for public releases.
- Major version number changes, customers should expect significant changes to the product that have the potential to break existing behaviour.
- Minor version number changes signal that there are feature enhancements, but not breaking changes.
- Patch version number changes should signal that only internal implementations have changed. Changes that are visible to customers should be limited to fixing product defects.
The key message here is make sure that your release labels are relevant to their audience and infer useful information about their content.
What about if my code needs to know its version number?
Code should know its version number, and be able to report it, but it should not care about what its version number is.
As part of the CI/CD build process, I would expect that the version number is embedded into the output artifact, allowing full reporting and traceability of defects and functionality. However, code deriving information from its own version label, and changing its behaviour as a consequence is a risky design pattern.
How should i store the current release number in Git, and not get merge conflicts?
If the reason for storing the release number in Git is because you release from the Developers local environment, then you have bigger problems than version numbering. Set up CI/CD first.
In Git, define the release label format, and the script that populates the version string and embeds the value into the build output. Ideally this should be part of your build scripts repository and not your source code repository.