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