Skip to content
DOCUMENTATION

Maintenance

UFLinux pins one Alpine release, and keeping that pin healthy is the core of maintenance.

Keep the Alpine branch on a currently supported release with both main and community support. Alpine’s desktop packages largely live in community, whose support ends earlier than main’s — do not assume the kernel’s support lifetime also covers the desktop stack.

  1. Select and review an Alpine stable release and aports commit. Obtain each architecture’s official minirootfs and verify its published signatures and hashes.
  2. Update the versions, archive URLs, SHA-256/SHA-512 values, aports commit and source epoch in config/sources.lock.json. Record immutable commits and actual archive hashes — avoid moving branches and tags as build inputs.
  3. Update the Settings APKBUILD version, source checksum and pkgrel when the workspace changes. Review its Cargo lockfile, minimum Rust and GTK requirements, feature names and labwc compatibility. The desktop shell, Start menu and screencapture tool build from the same workspace and APKBUILD.
  4. When changing Alpine branches, update the branch URLs in the UFLinux APKBUILD and the overlay generator together with the lockfile and publishing path. Recheck the pinned mkimage compatibility patch against the new source.
  5. Update the uflinux package version and the distribution default version. Bump the affected origins’ pkgrel for packaging, flag or patch changes without an upstream version change, and update the exact desktop dependency at the same time.
  6. Run python3 scripts/update-checksums.py after changing local package assets, inspect the diff, run scripts/check.py, then use the full manual build matrix.
  7. Review package, boot and desktop reports before creating the version tag.

ConnMan is a maintained custom package, not a pass-through. Track Alpine’s ConnMan security updates and upstream releases, update its locked source, hash and package revision, and rebase the small iwd credential-delegation patch before release.

Its private driver flag must remain confined to iwd, and authentication or CA and server verification must not be bypassed. Keep the package’s D-Bus rules: group netdev may control ConnMan but may not mutate net.connman.Clock, and that deny has to stay inside the netdev policy because D-Bus applies console and context policies in a fixed order.

Re-run the real PEAP, TTLS and TLS tests — including server-domain mismatch rejection — before publishing a changed network stack. The desktop pins the tested revision so an unrelated official package cannot silently drop the fix.

Boards are pinned in config/devices.json and config/devices.lock.json. Adding a board is a config change plus a package-availability check; nothing in the builder has to learn about it.

The optional Nura repository is a separate distribution. When the Alpine branch is raised, its branch and supported architecture list must be re-verified against the matching Nura release before the device stage can use it again, and board package lists re-checked with scripts/check-packages.py. The Nura index itself is not pinned by hash: postmarketOS rebuilds a release branch’s index regularly, so the branch is the pin and the packages are checked against the branch’s live index.

Replace the reserved [email protected] packager identity with a real maintainer identity before public releases, and set the package project URL to your actual repository.

Dependabot updates pinned GitHub Actions; the pinned actionlint Go source commit is reviewed separately. Changes to runner images, QEMU, firmware, Alpine’s kernel or the desktop shell require the relevant tests to pass again — do not mark failed targets as optional simply to produce a release.

Back up the release private key securely outside both Git and Actions caches. Never commit it or upload .state; that directory contains development keys and temporarily contains the release key during signing. Published metadata includes only public keys and key paths, never private PEM contents.

UFLinux signs with an EC P-256 or P-384 key. apk v2 has no ECDSA signature: apk-tools 3.0.9 recognises only the stream names RSA512, RSA256, RSA and DSA, and selects a trusted key by its filename from a plain public-key PEM, so an X.509 certificate is not accepted as a key. The EC signature is therefore carried in the SHA-256 stream, and the stream name RSA256 describes that digest, not the algorithm. abuild-sign supports this directly — it accepts any OpenSSL-capable private key under -t RSA256.

The key uses the stable filename uflinux.ec.pub, because apk v2 signatures refer to that filename. Keep the same key across routine releases. The apps repository is signed by a separate key of the same role, published as uflinux3.ec384.pub; apk resolves trusted keys by filename, so rotating it means replacing that file on every installed system (uflinux-release ships the bundled copy) and updating the pins in the apps section of config/sources.lock.json.

For a planned rotation, distribute the replacement public key to installed systems through an independently authenticated channel before switching the signing secret. Replacing an already trusted key is an administrator operation; this version does not implement unattended key rollover or dual-signature migration.

Retained old-generation APKs must also be verified with the old key and re-signed with the replacement key before being combined into the new repository. The publisher deliberately fails if those signatures no longer match rather than silently trusting an old snapshot’s bundled key, so keep the prior key and snapshot available during the migration.

For an unexpected compromise, revoke the old key through your authenticated release channel and rebuild affected packages rather than merely re-signing unknown binaries.

Compare like with like: the same source commit, source epoch, rootfs, source archives, Cargo lockfile, toolchain APKs, runtime APKs, build paths and release flags. Development signature streams differ because development keys are ephemeral, so builder.unsigned_digest() compares APK control and payload archives with signature streams excluded — it still includes control metadata and timestamps, and matching only the executable is a weaker check.

Record the baseline ISO size, desktop shell binary size, boot time and desktop RSS from attached records. No unmeasured minimum-memory or performance claim is implied by the word “lightweight”.

Settings changes require cargo fmt and frozen workspace tests. The build calculates the local source checksum; update the Settings version with scripts/settings-source.py --update when needed. The desktop shell reads network, audio and power state only through the Settings backend — do not add a second client for the same hardware. Check the gpu-screen-recorder patch series against the pinned upstream snapshot before upgrading it, and keep the capture tool’s originating-monitor tests in the desktop harness.

Before release, review PSS, idle CPU, mapped-frame latency, binary and ISO size, and physical hardware coverage separately. Only the x86_64 ISO is boot-tested; the other architectures are published without a boot report. An older development ISO’s historical record is not a substitute for validating a changed desktop stack.

Derived from docs/maintenance.md inUFlinux-project/uflinux3(b4f4817). Report documentation problems inUFlinux-project/docs.