sized/SHIPMENT.md

Project Release Process

This document defines the process for versioning and distributing the sized project independently of the Git hosting provider (GitHub, GitLab, Gitea).

Source review before a release

Use a named branch from main and keep a pull request focused on one outcome. The sizequeen-scan-hardening branch corrects accounting/error handling and adds the scan controls needed by SizeQueen; the scanner has also been extracted into private sized-core for SizeQueen. Sized 2.0 includes its exact pinned source snapshot as a path dependency. Verify CORE-SNAPSHOT.json before packaging; no private Git fetch is part of a public build.

1. Run local locked tests and strict Clippy as an unprivileged user. Run ./scripts/check-linux.sh linux/arm64 and ./scripts/check-linux.sh linux/amd64 for the repeatable Linux checks, including actual mount boundaries and an optimized-binary smoke test.
2. Push the review branch. Open a PR against main when its scope is ready, explaining changed behaviour, test evidence and remaining limits. For this branch, call out nonzero status on partial scans, added JSON status fields, and library API changes. Record current work and evidence in TODO.md.
3. Review and merge independently of distribution. A branch push or PR merge does not publish a package, change repository visibility or create a tag.
4. Choose the release version after reviewing library/API compatibility, then use the release steps below when explicitly authorized. Verify the exact archive contents, target and installation instructions before announcing a release.

Gitea Linux CI

.gitea/workflows/linux.yml uses the existing himesan-node24 label on cliff-mads, overriding the job image with the pinned Sized Rust runtime. The runner itself launches the two tmpfs mounts. Jobs have no Docker socket and run scripts/check-linux-container.sh as UID 65532, using the checked-out workspace as SIZED_TEST_SOURCE. Its tests, strict Clippy, formatting and optimized-binary smoke test and extracted release-archive verification are the same as the local Docker workflow.

The runtime contains Rust 1.88.0, rustfmt/Clippy and Node for the pinned checkout action. On cliff-mads, rebuild it explicitly with:

ssh cliff-mads 'docker build --platform linux/amd64 --tag local/gamertan-ci:sized-rust188 -' < scripts/gitea-linux.Dockerfile
ssh cliff-mads 'docker image inspect local/gamertan-ci:sized-rust188 --format "{{.Id}}"'

Review and update the workflow's image ID after an intentional rebuild; images stay local to the runner host. The image pre-owns /workspace/gamertan/sized for UID 65532 so the runner's workspace setup permits unprivileged checkout. No runner labels, global isolation settings or publishing credentials are required. Repository Actions must be enabled. Only owner-triggered, same-repository code runs on this shared homelab runner. Source changes on main/the review branch and PRs to main trigger checks; documentation-only pushes skip builds. Manual dispatch is also available. This workflow does not publish or tag releases.

The first complete native AMD64 push check is Gitea run 1048 (number 2), at 74b30bbf750417121f3b0c26017d2f011a2a8286. All 23 tests, formatting, strict Clippy, release smoke and unchanged-checkout verification passed as UID 65532 on cliff-himesan-linux-amd64. The packaging source checkpoint 77b11a8 subsequently passed push run 1065 and PR run 1066, including executable/archive checks and output/symlink refusal. Manual dispatch is configured but not independently exercised. See TODO.md for current work.

1. Versioning and Tagging

The project adheres to Semantic Versioning.

1. Synchronize the version in Cargo.toml.
2. Update CHANGELOG.md with the release notes.
3. Commit and create a git tag:

   git tag -a v2.0.0 -m "Release Sized 2.0.0"
   

2. Asset generation and verification

./scripts/check-release.sh
./scripts/release.sh

release.sh uses the locked dependencies and the Rust toolchain's host target. It packages the executable before creating the archive, together with the man page, Bash/Zsh/Fish completions, licence, README, manual and build metadata. Outputs are dist/sized-v<VERSION>-<RUST-TARGET>-<REVISION>/, a sibling .tar.gz and .tar.gz.sha256, including complete dependency notices. Existing outputs are never replaced. Use --output-dir /absolute/new/path for an explicitly named local candidate. CARGO_TARGET_DIR is respected. The script does not sign, upload, tag or publish.

check-release.sh creates temporary outputs, extracts the archive, checks all required files and the checksum, then runs the packaged executable against an owned fixture. It also checks the refusal to overwrite. Gitea's Linux check runs this same test; a successful compile alone is insufficient.

Only build from a clean, reviewed commit for distribution. BUILD-INFO.txt records the commit, target, toolchain and whether tracked inputs were modified. Exported source can provide SIZED_SOURCE_REVISION; verify that provenance against the original checkout. Retain matching source and complete dependency licences with any public binary distribution. A host build is unsigned; do not advertise it as notarized or as a Mac App Store application.

Matching source and Mac delivery

From a clean committed source checkpoint, run:

scripts/package-source.sh /absolute/new/release-directory

