1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
|
<!doctype html>
<html lang="en">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="author" content="aki">
<meta name="tags" content="versioning, deployment, software development">
<meta name="published-on" content="2022-07-02T23:33:33+02:00">
<meta name="last-modified-on" content="2022-07-04T18:00:00+02:00">
<link rel="icon" type="image/png" href="favicon.png">
<link rel="stylesheet" href="style.css">
<title>Let's Not Store Versions in Versioned Files</title>
<header>
<nav><a href="https://ignore.pl">ignore.pl</a></nav>
<time>2 July 2022</time>
<h1>Let's Not Store Versions in Versioned Files</h1>
</header>
<article>
<p>It is a rather common practice to include version numbers directly in the meta files or sources that are stored
inside a code repository. To list few examples: <a href="https://www.npmjs.com/">npm</a> makes it part of its regular
practices, python's <a href="https://setuptools.pypa.io/">setuptools</a> usually involves various hacks, be it normal
imports, reading file, or anything else. Even in their more declarative approach their support limits itself to string
literals and file or module attribute reading.
<p>OK, we have a version number in a configuration file, or some other special file, or directly in the code. What's so
wrong about it? The natural enemy of this blog - duplication. In this case, we're talking responsibilities.
<p>There's a rather high chance that you are using Git to track changes. If not Git then Mercurial, SVN, Fossil, Darcs,
or really any other version control system, distributed or not, it doesn't matter. What matters is that these tools are
designed to help you control different versions of your software. When you add your software version into the source
code of said software, you create a new independent layer of versioning.
<p>Now, not everyone is a minimalist and a mere threat of an additional entity handling the same thing might not scare
you. Same thing regarding the duplication of the version data. The problems begin when the version data is actually not
duplicated between VCS and the source code. Native identification of commits in Git - SHA - doesn't really fit for
distribution use, where <a href="https://semver.org/">Semantic Versioning</a> makes much more sense for users. The point
stands for other VCSes as well.</p>
<img src="lets_not_store_versions_in_versioned_files-1.png" alt="say no!">
<p>We end up with two distinct layers of versioning where one controls the other. This usually leads to very awkward
workflows. In a commercial project I have worked in, we wanted to mark mainline branch as unstable and make it visible
through a version number. For a released (and validated; the whole workflow was heavily oriented on paperwork) piece of
software we wanted a regular version number. This resulted in an interesting process that was required for back-fixing:
find merge base between release branch and mainline, make fix, merge to mainline, merge release branch into fix branch,
increment version file, merge to release branch.
<p>Other tendency that I see as a result of the duplication - the versions are out-of-sync or simply meaningless. Let's
consider two approaches to incrementing version number in a file: before and after the release. First one makes it that
the first commit of the release is a commit that increments the version number. Now, between this commit and the next
release file is out-of-sync, because with each change the state only becomes more and more different from the version
that is described by the file. The second approach is: create release - deploy application and whatnot - and then
increment the version number to what is expected to be the next release. This requires strict management of what changes
will get merged or good fortune-telling skills, otherwise that predicted number is meaningless as you won't be able to
ensure that the release is a major/minor/patch.
<p>Happily for us, most of the VCSes have built-in functionalities to help us control version numbers that are
meaningful in a context of distribution and deployment. They are called <em>tags</em> or rarely <em>baselines</em>. With
them we can mark arbitrary repository states with arbitrary strings that can be later referenced. Usually, they are used
to mark commits that a certain release originated from. Sometimes it might be even the same commit that incremented
version number in a file. We're not doing the last part. Instead we want to tag a commit, and read it from our build,
distribution, deployment, or packaging system.
<p>Some of them support it better, some worse. Luckily, good chunk of them allow for arbitrary logic to be executed, so
we can implement it by ourselves. Additionally, there is a good chance that the VCS provides some kind of helper for
getting the human-readable tag-driven version description. In case of Git there is <b>git-describe</b>(1), which fits
this use case directly. We can just call it from CMake or setup.py and read its output. Very often we may be forced to
generate some full pledged files, so be ready to do it.
<h3>Example CMake Project</h3>
<p>Let's consider a C++ project built by CMake. It is intended to be packaged, but is also meant to support installing
it directly from the repository. The program itself is rather simple - it prints out its version. Every single time:
<pre>
#include <iostream>
#include "version.h"
int main(int, char*[])
{
std::cout << version::full << std::endl;
}
</pre>
<p>The <i>version.h</i> is just a namespace with an extern constant. To provide an actual value for the version number,
let's write a <i>version.cpp.in</i> that will be processed by CMake to generate the actual source that will be added to
the target:
<pre>
namespace version {
const char* full = "@VERSION@";
}
</pre>
<p>The <code>@VERSION@</code> is a pattern that is recognized by CMake's
<a href="https://cmake.org/cmake/help/latest/command/configure_file.html">configure_file</a> which we will use to
generate the actual source code that is intended for compilation just like we planned:
<pre>
add_executable(version-print main.cpp)
git_describe(VERSION)
configure_file(version.cpp.in ${CMAKE_CURRENT_BINARY_DIR}/version.cpp @ONLY)
target_sources(version-print PRIVATE ${CMAKE_CURRENT_BINARY_DIR}/version.cpp)
</pre>
<p>Now, CMake does not support this out-of-box sadly, so you need to implement <code>git_describe</code> (or similar)
yourself or get an external module for it. There is one in
<a href="https://github.com/rpavlik/cmake-modules/blob/main/GetGitRevisionDescription.cmake">Ryan A. Pavlik's
repository</a> and I have implemented
<a href="https://git.ignore.pl/starshatter/tree/cmake/modules/GitDescribe.cmake">one for Starshatter</a> at some point.
They are rather easy and fun to write (although there is a variety of edge cases), but it's still a bit shame that they
are not part of the core CMake. Now, note that one of these "edge cases" might be triggering the reconfiguration of the
output file as <code>configure_file</code> is configuration-time action and changes to the output of the
<code>git_describe</code> may or may not be properly detected. Be wary.
<p>Alternatively, you can consider using a define to, well, define the version number. I use this approach with separate
file that defines the variable for the sake of dependency checks and recompilation.
<h2>Final Thoughts</h2>
<p>Of course, a full-pledged support would be way nicer and stable, but surprisingly, we're not there yet.
<p>Well, some of us are. To contrast the list of bad examples consider Go programming language, which recommends this
method of versioning. Interestingly, it also uses code repositories as a form of package distribution, so any arguments
saying that file with a version is needed because the repository is used as a means of distribution are baseless.
<p>What to take away from this post? Next time when you will start a project, consider keeping meaningful version only
in the VCS. If your building/distribution/whatever-else system does not support it fully out-of-box - try implementing
it. Once you have a working implementation - push it upstream. Who knows, maybe in some time we might be able to have a
consistent support in all across the ecosystem. As for now, back to experimenting, and until next time!
</article>
<script src="https://stats.ignore.pl/track.js"></script>
|
