![screenshot of the first page of my “Stamp It! All Programs Must Report Their Version” blog post:
Recently, during a production incident response, I guessed the root cause of an outage correctly within less than an hour (cool!) and submitted a fix just to rule it out, only to then spend many hours fumbling in the dark because we lacked visibility into version numbers and rollouts… 😞
This experience made me think about software versioning again, or more specifically about build info (build versioning, version stamping, however you want to call it) and version reporting. I realized that for the i3 window manager, I had solved this problem well over a decade ago, so it was really unexpected that the problem was decidedly not solved at work.
In this article, I’ll explain how 3 simple steps (Stamp it! Plumb it! Report it!) are sufficient to save you hours of delays and stress during incident response.
[…]](https://cdn.bsky.app/img/feed_thumbnail/plain/did:plc:eb3563jmh2vjnrlkwujxqdwg/bafkreibmyjp2vprkz3vd4quze4ptlmt5sgz32mjc2bycogzwu6ps2odxpq)
screenshot of the first page of my “Stamp It! All Programs Must Report Their Version” blog post: Recently, during a production incident response, I guessed the root cause of an outage correctly within less than an hour (cool!) and submitted a fix just to rule it out, only to then spend many hours fumbling in the dark because we lacked visibility into version numbers and rollouts… 😞 This experience made me think about software versioning again, or more specifically about build info (build versioning, version stamping, however you want to call it) and version reporting. I realized that for the i3 window manager, I had solved this problem well over a decade ago, so it was really unexpected that the problem was decidedly not solved at work. In this article, I’ll explain how 3 simple steps (Stamp it! Plumb it! Report it!) are sufficient to save you hours of delays and stress during incident response. […]
![screenshot of the last page of my “Stamp It! All Programs Must Report Their Version” blog post:
Conclusion: Stamp it! Plumb it! Report it!
My argument is simple:
Stamping the VCS revision is conceptually easy, but very important!
For example, if the production system from the incident I mentioned had reported its version, we would have saved multiple hours of mitigation time!
Unfortunately, many environments only identify the build output (useful, but orthogonal), but do not plumb the VCS revision (much more useful!), or at least not by default.
Your action plan to fix it is just 3 simple steps:
Stamp it! Include the source VCS revision in your programs.
This is not a new idea: i3 builds include their git-describe(1) revision since 2012!
Plumb it! When building / packaging, ensure the VCS revision does not get lost.
My “VCS rev with NixOS” case study section above illustrates several reasons why the VCS rev could get lost, which paths can work and how to fix the missing plumbing.
Report it! Make your software print its VCS revision on every relevant surface, for example:
[…]](https://cdn.bsky.app/img/feed_thumbnail/plain/did:plc:eb3563jmh2vjnrlkwujxqdwg/bafkreie44kyf3bi262fe6se54yj26txtvxmx6dwqk6jrtqhum7a7is2gs4)
screenshot of the last page of my “Stamp It! All Programs Must Report Their Version” blog post: Conclusion: Stamp it! Plumb it! Report it! My argument is simple: Stamping the VCS revision is conceptually easy, but very important! For example, if the production system from the incident I mentioned had reported its version, we would have saved multiple hours of mitigation time! Unfortunately, many environments only identify the build output (useful, but orthogonal), but do not plumb the VCS revision (much more useful!), or at least not by default. Your action plan to fix it is just 3 simple steps: Stamp it! Include the source VCS revision in your programs. This is not a new idea: i3 builds include their git-describe(1) revision since 2012! Plumb it! When building / packaging, ensure the VCS revision does not get lost. My “VCS rev with NixOS” case study section above illustrates several reasons why the VCS rev could get lost, which paths can work and how to fix the missing plumbing. Report it! Make your software print its VCS revision on every relevant surface, for example: […]
New blog post 🥳
Stamp It! All Programs Must Report Their Version
In this article, I’ll explain how 3 simple steps (Stamp it! Plumb it! Report it!) are sufficient to save you hours of delays and stress during incident response.
Read more: michael.stapelberg.ch/posts/2026-0...
#nix #golang #linux
