How to manage release versions across different build tools?

Question

I'm looking into improving how release versioning works in my project. The result of a release is composed of multiple artifacts, involving multiple tools and their corresponding control files depending on their domain:

• CMake (CMakeFiles.txt) for C/C++
• Maven (pom.xml) for Java
• NPM (package.js) for Node.js
• Sphinx (conf.py) for documentation hosted at ReadTheDocs
• Any other tool (e.g. I think we could soon be generating Docker images for each release, so add Dockerfile here)

Each one of those typically contains a Project Version field where the version of the release is written, and the release artifact obtains its version number from there. I want to unify those duplicated version numbers scattered around multiple files, into a single source of truth. I've searched but didn't find satisfying solutions, so I'm asking here:

What are some best-practices or standards for robust & easy management of version numbers in projects that span over multiple languages/build tools? Specifically at least for the 4 first types indicated avobe, although a generic solution would be preferred.

One important requisite is that I'd rather avoid wrapper scripts (e.g. doing field substitutions with sed), in order to keep the tools independent of even more external tools (i.e. I want that the build command stays "cmake" instead of "cmake_prepare_and_run.sh").

Update: I consider a general good practice limiting CI to read-only operations over a code repository, and this is a policy that I enforce in my projects. I don't really need, nor want, that CI is too clever and decides to automatically release new versions without any supervision.

Answer 1

My own solutions to this question - so far, these are the two ideas I've come upon:

A. Get the release version from Git tag. When building any module, the build tool will have to do something in the line of git describe --tags (maybe with --always and/or --abbrev=0) and extract the result into a variable that contains the version. I would have a "release" branch in Git, which would only be used for releases, and new release artifacts would be published only for commits in this branch that are tagged with some version number. This has the problem of requiring that each separate build tool is able to easily run a subshell with a command and obtain the command's result. It also means that the version number is tied to the version control system.

B. Create a text file named VERSION in the root of the repository, containing the version number. Then, configure each build tool to first read that file and load the version number from it, before doing the normal build steps. It still depends on editing a file, but at least this would be centralized to a single one, and it would always be the same, sitting in the same place.

Both solutions would require that the build tools allow to perform those actions; for some like CMake and Python it would be easy, but I'm not so familiarized with tools such as Maven, NPM or even whatever parses Dockerfiles so I'm not sure if these would be generic solutions.

Answer 2

Generally, solution A is the one most often implemented.

• the version control system does not change that often (if ever)
• most build process already have a plugin calling the right git command and generating a properties file with the version information in it.

For instance, for maven, that would be ktoso/maven-git-commit-id-plugin