LordOS — a free, fast and secure GNU/Linux distribution based on Debian, with its own desktop environment: display server and Wayland compositor in C, a React UI engine on QuickJS, and private native apps.
Releasing LordOS
How a LordOS version goes from main to a GitHub release.
The releases page is the project's public changelog: every release is documented in full, from
CHANGELOG.md.
Versions
- Semantic Versioning. Until 1.0, every release is a beta.
- The CHANGELOG version and the git tag carry the pre-release suffix:
0.8.0-beta, tagv0.8.0-beta. package.jsoncarries the version without the suffix ("version": "0.8.0") and the channel separately ("lordos": {"channel": "beta"}; empty for a stable release). The file names use that version:lordos_0.8.0_amd64.deb,lordos-live-0.8.0-amd64.iso,lordos-0.8.0-rpi5-arm64.img.xz.- An update of a published version that only fixes it or completes it (no features planned for
the next version) adds a fourth number:
0.8.4.1-betaafter0.8.4-beta, package0.8.4.1. dpkg sorts it after0.8.4and before0.8.5, so Store → Updates and apt offer it like any version. (Semantic Versioning has no fourth number; LordOS uses it only for these.) - The release title is
LordOS <version>, for exampleLordOS 0.8.0-beta. - Every beta (any version with a suffix) is published as a pre-release. Only a version without a suffix is a normal release.
The changelog
CHANGELOG.md follows Keep a Changelog 1.1.0:
- Changes go under
## [Unreleased]as they land, in### Added,### Changed,### Deprecated,### Removed,### Fixedand### Security(LordOS also uses### Known issues and limitations,### Upgradingand### Verifying). - Bullets are written for users first (what you can do now, what was wrong), then technical detail
where useful, with links to the docs (
docs/…). - Only what the code and the docs show. Measured numbers come from the test docs (ISO.md, RASPBERRY.md…).
- The wording rules apply: a free GNU/Linux distribution based on Debian with its own desktop environment; generic names, no commercial brand names; English only.
Steps
Changelog. Rename
## [Unreleased]to## [<version>] - <YYYY-MM-DD>(the release date), add a new empty## [Unreleased]above it, and update the link references at the bottom:[Unreleased]: https://github.com/lordbasex/LordOS/compare/v<version>...HEAD [<version>]: https://github.com/lordbasex/LordOS/compare/v<previous>...v<version>Also bump
package.json(version,lordos.channel) and commit both.Tag.
git tag -a v<version> -m "LordOS <version>"on that commit, and push the tag.Sign the system code, then build from the tag.
- On the maintainer's machine (where the release key lives):
npm run build, thentools/release/sign-code.sh. It regeneratescode-manifest.json(the SHA-256 of every theme bundle, the app host and the system apps) and writescode-manifest.sigwith the release key, checked againsttools/release/lordos-release.pub.pem(SIGNING.md, "Verified system code"). The bundles are the same for every architecture: one signature serves all the images. - Send the tree, with both files, to the build VMs (never the key). Build lord-server as a release:
make -C server RELEASE=1(it only runs code signed with the release key, with no development mode). - Build the ISO on the build VM (
sudo REQUIRE_SIGNED_CODE=1 tools/iso/build.sh, ISO.md), the Raspberry Pi 5 image (sudo RELEASE=1 REQUIRE_SIGNED_CODE=1 tools/rpi/build-img.sh, RASPBERRY.md) and the.debfor amd64 and arm64 (REQUIRE_SIGNED_CODE=1 tools/iso/mkdeb.sh).mkdeb.shputscode-manifest.jsonandcode-manifest.sigin/usr/lib/lordos/and runslord-server --check-codeon the staged tree: the package is not built if a bundle changed after signing or the signature is missing. A bundle rebuilt after signing means signing again. An update with a fourth number may ship without a new ISO (0.8.4.1 did: the 0.8.4 ISO stayed the current one, see ISO.md). - Copy them, and
tools/install/install.shasinstall.sh, into one release folder.
- On the maintainer's machine (where the release key lives):
SBOM. On each build VM,
tools/release/make-sbom.sh lordos_<v>_<arch>.deb, and put the.spdx.jsonfiles in the release folder (COMPLIANCE.md).Sign. On the maintainer's machine,
tools/release/sign-release.sh <release-dir>: it writesSHA256SUMSandSHA256SUMS.sigand checks them against the public key (SIGNING.md, "Release files"). Then copytools/release/lordos-release.pub.peminto the folder too (it is not covered bySHA256SUMS: it is checked by its fingerprint).Release notes.
tools/release/release-notes.sh <version> > notes.mdprints the changelog section for that version (relative links made absolute for the tag, hard-wrapped lines joined, its "Verifying" part replaced by the footer) plus a fixed footer: the downloads table, the verification steps and links to lordos.org, the paper, the docs and the security page. Read it once before publishing.The APT repository (what installed systems update from; UPDATES.md). On the maintainer's Mac, where the archive key lives (never on a VM):
# staging first: the same .debs, the notes from this version's CHANGELOG section tools/release/apt-repo.sh build staging <release-dir>/lordos_<file-version>_amd64.deb <release-dir>/lordos_<file-version>_arm64.deb tools/release/apt-repo.sh publish staging tools/release/apt-repo.sh verify staging # https and http, signature, every index hashOn a clean VM with the previous release installed, point a copy of
lordos.sourcesathttps://lordos.org/apt-staging(or afile:copy of the tree) and check:sudo apt updateis clean, Store → Updates shows "LordOS is available" with these notes, Update installs it, the migrations run (ls /var/lib/lordos/migrations), the user's settings are untouched, "Restart required" appears and the system comes back after the restart; a secondapt install --reinstall lordosruns no migration again. On the Raspberry Pi,apt-get updateagainst staging in a temporaryDir::State::Lists(no change to the board) validates the arm64 index. Then the same for the live repository:tools/release/apt-repo.sh build live <release-dir>/lordos_<file-version>_amd64.deb <release-dir>/lordos_<file-version>_arm64.deb tools/release/apt-repo.sh publish live tools/release/apt-repo.sh verify liveA version is never re-uploaded with other contents (the script refuses); a fix is a new version.
verify livemust pass before any release whose package carrieslordos.sourcesis published: otherwiseapt updatefails on every system that installs it. A change between versions that is not just new files (a unit to enable, a renamed setting, a config to convert) is a migration inpackaging/migrations/orsdk/settings.js(UPDATES.md, "Migrations"), never a manual step in the release notes.Results. Collect the evidence on each test machine with
tools/results/collect.sh <machine>(the release test VMs, the Raspberry Pi 5 with a monitor), fill in each README's conditions, commitresults/<version>/, and addtar czf results-<version>.tar.gz results/<version>to the release files (RESULTS.md).Publish:
gh release create v<version> --title "LordOS <version>" --prerelease --verify-tag \ --notes-file notes.md <release-dir>/*Leave out
--prereleaseonly for a version without a suffix. The Debian installer (install.sh) finds betas too:releases/latestskips pre-releases, so it falls back to the newest release of any kind (INSTALL-DEBIAN.md).Check: download from the release page and run the verification commands from the notes; run
curl -fsSL https://lordos.org/install.sh | shon a clean Debian 13; update the website if it names the current version.
A release that is pulled after publishing stays in the changelog, marked [YANKED], with a line
saying why.