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.

Use the same Linux check script in Gitea CI when a Docker-capable runner is configured. The current branch provides the local entry point; it does not configure a runner or enable automatic publishing.

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

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

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

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:

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.