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:

```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`. The packaging source checkpoint `77b11a8`
subsequently passed [push run 1065](https://gitea.speelman.ca/gamertan/sized/actions/runs/1065)
and [PR run 1066](https://gitea.speelman.ca/gamertan/sized/actions/runs/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](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 v2.0.0 -m "Release Sized 2.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`, 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:

```sh
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](https://developer.apple.com/documentation/security/customizing-the-notarization-workflow).

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

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.