From 5a9fab1cc3ce051fac190788d507c7580c5f9d07 Mon Sep 17 00:00:00 2001 From: bong-water-water-bong Date: Sun, 8 Nov 2026 02:03:13 -0400 Subject: [PATCH] docs: the upgrade path and what each tool does with a downgrade, measured (Refs #1279) #1407 measured "does this set take a weekly tag" for the kernel/driver set and noted that the engine set maps the tag into the version instead. Nobody had measured the engine set's *upgrade* path, which is the thing a user does every week, so this is that: the rc-2026-11-07-c32 payload built at three versions and installed over itself in each family's own container. 2026.44 -> 2026.45 apt-get install rc 0, dnf rc 0, pacman -U rc 0 payload replaced in place: 75 files before and after, in each 2026.44 -> 2026.45~c32 -> 2026.45 deb and rpm: the candidate installs over the previous release, and its release installs over the candidate 2026.44 -> 2026.45c32 -> 2026.45 pacman: the same, with the Arch spelling The downgrade half came out of the same runs and is worth writing down rather than discovering: apt refuses a downgrade (it needs --allow-downgrades), pacman warns and does it, and dnf is the surprising one - `dnf install ./old.rpm` DOWNGRADES the package silently (rc 0), while `dnf upgrade ./old.rpm` refuses with "Package 1bit-engine.x86_64 is already installed. Nothing to do." (rc 0). Both measured on the same container. That is dnf's semantics for a local file, not this package's, so the doc says to use `upgrade` rather than change anything about the packaging. One row in the measured table and one paragraph in the Fedora/openSUSE section, which is where a reader looks for the command. Refs #1407 as the kernel-set counterpart. Checks: tools/copyright.py --check rc 0. One file, +9 lines, docs only. --- docs/install-any-distro.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/install-any-distro.md b/docs/install-any-distro.md index 36879d9e9..744217c0b 100644 --- a/docs/install-any-distro.md +++ b/docs/install-any-distro.md @@ -122,6 +122,14 @@ sudo dnf install ./1bit-engine--1.x86_64.rpm # Fedora sudo zypper install ./1bit-engine--1.x86_64.rpm # openSUSE Tumbleweed ``` +**Upgrading.** `sudo dnf upgrade ./1bit-engine-.rpm` (zypper: `sudo zypper update ./…rpm`). Use +`upgrade`, not `install`: for a local file, `dnf install ./…rpm` performs whatever the file says — an +older file **downgrades** the package silently (measured), while `dnf upgrade` of an older file refuses +with `already installed. Nothing to do.`. On Debian and Ubuntu `apt-get install ./…deb` refuses a +downgrade outright, and on Arch `pacman -U` warns and does it. The version scheme makes all of them an +upgrade in the ordinary case: a weekly release is `2026.45`, the release before it `2026.44`, and a +candidate of it `2026.45~c32` / `2026.45c32`, which sit between the two. + The recipe (`packaging/rpm/1bit-engine.spec`) declares no dependencies: rpm reads the ELF files the package ships and requires the sonames that come from outside it (`libcrypto.so.3`, `libgomp.so.1`, `libzstd.so.1`, `libpcre2-8.so.0`, `libstdc++.so.6`, `libm.so.6`), which dnf resolves to `openssl-libs`, `libgomp`, @@ -385,6 +393,7 @@ registry model, since this Lemonade version has no local-file registration): | **the package's payload serves on the GPU** | strixhalo, the Fedora `.rpm` unpacked with `rpm2cpio` (so exactly the files the package installs), `1bit serve -m Qwen3-0.6B-Q4_K_M.gguf --device hrx --no-strict-device`, two chats | `1bit serve: HRX: HSA runtime …/_rocm_sdk_core/lib/libhsa-runtime64.so.1 sha256 21a66824…` — the runtime the package ships, not the box's — then `Qwen3-0.6B-Q4_K_M on hrx`, health `200`, and `request /v1/chat/completions -> hrx status 200 in 202.5 ms | prompt 16 completion 16 79.0 tok/s`; a second chat with `max_tokens: 200` came back `content: "5"` (109 completion tokens, 69.1 tok/s). The first one's content was empty because Qwen3 spends the opening tokens on its thinking trace, so a 16-token budget never reaches the answer. Both this model and `Qwen3-4B-Q4_K_M` are refused first by strict placement (`"embd" is GET_ROWS f32 … 1 of 986 nodes off HRX`), which is why the runs pass `--no-strict-device` | | **the release proves its own packages** | `scripts/pack-proof.sh `, wired into `scripts/weekly.sh`'s package stage, 2026-11-07, on the `rc-2026-11-06-c31` artifacts | 6/6 rows PASS: the `.deb` installed in `ubuntu:26.04`, the `.rpm` in both `fedora:latest` and `opensuse/tumbleweed`, the pacman package in `archlinux:latest` (each asked `1bit-engine --version` = `1bit 0.0.1`, made to run the shim = `version: 1 (32559003)`, then removed with nothing left), the tarball unpacked as root the way this page says, and the four compared as root (paths, modes, owner `0:0`, sizes, sha256). Handed the pre-fix tarball — uid 1000, a `./` member, the filesystem directories — the same harness fails **4/6**, naming the 151 members that are not root's and the payload difference, so the row is a check and not a claim | | **a candidate package installs over the previous release** | `scripts/pack-version.sh` + `tests/pack_version_test.sh` (ctest `pack_version`), measured with each family's own comparator, 2026-11-07 | a candidate tag has to map to a version that sorts *above* the previous release and *below* the release it precedes, or installing it is a downgrade that apt and rpm refuse. `rc-2026-11-07-c32` packs as `2026.45~c32` (deb, rpm, tarball) and `2026.45c32` (pacman): `2026.44 < 2026.45~c32 < 2026.45` with `dpkg --compare-versions` and with rpm's `labelCompare` in `fedora:latest`, and `2026.44 < 2026.45c32 < 2026.45` with pacman's `vercmp` in `archlinux:latest`. The mapping this replaced read the tag as `2026.11.07.c32`, which is *below* every release since week 11 (`dpkg: 2026.11.07.c32 < 2026.44`) — the bug the #1368 review found, kept as a row in the test | +| **a newer package upgrades an installed one, in all three families** | 2026-11-08, clean containers, the `rc-2026-11-07-c32` payload built at three versions (`2026.44`, the candidate, `2026.45`) | `2026.44 → 2026.45`: `apt-get install` rc 0, `dnf` rc 0, `pacman -U` rc 0 — and the payload is replaced in place, 75 files before and after, in each. And the candidate path the #1368 review was about: `2026.44 → 2026.45~c32 → 2026.45` (deb, rpm) and `2026.44 → 2026.45c32 → 2026.45` (pacman), so a candidate installs over the previous release and its release installs over the candidate. Downgrades are the tool's business and they differ, measured on the same three containers: **apt refuses** (it needs `--allow-downgrades`), **`dnf install ./old.rpm` downgrades silently** while **`dnf upgrade ./old.rpm` refuses** (`already installed. Nothing to do.`), and **pacman warns and downgrades** | | a stock Lemonade takes a backend binary from `hrx_bin` / `LEMONADE_HRX_HRX_BIN` | extracted PPA deb `2026.44.1~26.04` on the dev box, isolated cache/config | `llamacpp-hrx` backend `installable` → `installed`, both forms, with no fork and no patch | | the same recipe, both packages side by side | clean `ubuntu:26.04` container: PPA `lemonade-server` + this `.deb` | `lemond 2026.44.1` starts, `1bit-engine --version` and the shim run; the recipe's backend state is hardware-gated there (`unsupported: Unsupported GPU`), so the end-to-end chat is the hardware row below | | the shim is the engine's own wrapper | `1bit/lemonade-hrx` from this repo's package (`scripts/package-linux.sh`) | it runs `1bit serve --print-backend-env` and then `exec`s the engine with serve's environment and defaults; `lemonade-bin/llama-server` is a symlink to it |