docs: installing from a file pins the package, and apk upgrade then says nothing

[raspbeguy]

Found while testing the 3.0.0 upgrade path from the 2.5.1 release artifact.

apk add <file>.apk pins, silently

It writes a checksum-pinned entry into /etc/apk/world:

uapi><Q1zxo621V/TEoIKMwszOveLq/th2E=

That holds the package to one exact build. apk upgrade then leaves uapi alone with no error and no mention in its output; the version simply never moves. On a box in that state, with the feed serving 3.0.0 and apk policy naming it:

apk upgrade --simulate   ->  OK: 42.6 MiB in 294 packages   (nothing to do)
apk upgrade              ->  still uapi-2.5.1-r1

After apk add uapi, which replaces the pinned entry with a bare uapi:

apk upgrade  ->  (1/1) Upgrading uapi (2.5.1-r1 -> 3.0.0-r1)
                 mount moves to /api/v3, /api/v2 now 404, healthz reports 3.0.0

This matters because installing from a file is what we tell people to do for every RC (docs/release-process.md, the RC release notes) and for any older release now that the feed carries one version. Anyone who dogfoods an RC and later expects apk upgrade to bring them back to stable stays on the RC indefinitely, with nothing in the output to explain it.

grep uapi /etc/apk/world distinguishes the two states, and both README and docs/installation.md now say so.

A false claim about the feed, in the same file

docs/installation.md said:

Every stable release stays available indefinitely, so pinning works: apk add 'uapi<3.0.0' holds a client to the v2 wire contract

The feed's index is rebuilt from the latest stable tag on every publish, so the previous release stops resolving as soon as a new one ships. uapi-2.5.1-r1.apk returned 404 from the feed within minutes of 3.0.0 publishing, while uapi-3.0.0-r1.apk returned 200. A < 3.0.0 constraint finds nothing, and an exact pin only works while that build is the current one.

The same sentence lived on the website's install page and was corrected there yesterday; this is the copy in the repo. Older releases do stay on the GitHub Releases page permanently, which is the supported way back, and the text now says that instead.

Does this change the wire surface? No, documentation only.

Was it verified against a real device, or only by CI? On a device, both directions: pinned world blocking the upgrade, then a bare world entry letting it through and moving the mount from /api/v2 to /api/v3 with the conffile preserved. make lint and 1234 unit tests pass.

Was LuCI checked? Not applicable; this is apk behaviour, not a uci surface.

Worth noting what this does not claim: apk's own reasoning was inferred from /etc/apk/world and the observed behaviour, not read from apk-tools source, which is not in the SDK feeds. The commands and their effects are measured; the explanation for why apk chooses that is a reading of the evidence.