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 retains its own copy until adoption preserves public source access.

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 v1.0.0 -m "Release v1.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. 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.

3. Distribution channels

The existing public Gitea v1.0.0 release contains a macOS arm64 executable, man page and completions, plus generated source archives. It predates the scanner hardening branch. No architecture-labelled binary archive, .deb or verified Homebrew tap is currently offered.

Future public releases need their own reviewed version, source, target-specific archives, checksums and installation acceptance. Do not replace historical v1.0.0 assets with newly built bytes. Add a new version only after review.

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.