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; shared-crate extraction follows
in a separate PR so reviewers can distinguish behaviour changes from packaging.

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. Reconcile legacy
   GitLab download/package links before announcing a Gitea 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

The `scripts/release.sh` script is the authoritative way to generate release assets locally or in any CI environment. 

```bash
./scripts/release.sh
```

This script generates:
-   **Optimized Binary**: The production-ready `sized` executable.
-   **Documentation**: The `sized.1` man page.
-   **Shell Completions**: Scripts for Bash, Zsh, and Fish.
-   **System Installers**: A `.deb` package for Debian-based Linux distributions.

All assets are gathered in the `dist/v<VERSION>/` directory.

## 3. Distribution Channels

### crates.io
To update the project on the central Rust registry:
```bash
cargo publish
```

### System Package Managers
For Homebrew, GitLab, or Gitea-based distribution:
1.  Push the git tag to your SCM.
2.  Run the release script to generate assets.
3.  Attach the contents of the `dist/` folder to your SCM's "Release" or "Tag" entry.
4.  Update downstream formulas (like `homebrew-tap`) with the new source URL and SHA256 of the generated tarball.

## 4. Automation & Hooks

To automate asset generation locally, you can use a git `post-checkout` or a wrapper script. Since gitea and gitlab use different CI formats, it is recommended to simply call `./scripts/release.sh` within your preferred CI runner (e.g., `gitlab-ci.yml` or `gitea-actions`).

## 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.