Read the Kolibri version from one shared helper across platforms

[rtibblesbot]

Summary

Each platform build read the Kolibri version its own way: pkginfo against an unpacked wheel, the plaintext kolibri/VERSION, or a strip of the sdist tar's filename. The three that have no importable Kolibri at their read point — desktop-app, android, the root pex target — now go through one stdlib-only helper keyed on kolibri/_version.py, the file setuptools-scm writes and the one kolibri.__version__ itself reads. kolibri-server's read is deleted rather than routed: its .deb build already runs inside the workspace uv env, so generate_changelog.py imports the version itself. Per-platform conversions (PEP 440 → Debian, Android versionCode) stay with their platform. The desktop app also gains stage-workspace-whl, mirroring android's stage-workspace-tar, so it can bundle the Kolibri you have checked out instead of a wheel downloaded from a URL.

Excluding the helper's test, the diff is +96/-121. The helper is 33 lines and replaces three bespoke reads; the fourth goes away. pkginfo leaves the desktop app's build extra with it.

References

Fixes #15077. Related: #15072 (release-path migration — where the external installer consumers move).

Acceptance criteria

• One shared helper for the version read; per-platform conversions stay separate. build_tools/read_kolibri_version.py is the single reader of kolibri/_version.py for the platforms that cannot import it: android (app/build.gradle:113), desktop-app (Makefile:23) and the root pex target (Makefile:229). kolibri-server can import it, so it does — generate_changelog.py:52, the same read platform-debian-server-release.yml:35 already used — and its tar-filename strip is gone.
• desktop-app has stage-workspace-whl mirroring android's stage-workspace-tar. platforms/desktop-app/Makefile:80.
• Stale clone/venv/get-tar instructions gone from platforms/android/README.md. grep -n "get-tar\|kolibri-installer-android\|uv venv\|--extra build\|0\.17\.0" platforms/android/README.md returns nothing.

(Ticked here and in this issue comment rather than in the issue body — this account lacks UpdateIssue permission on learningequality/kolibri.)

Deviations from the issue spec

• kolibri/VERSION is not retired, though the issue thread asked for it once android stopped reading it. It has no reader in this repo, but kolibri-installer-debian untars the sdist we publish and reads it out of that tar (Makefile:18-21 at v0.16.1), and this repo calls that installer from pr_build_kolibri.yml:24-30 and release_kolibri.yml:78. Deleting the file turns the PR deb job red, taking zip, pi_smoke_test and server_smoke_test with it. Makefile:204 records this; please sanity-check the pins. (The external kolibri-installer-android reads it too, but no workflow here calls that repo any more — platforms/android/ builds both the PR and the release APK — so the retention rests on the one Debian consumer.)
• raspberry-pi keeps its .deb-filename parse (platforms/raspberry-pi/Makefile:62). The .deb it packages is the correct artifact there — the version is already Debian-converted and no _version.py exists at Pi-image build — so the helper would mean reading a version it does not ship.

Open question

• No released sdist contains _version.py, so a workflow_dispatch of platform-android-build_apk.yml with a pre-monorepo release tar-url now fails at Gradle configure. The reusable-call path from pr_build_kolibri.yml is unaffected (same-commit tar). Acceptable, or should the read fall back?

platforms/desktop-app/README.md:44 still says git clone kolibri-app.git. Its build section is rewritten here for stage-workspace-whl, but that pre-monorepo clone step is left — the same staleness AC3 fixed for android, and AC3 names only the android file. Happy to fold it in.

AI usage

Used Claude Code to implement the plan agreed in the issue thread, writing the version-read helper test-first and scoping the kolibri/VERSION question against the external installer repos before deciding not to delete it. Verified with the test/ suite, prek run --all-files, a real Gradle configure against a workspace-built sdist, an end-to-end make stage-workspace-whl, and a round-trip of the read through generate_changelog.py's Debian conversion.

---

@rtibblesbot's comments are generated by an LLM, and should be evaluated accordingly

How was this generated?

• Ran pre-flight CI checks (lint, format, tests) and verified all pass
• Rebased onto the target branch and resolved any conflicts
• Reorganized commit history into clean, logical commits
• Audited the diff to ensure only issue-relevant files are changed
• Built PR body from the repository's PR template with evidence blocks

🟡 Waiting for feedback Last updated: 2026-07-30 06:01 UTC

[github-actions]

Build Artifacts

