From 1cc12b86dfb036ea4ee5100ca6653d3c3b054195 Mon Sep 17 00:00:00 2001 From: "Danilo M." Date: Tue, 25 Aug 2026 17:32:53 +0200 Subject: feat: number each build of a dev tree The version alone cannot tell one build of an unreleased X.Y.Z from another, and the user rebuilds and hand-tests unreleased builds daily. They chose a counter over a git description: what they want to know is that the binary is newer than the one they were running, not which commit it came from. QTMAILDIR_BUILD_NUMBER is a cmake option, ON by default, that runs cmake/BuildNumber.cmake as a build step to increment a counter and write buildnumber.h. It had to be a build step: configure_file runs once per cmake run, so a counter interpolated into version.h.in would sit still across exactly the rebuilds this exists to distinguish, which is why version.h.in includes a second generated header rather than carrying the number itself. Two macros, and the split is load-bearing. QTMAILDIR_VERSION stays a clean X.Y.Z and keeps the window title, applicationVersion and anything that might ever compare versions; QTMAILDIR_VERSION_DISPLAY carries the number and goes to the three surfaces the user picked, --version and --help, the About dialog, and the placeholder pane. The window title was offered and declined, since the number would then be in every screenshot. The counter lives in the build directory and is not tracked, so it cannot conflict on a pull or leave the tree dirty; a fresh build directory restarts at 1, which is honest, because it is a different build tree. A release passes -DQTMAILDIR_BUILD_NUMBER=OFF and the header is written empty. The SlackBuild in the my-slackbuilds repo needs that flag and is a separate commit there. Verified by running it, since none of this is reachable from a C++ test: three consecutive builds reported build 2, 3 and 4, and a separate Release configure with the option OFF reported a clean 0.27.0. Passing the flag to a tree that does not have the option yet is an unused-cli warning and exit 0, so the SlackBuild change is safe before 0.28.0 ships. The suite is 37 of 38, the one failure being item 136 on an unrelated path. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01HFuRPtzFrSxCQjFk6tq7gD --- .../2026-08-03-post-0.1.0-usability-closed.md | 78 ++++++++++++++++++++++ 1 file changed, 78 insertions(+) (limited to 'docs/superpowers/plans/2026-08-03-post-0.1.0-usability-closed.md') diff --git a/docs/superpowers/plans/2026-08-03-post-0.1.0-usability-closed.md b/docs/superpowers/plans/2026-08-03-post-0.1.0-usability-closed.md index ae6443d..b9eb8cf 100644 --- a/docs/superpowers/plans/2026-08-03-post-0.1.0-usability-closed.md +++ b/docs/superpowers/plans/2026-08-03-post-0.1.0-usability-closed.md @@ -8034,3 +8034,81 @@ ever be empty. That is real, independent of this item, and outside this repository. **Size: XS.** Done. + +## 167. No way to tell one build of an unreleased version from another + +**Observed (user, from the notes):** "we should add a dev build number to be +pushed everytime we rebuild after a fix, so that I can verify if I'm in the +correct app version." The note has sat unrecorded through several sessions; +the 2026-08-25 reconciliation is the first to pick it up. + +**Cause (verified in the code, 2026-08-25.)** The version lives in exactly one +place, `project(qtmaildir VERSION ...)`, and `src/version.h.in` interpolates +`@PROJECT_VERSION@` and nothing else. That is correct for a release and says +nothing between two of them: the string moves only when the release procedure +bumps it, so every rebuild of `0.27.0` reports `0.27.0`. The status table above +shows why it bites in practice, since most closed items since 0.27.0 read +"unreleased" and the user hand-tests each one against a binary they rebuilt +themselves. + +Both surfaces that show the version take it from the same macro, so whatever is +added reaches them at once: the window title (`mainwindow.cpp:939`), the About +dialog (`mainwindow.cpp:2449`), the placeholder pane (`messageview.cpp:547`), +`--version` and `--help` (`main.cpp`). + +**Approach.** Needs a DECISION before any code, because the two candidates fail +in opposite directions. + +A git description (`git describe --always --dirty`, or the short hash) is +accurate and self-explaining: it names the commit the binary was built from, and +a reviewer can check out exactly that. Its cost is that CMake computes it at +CONFIGURE time, so a build after a new commit reports the previous hash unless +the configure step is made to re-run, which is a custom command with a dependency +on `.git/HEAD` and the packed refs, and is the part that usually ships subtly +wrong. + +A monotonic counter always moves and needs no git, but it means nothing on its +own: build 412 does not say which fix is in it, and it differs between the user's +machine and any other, so it cannot be quoted in a report. + +**Constraints.** A release build must keep printing a clean `X.Y.Z`, since the +SlackBuild in the `my-slackbuilds` repo builds from the release tarball where +there is no git checkout at all, and the release procedure checks +`./build/src/qtmaildir --version`. Whatever is added is therefore an addition to +the string in a dev build and absent in a release one, not a change to the +version itself. + +**Decision (user, 2026-08-25): the counter.** The git description was +offered as the recommendation and was not chosen; what the user wants is to +know a rebuild happened, not which commit it was. + +**Built 2026-08-25, unreleased.** `QTMAILDIR_BUILD_NUMBER`, a cmake option ON +by default, runs `cmake/BuildNumber.cmake` as a build step: it increments a +counter and writes `buildnumber.h`, which `version.h` includes. +`QTMAILDIR_VERSION_DISPLAY` is `X.Y.Z build N` when that macro is defined and +plain `X.Y.Z` when it is not. + +Two macros, not one, and the split is the load-bearing part. +`QTMAILDIR_VERSION` stays clean and keeps the window title, `applicationVersion` +and anything that might ever compare versions; `QTMAILDIR_VERSION_DISPLAY` goes +to the three surfaces the user picked: `--version`, `--help`, the About dialog +and the placeholder pane. The window title was offered and declined, since the +number would then sit in every screenshot. + +**The counter had to be a BUILD step, not `configure_file`.** That is the whole +reason this is not two lines: `configure_file` runs once per cmake run, so a +counter interpolated into `version.h.in` sits still across exactly the rebuilds +this item exists to distinguish. `version.h.in` therefore includes a second +generated header rather than carrying the number itself. + +The counter file lives in the build directory and is not tracked, so it cannot +conflict on a pull or dirty the tree; a fresh build directory restarts at 1, +which is honest, because it is a different build tree. A release build passes +`-DQTMAILDIR_BUILD_NUMBER=OFF` and the header is written empty. + +**Verified by running it**, since none of this is reachable from a C++ test: +three consecutive builds reported `build 2`, `build 3`, `build 4`, and a +separate Release configure with the option OFF reported a clean `0.27.0`. The +suite is 37 of 38, the one failure being item 136 on an unrelated path. + +**Size: XS**, as sized. -- cgit v1.2.3