This exports tracked source, includes all locked registry dependencies, verifies an empty-cache offline build, and retains the exact source archive. Build the binaries from that exported sized-source directory with CARGO_NET_OFFLINE=true and SIZED_SOURCE_REVISION set to SOURCE-REVISION.txt. Linux release checks can retain an archive when SIZED_RELEASE_DIR names a writable output mount. Run on the architecture being released; keep both tmpfs boundary mounts and UID 65532. This does not publish files.

For Mac, use scripts/notarize-macos.sh PACKAGE_DIRECTORY NEW_DMG_PATH with an explicit SIZED_SIGN_IDENTITY. It signs the CLI and disk image, submits through SIZED_NOTARY_PROFILE (default sizequeen-notary), staples and validates the DMG. The notarization receipt stays with private build evidence. Distribute the DMG; a raw command-line executable cannot carry a stapled ticket. Compute final checksums only after signing/stapling, then exercise the mounted signed CLI and verify the downloaded files. See Apple's custom workflow guidance.

Publish versioned files on the Gitea release and link them from the existing Gamertan CMS project. Keep forge privacy settings unchanged. Retain the exact matching source and never overwrite a published asset with different bytes.

3. Distribution channels

Sized 2.0.0 provides Apple silicon Mac (signed DMG), Linux x86-64 and Linux ARM64 archives, matching vendored source and SHA-256 checksums through Gitea, linked from Gamertan. No verified Homebrew tap or .deb installer is offered. Historical v1.0.0 assets remain unchanged.

Debian/Alpine packaging is separate from the portable host archive. Do not implicitly invoke cargo deb or abuild just because they are installed: a Mac binary is not a Debian package. Validate each installer on its target OS before publishing it. Registry and Homebrew publication are separate decisions too.

4. Automation

CI tests and packages temporary candidates without publishing credentials. Do not run release generation automatically from Git hooks. Publication remains an intentional operation after the checks above.

5. Manual Installation

For system-wide installation from source, use the Makefile:

make install

Defaults to PREFIX=/usr/local. Overridable via PREFIX=/your/path make install.

6. Contributions

The project accepts contributions under the terms of the Contributor License Agreement. All pull requests must acknowledge agreement with these terms.

Sized 2.0.0 — 10 October 2026

Released source/tag: 9f36122e37ea3aefbd22ded08950e8858538e44b / v2.0.0. PR #2 was fast-forward merged. The pinned core is fb63e96266dcb8ffbca53b73c6c0f738ac3e827d; the core forge remains private, while CORE-SNAPSHOT.json verifies the public source copy.

Public file	SHA-256
sized-v2.0.0-aarch64-apple-darwin.dmg	ded20af5dbcb425d2afcd04033c2256977eb10ca06e6ae29db27bb88b5f8fa7b
sized-v2.0.0-aarch64-unknown-linux-gnu.tar.gz	2e2476267cd37bd2ceee8809daad57a6597a0053f913ff0ae566f1032b0f619e
sized-v2.0.0-x86_64-unknown-linux-gnu.tar.gz	9eefe83aebabb580b4e28a9d5a9688c2ca845ffe22b0d4109c552701bb0df09f
sized-v2.0.0-source.tar.gz	0969ec29a2c994008dd2e41da7f13314f523b980466848f12019616af6088544

The fifth attachment is SHA256SUMS. All five were downloaded publicly and compared with the retained release files. Do not replace them with rebuilt bytes. The source archive includes the exact core and locked registry sources/notices. It excludes Mac archive metadata/AppleDouble files; Linux extraction verifies snapshot hashes. See dependency review.

• Mac: scanner/CLI passed 33 tests and strict workspace Clippy; final archived source passed an empty-cache offline check. Built with Rust 1.98.0 on macOS 26.6.2, deployment target 11.0, only system dylibs. Developer ID signing, notarization, stapling and Gatekeeper passed. The actual Chrome download kept quarantine and passed installation, --version and a complete fixture scan.
• Linux: native ARM64 Docker and native AMD64 on cliff-mads each passed 35 tests, including both real mount tests, formatting, strict Clippy, release smoke and archive/executable/overwrite guards. Release packages were built from the extracted matching source archive, offline, as UID 65532, with Rust 1.88.0 on Debian 12. Supported package baseline: glibc 2.36+. No musl claims.
• Provider CI on exact source: push 1071 and PR 1072 passed.
• CMS project revision 10 supplies downloads and upgrade guidance, retaining the shared status sidebar. Desktop/320px mobile fit without page overflow.

Local evidence: ignored target/release-audit/ logs and target/distribution/2.0.0-portable/ retain packages, source, public-download copies and the notarization result. Website evidence is in its .local/releases/sized-2.0.0/. No personal scan data was used in release tests. Older macOS and fresh-machine acceptance remain pending; no Intel Mac, Windows, App Store or package-manager distribution is included. SizeQueen's released binary and private core repository visibility were not changed.