Asset type	Download link
PEX file	kolibri-0.19.6.dev2379_g6790f9e40.d20260730.pex
Windows Installer (EXE)	kolibri-setup-0.19.6.dev2379+g6790f9e40.d20260730-unsigned.exe
Debian Package	kolibri_0.19.6.dev2379+g6790f9e40-0ubuntu1_all.deb
Debian Package	kolibri-server_0.19.6~dev2379+g6790f9e40-0ubuntu1_all.deb
Mac Installer (DMG)	kolibri-0.19.6.dev2379+g6790f9e40.d20260730.dmg
Android Package (APK)	kolibri-0.19.6.dev2379+g6790f9e40.d20260730-debug.apk
Raspberry Pi Image	kolibri-pi-image-0.19.6.dev2379+g6790f9e40.zip
TAR file	kolibri-0.19.6.dev2379+g6790f9e40.d20260730.tar.gz
WHL file	kolibri-0.19.6.dev2379+g6790f9e40.d20260730-py3-none-any.whl

Smoke test screenshot

Download screenshot

[rtibbles]

My first impression of this from a skim is that this is incredibly verbose for what it achieves and rather than consolidating things and reducing code duplication it seems to add rather a lot of code.

[rtibblesbot]

Fair, and mostly deserved. Pushed a trim in a78fd26 and cut the PR body down too.

The helper was carrying two readers nobody calls. No caller passes an sdist tar — android extracts it and hands over the tree — so the tarfile branch and its two tests went, along with argparse (one positional arg), the three private _read_* wrappers, and the error-path tests for entities that no longer exist. It is now one 45-line file: read kolibri/_version.py out of a directory or a .whl, ast-parse the __version__ assignment. 92 → 45 lines, tests 129 → 66. I also trimmed the comments at every call site and dropped the eight-line directive GradleException in app/build.gradle for a three-line comment.

On the volume, with the helper's test set aside the diff is now +112/-98 — so the consolidation is close to line-neutral, and the test file is most of what is left. The _version.py read itself replaces four bespoke ones (pkginfo.Installed, a VERSION-file read, a tar-filename strip, pkginfo.Wheel), and pkginfo drops out of desktop-app's build deps.

Two adds are not consolidation and I should flag them as such: stage-workspace-whl (11 lines) is AC2, not deduplication; and the one-line guard in desktop-app's needs-version exists because $(shell) swallows the helper's exit status, so a failed read would otherwise pass an empty version into the build.

Two places I could go further if you want it — say the word rather than my guessing:

1. Drop the debian-server CI version step entirely. That job runs uv sync --all-packages, so generate_changelog.py's existing import kolibri fallback already resolves the same _version.py. The step and its env: block are ~9 lines that only make the version explicit in the log. Removing them means debian-server stops calling the shared helper — which reads either as the right per-platform mechanism or as a hole in AC1, and that is your call, not mine.
2. Drop the .whl branch (4 lines) and have pex read the repo tree instead of each wheel. Same answer in practice, since pex runs right after dist in the same tree; I kept it so the pex filename comes from the artifact it names.

[rtibbles]

This is more concise, but I'm confused by the changes to kolibri-server, unless I'm just missing something?

[rtibbles]

I don't understand why _version.py can't just be imported? It's a standalone file.

[rtibblesbot]

Agreed — it can, and now it is executed rather than parsed. The ast walk is gone:

    if path.endswith(".whl"):
        with zipfile.ZipFile(path) as wheel:
            source = wheel.read(VERSION_MODULE)
    else:
        with open(os.path.join(path, VERSION_MODULE), "rb") as version_module:
            source = version_module.read()
    # _version.py imports nothing and only assigns, so running it is the same as
    # importing it -- which is not an option for a member of a wheel.
    namespace = {}
    exec(source, namespace)
    return namespace["__version__"]

The one reason it is exec on the source rather than an import of the path: the pex target hands over a .whl, and a member of a zip cannot be imported without unpacking it — so reading the text and running it is the single form that covers both a tree and a wheel. The helper is 36 lines now, and the two tests that only pinned the parse (quoting style, version-alias-only) went with it, leaving the two that assert the actual interface: read from a tree, read from a wheel.

[rtibbles]

OK, let's tidy up the commit history ready for merge here, this doesn't need to be more than a few commits.

[rtibblesbot]

Squashed to three commits, one per acceptance criterion — the tree is byte-identical to the previous head:

• 53b5198 Read the Kolibri version from _version.py with one shared helper (helper + test, pex, android, kolibri-server, the kolibri/VERSION comments)
• a80a4b8 Stage and read the desktop app's Kolibri whl from the workspace (needs-version + stage-workspace-whl, pkginfo dropped)
• 4fff366 Drop pre-migration setup from the Android README

git diff <old-head> HEAD is empty; pytest test/ 26 passed.