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.

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.
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.
Review and merge independently of distribution. A branch push or PR merge does not publish a package, change repository visibility or create a tag.
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:

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

Synchronize the version in Cargo.toml.
Update CHANGELOG.md with the release notes.
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:

Push the git tag to your SCM.
Run the release script to generate assets.
Attach the contents of the dist/ folder to your SCM's "Release" or "Tag" entry.
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.

5.3 KiB Raw Blame History