F23.2 — A Python tool installs from a branch, a tag or a commit
| State | Closed |
| Parent | E23 |
| Iteration | Release 9 |
| Start Date | 2026-11-17 |
| Closed Date | 2026-11-17 |
| Predecessors | F22.6 |
| Source | kiln F7.7, 2026-11-14 |
Stories: 3 Closed
| Story | State | Depends on |
|---|---|---|
S23.2.1 — install --ref installs a commit of a GitHub repository |
Closed (2026-11-17) | — |
S23.2.2 — upgrade, status and doctor follow the recorded ref |
Closed (2026-11-17) | S23.2.1 |
S23.2.3 — PythonTool builds a runnable command |
Closed (2026-11-17) | — |
<tool> self install --ref <ref> installs any branch, tag or commit of a tool's
GitHub repository, with no GitHub release needed. A Python tool's install holds
a working command. The install state records what was asked for and what was
installed, so status, upgrade and doctor report and act on it.
Context
Seen with kiln, the first tool to run the lifecycle outside its tests:
GitHubReleases.latest()readsreleases/latest, and--versionnames the tagv<version>. A tool with no release, such as kiln beforev0.1.0, cannot be installed, and neither can a branch. The version is also the directory name underversions/, which must be one path segment, andfeature/v1is not.ToolProduct.buildcopies the release's source tree. For a Python tool that tree has nobin/<tool>, so the product'sLink("bin/<tool>", "bin/<tool>")points at nothing. kiln's own product and everypython-toolrepository kiln generates declare exactly that link.state.jsonholdsversionandschema_version, anddoctorcompares the version directory's name with the running version. An install from a commit has no release version to compare.
F22.6 reworks the install transaction (prepare, then mutate). This feature follows it so that the ref resolution and the uv build land in its prepare phase.
Design
-
GitHubReleasesalso resolves refs; there is no separate refs class:resolve(ref)returns the 40-character commit SHA fromGET /repos/{repo}/commits/{ref}, which accepts a branch, a tag or a SHA;download_commit(sha, destination)fetches/{repo}/archive/{sha}.tar.gz;latest()stays the newest release.
-
install --ref <ref>, a new option on theinstallverb, exclusive with--versionand--archive. A ref install's version directory is named for the commit's first 12 characters. -
state.jsongainsref(as asked: the branch, the tag or the SHA, and for a--versioninstall the tag) andcommit(when known). It gainsversion, the package version the build reports, from the built tree'spyproject.toml[project] version. An install recorded before this feature reads as a release install whoserefisv<version>. -
upgradere-resolves a ref install's recordedref. When the commit is unchanged, the result isalready-current. A release install moves to the newest release, as it does now. -
statusprintsinstalled: <version> (<ref> @ <commit 12>)for a ref install, and its--jsonoutput carriesrefandcommit. -
doctor'sinstall.version-mismatchcompares the running version withstate.json'sversion, not with the directory name. -
PythonTool(ToolProduct), inrn_forge.tooling.install:- its
buildrunsuv tool install <release_root>withUV_TOOL_DIR=<version_dir>/toolandUV_TOOL_BIN_DIR=<version_dir>/bin; - its default
artifacts()isLink("bin/<name>", "bin/<name>"); uvmissing from PATH is anAppExceptionraised before anything is written, by itspreflight(), aToolProducthook thatinstallcalls first and that does nothing by default.
uvis a program on PATH, not a Python dependency, and no dependency is added. - its
S23.2.1 — install --ref installs a commit of a GitHub repository
State: Closed (2026-11-17)
Acceptance:
GitHubReleases.resolveanddownload_commitare tested against a fake HTTP server, for a branch, a tag and a SHA, and for a ref that does not exist, which is anAppExceptionnaming the ref that leaves the home untouched.install --refwith--versionor--archiveis a usage error.- A ref install's directory is
versions/<commit 12>, andstate.jsonholdsversion,ref,commitandschema_version. This is a test. - A
state.jsonwithoutrefreads as a release install, andstatusanddoctorreport it without error. This is a test.
S23.2.2 — upgrade, status and doctor follow the recorded ref
State: Closed (2026-11-17) · Depends on: S23.2.1
Acceptance:
upgradeof a branch install moves to the branch's new commit, and returnsalready-currentwhen the commit has not moved.upgradeof a release install moves to the newest release. There is one test for each.statustext and--jsoncarryrefandcommitfor a ref install.doctorreportsinstall.version-mismatchfromstate.json'sversion. A ref install whose package version matches the running one reports none.
S23.2.3 — PythonTool builds a runnable command
State: Closed (2026-11-17)
Acceptance:
PythonTool.buildfrom a minimal Python tool tree with one console script leaves<version_dir>/bin/<name>. Afterinstall,$RNF_HOME/bin/<name>runs throughcurrent. This is a test that needsuvand is skipped without it.uvmissing from PATH fails the install beforeversions/is written. This is a test.uninstallremoves the uv tool environment with the version directory, and nothing is left under$RNF_HOME. This is a test.- The lifecycle guide (
packages/rn-forge-tooling/docs/guides/lifecycle.md) and the install reference cover--ref, the newstate.jsonfields andPythonTool. rn-forge-toolingis released to pypi.org with F23.2, and kiln's upstream pin row for F23.2 can then readyes.
Acceptance
Not scriptable: kiln F7.7's S7.7.4 run installs kiln from feature/v1 and from
a commit, upgrades it, cleans it up and uninstalls it, and records the home and
state.json at each step.
Considered and rejected
- Install from GitHub releases only. It needs a release before a tool can be tested as installed, and kiln's release waits on that test.
- Name a ref install's directory after the ref. A branch name is not one path segment, and a branch moves, so the same name would hold different commits.
uv tool installinto uv's own tool directory. That leaves nothing for the home'sversions/andcurrentto manage, socleanup, the rollback anddoctorwould no longer describe the install.