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 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:

```bash
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)](https://gitea.speelman.ca/gamertan/sized/actions/runs/1048),
at `74b30bbf750417121f3b0c26017d2f011a2a8286`. All 23 tests, formatting, strict
Clippy, release smoke and unchanged-checkout verification passed as UID 65532
on `cliff-himesan-linux-amd64`. PR and manual-dispatch events are configured;
only push execution has been exercised. See `TODO.md` for the current checkpoint.

## 1. Versioning and Tagging

The project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). 

1.  Synchronize the version in `Cargo.toml`.
2.  Update `CHANGELOG.md` with the release notes.
3.  Commit and create a git tag:
    ```bash
    git tag -a v1.0.0 -m "Release v1.0.0"
    ```

## 2. Asset generation and verification

```bash
./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`:
```bash
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](CLA.md). All pull requests must acknowledge agreement with these terms.