Skip to content

Release Engineering

Release sequencing, semantic versioning, release candidates, and staged validation are defined in Release Process.

Toolchain

The supported Rust toolchain is locked in rust-toolchain.toml at Rust 1.88.0. CI installs that toolchain explicitly and uses the same version for formatting, linting, tests, release builds, and supply-chain checks.

Release Archives

scripts/package-release.sh is designed for reproducible archives:

  • SOURCE_DATE_EPOCH controls file mtimes and tar metadata.
  • archive entries are sorted by path.
  • archive ownership is normalized to uid/gid 0.
  • gzip is written with -n so timestamp and original filename headers are not embedded.
  • release CI compares two archives built from the same inputs.

Release targets include GNU libc and musl variants:

  • x86_64-unknown-linux-gnu
  • x86_64-unknown-linux-musl
  • aarch64-unknown-linux-gnu
  • aarch64-unknown-linux-musl
  • armv7-unknown-linux-gnueabihf
  • armv7-unknown-linux-musleabihf

GNU libc archives are intended for normal Raspberry Pi OS installs. Musl archives provide the static-build path where a lower host libc baseline is needed or easier to validate.

Artifact Gates

Do not publish package channels until the matching GitHub release includes:

  • target-specific archives
  • target-specific SHA-256 files
  • SBOM files
  • provenance attestations
  • a release note stating whether hardware validation was run for the supported Raspberry Pi OS matrix

The manual hardware validation workflow can test exact published archives by passing release_version in workflow_dispatch. It requires matching self-hosted Raspberry Pi runners and is not part of the hosted tag release workflow.

The tag release workflow gates publication on hosted release verification: formatting, Clippy, workspace tests, cargo audit, cargo deny, Debian package build, lintian, autopkgtest, cross-target release archives, SBOM generation, and provenance attestation.

Post-release Debian validation must also run from a clean Debian unstable environment. Treat that external source build, lintian, autopkgtest, and sbuild run as a release gate rather than relying only on GitHub Actions or a local developer machine.

Package Channels

Debian packaging in debian/ is maintained for mentors review. Publish to mentors or an APT repository only after the artifact gates are complete.

Homebrew packaging lives in packaging/homebrew/pi-doctor.rb. Fill in the release archive SHA-256 only after the signed release artifact exists.

Optional Snap or Flatpak packaging should be added only if confinement does not block the read-only hardware diagnostics documented in the CLI contract.

Installer Lifecycle

CI tests the release installer with real archives for:

  • upgrade install
  • downgrade install
  • rollback to the previous binary
  • uninstall

The installer keeps the previous binary at .pi-doctor.previous in the target binary directory and restores it with --rollback.

--skip-attestation is reserved for explicitly supplied local archives used in offline or CI smoke tests. Remote GitHub release downloads still require attestation verification.