fds-os/docs/developer/versioning.md

Build versions and the workstation package

tools/version is the authoritative FDS build-version resolver. It reads this repository's Git history, never the Void submodule's history. All FDS Rust commands, base XBPS packages, login/boot banners and /etc/os-release use it. SYSTEM cartridge metadata copies the version already embedded in its rootfs, so wrapping an older rootfs does not mislabel it as the current source version.

Release tags are numeric MAJOR.MINOR or MAJOR.MINOR.PATCH, optionally prefixed with v. Unrelated tags are ignored. The nearest reachable release tag is used:

Source state	Example build version
Exactly release tag 1.0, clean checkout	1.0
Two commits after 1.0	1.0.r2.g123456789abc
No reachable release tag	0.dev.g123456789abc
Uncommitted changes to tracked files	Append .dirty

Untracked files do not affect the version, matching Git’s usual dirty-checkout convention. Add new release sources to Git before tagging.

Versions are bounded to 32 letters, digits and periods, starting with a digit, for the cartridge metadata, XBPS and Arch package formats. A shallow clone without a reachable release tag gets a development version; fetch the intended release tag/history before building a release. No value is silently invented when both Git identity and an exported identity are missing.

Each Rust crate uses the shared build script, including direct Cargo builds. Cargo notices tag/ref changes, index changes and source edits, avoiding an old version string in a cached binary. Cargo's workspace metadata uses the SemVer form 1.0.0; the public build version comes from Git. Protocol/schema versions, application recipe versions, the Linux kernel version and third-party package versions are independent and remain unchanged.

tools/prepare-void writes the resolved value to the writable build checkout's fds-version file. FDS-owned XBPS templates read it; base-files substitutes it into /usr/lib/os-release and /etc/issue. /etc/os-release links to that installed identity file. Runtime checks compare installed command versions against VERSION_ID. Superseded FDS packages are archived under out/package-history/ so the active repository cannot accidentally select an older development package whose version sorts above a release.

Frozen source exports save a validated FDS_VERSION file before inventorying and hashing their contents. Their builds use that saved value without Git or network access. Legacy 0.1.0 snapshots retain their original scripts and layout; the historical release stays unchanged. Release verification accepts supported version strings independently of the verifier's own version, so newer tools can still authenticate an older signed release using the supplied trust key.

Build and install on Arch

packaging/arch/PKGBUILD packages the local checkout. make workstation invokes makepkg, building both binaries in the existing Cargo cache and recording the result in out/workstation/package-path.txt. It builds without implicit package installation; required build commands are checked directly. Runtime feature packages are declared as optional because project-local runners are supported. make workstation-install explicitly invokes pacman to install the exact recorded package. Generic Linux users use make workstation-binaries.

The package includes binaries, the user/developer manuals, source examples, MIT licensing and dependency notices. It has no service, hook or installation script. The workflow follows the official PKGBUILD specification and makepkg interface.

Verification

make check includes release/no-tag/dirty/export and real Cargo cache-invalidation checks. make workstation-test exercises the installed-tree cartridge creator; make emulator-test covers stopping and starting the same directory, preserved logs/overlays/mappings, and rejecting a restart of a live VM. make workstation-package-test installs the real Arch package with pacman in a disposable root and executes both installed commands. After building matching images, python3 tests/integration/version-images.py reads the identity and metadata directly from the GPT/EROFS image and executes its twelve FDS commands under ARM emulation to compare their versions. Image acceptance requires a new CLI rootfs and SYSTEM image: inspect their identity, execute the ARM tools and run the VM checks. A VM result does not establish physical Pi or Dasung power-cycle behavior.