Approach to tagging/versioning builds of an executable

Question

In a certain software project I'm involved with, (one or more) of the executables which get built to write logs, and it is customary/expected for those logs to include some sort of tag or version information regarding the running process. This is currently done both for release builds, which have release version numbers (e.g. 3.5.1), but also for development builds, where the tag can and is more involved than that. There is a bespoke mechanism which generates code for this tagging, and uses git (i.e. assumes the source code is also a git repository) to obtain commit hashes and such. During build (re)configuration, a source file with functions returning build tags is generated, by examining the git history and/or computing hashes of things.

I want to scrap this mechanism, for the following reasons:

• Code should not rely on the existence of the revision control mechanism it may or may not be developed with. Specifically, one should be able to package a release tarball, unpack and build it with no revision control employed at all (e.g. no .git, .hg, .svn etc. subdirectories in the repository source).
• I don't like bespoke build-related mechanisms or libraries for tasks which are not specific to our project or to our organization; I'd like to use something common, well-known/well-established, which we don't need to maintain and worry about.
• I'd rather have build tags be intentional rather than extentional, i.e. the repository itself is not aware of, and cannot determine, what the build version is; and it is only the person (or program) configuring the build that says "your build tag is 'foo_experimental_2024_11_23+'", or whatever.

I would like to propose something different to the team, but I'm not sure what that would be, especially since I'm not familiar with build-tagging conventions in other projects. Any suggestions?

Answer 1

First, let me say there is nothing inherently wrong in having a build process which depends on specific tools, and Git may be one of theses tools. Source code requires always special tools like specific compilers, scripting languages, HTML or PDF generators, and though you may design a program to support a variety of tools, at the end there is a list of tool dependencies one cannot avoid. If your team has decided to put Git on the list of the dependencies of your project, than that is a valid decision.

However, there is just as little wrong with making a build process independent of Git. Generating a build version into the source code can be done (and is done!) differently in different environments, so searching for "the" standard is in vain. Still, lots of compilers / IDEs / build tools support such a mechanism, so you can use theirs instead of the SCCS's. For example, here on this older SO post you find some information about Visual Studio. Here is a post about a Maven plugin which accomplishes this. And if your compiler/build environment does not have a standard mechanism out of the box which suits your needs, just write your own little script which does what you want.

Let me add the idea of generating revision number from the used SCCS into the source itself is not new. SVN, for example, provides keyword expansion. Git does not support this directly, but it can be accomplished through customization (which bears a certain risk to work differently in different Git environments). CVS has such a mechanism. Other systems which I had to deal with in the past also had. So having sources or build process (loosely) dependend on the SCCS is not a very special or unusual idea.

Answer 2

Build versions / labelling is a tool, you need to decide what are your requirements, some common requirements are:

1. To identify the specific commit that the build was produced from.
2. To identify the branch in source control.
3. To identify the relative order of two builds A was built before B.
4. To indicate functional compatibility (Semantic Versioning)

If your system identifies the commit (#1) you can work out the branch (#2) and ordering of builds (#3) however it is sometimes useful to be able to look at a build without referring back to source control. You may be able to achieve that with additional metadata (build date and branch) hence it may not be necessary to include that information in the version number.

Git hashes, Perforce CL# etc are often used because it is very low effort for everyone involved - the DevOps team simply includes the info in the build and everyone else can simply refer to it identify which build they have / where it came from.

There are two primary issues with Semantic versioning:

• It doesn't handle branches (concurrent development) very well because code being merged between branches doesn't really change its semantic meaning.
• Ideally you include a manual step to indicate that important changes have been made, optionally having a concept of SNAPSHOT verses RELEASE builds. **

** - If you don't manage your numbers - you are not using the changes to indicate significant changes, it just becomes a build number so why bother?

Recommendations:

• Use semantic version if you think your team will leverage/benefit from it.
• But also include the other metadata (GitHash, Branch, Build date) into the build - in a way that is easy to query.
• If your build tooling leverages semantic versioning use it for artifact repositories.
• For binary images (VMs, Docker etc) its probably best to continue to use git hashes since there will likely be multiple builds before semantic versions are reved.

Answer 3

Having a git commit/tag baked into the final artifact (package, executable, docker image, etc) is extremely useful. It helps debugging a lot. If you use anything else, then how will you know what code was actually deployed? You will need some mapping between versions and git commits. Which is an external dependency anyway. Which is just more complicated solution, and even less portable.

But that doesn't mean that code itself should depend on a revision system. It is enough if the appropriate build number is injected during build process. The code doesn't even have to use it, it is enough if it is present in the final artifact. But it can use it, for example a server that serves its own version, why not?

Side note: I'm saying it is useful, but not necessarily safe. Malicious users can do something with that information if it ever leaks. Just be aware of that. That being said the risk is (or should be) rather low.

So, all you need is a build process. Most compiled languages (including those compiled into bytecode like Java and C#) have mechanisms to run arbitrary code at compile time. You can use that. If not then you will need some build scripts. Just make sure that those work even when a revision system is not present. That's all.

So the bottom line here is: build process should be aware of the revision system. Code does not have to be. Separate those two, and it will be fine.

As a final note: I really love semantic versioning. And I think it is better than baked in random build numbers. But it has one major flaw which IMO makes it very inferior: it requires a dev attention. I will always chose things that can be easily automatized above those that require manual work. Even if such solution is technically inferior. Because ultimately there's always more trouble with people than with code. That being said nothing prevents you from having both at the same time.

Answer 4

I think almost everyone uses:

1. Single CI pipeline for all builds,human specified Major.Minor and an incremented build number

This wont pick up on local builds, but it works for all dev/test/prod builds because they are forced to go through the pipeline.

A key thing here is that you are versioning the built code. Not the aource

Alternatives.

2. I think microsoft used to provide an option to use a date as the build number. This also provides an ever increasing version which is independent of a central system. But can get confusing if your local dev build from an old commit has a higher build number than the most recent version.

3. git commit ids. I think its fairly common to tag builds with this info, but it fails as a version number. Simply speaking if you have two feature branches, asking which is the later version makes no sense. Also, what if you build the same commit twice with different options etc

4. Don't use a build number at all, just manually update the version when you publish. This is problematic because you can end up with two different exes with the same version