# Manual releases

AutoCAD Bench releases are assembled locally. One release directory binds the
Python package and benchmark corpus together without depending on a CI system
or project-owned cloud infrastructure.

## Build

Start from a clean checkout with Python 3.12, `uv`, and the active evaluator
cache:

```bash
uv sync --dev
uv run pytest

uv run autocad-bench-release build \
  --output dist/releases/0.1.0
```

The default build includes the evaluator version pinned by the runtime
contract. Use `--source-only` only when intentionally publishing a corpus
without generated gold renders.

The output directory is created from scratch and contains exactly:

```text
autocad-bench-corpus-v1.tar.gz
autocad_bench-<version>-py3-none-any.whl
autocad_bench-<version>.tar.gz
release.json
SHA256SUMS
```

`release.json` records the package version, bundle version, evaluator versions,
fixed source timestamp, byte size, and SHA-256 digest of every artifact.
`SHA256SUMS` covers those artifacts and `release.json`.

The output path must not already exist. This prevents a new release from
silently inheriting stale files.

## Verify

Run the project verifier before upload and again against downloaded artifacts:

```bash
uv run autocad-bench-release verify \
  --root dist/releases/0.1.0
```

Verification checks:

1. the exact release inventory and every recorded size and SHA-256 digest;
2. the generated `SHA256SUMS` file;
3. package name and version inside both the wheel and sdist;
4. normalized, traversal-safe corpus archive metadata;
5. the corpus bundle's exact inventory, task and audit contracts; and
6. every included gold-cache entry against its source DWG.

The first three artifacts are upload-ready. Publish the wheel and sdist to the
chosen Python package registry. Publish the corpus archive, `release.json`, and
`SHA256SUMS` together on the release page or artifact store. Operators need the
Python package and corpus archive from the same release.

## Reproduce

The release builder sets deterministic archive metadata and Python build
environment values. Its isolated PEP 517 dependencies are pinned in
`build-constraints.txt`; `SOURCE_DATE_EPOCH` defaults to `315532800`
(1980-01-01) unless explicitly supplied.

Build twice from the same source tree and compare the directories:

```bash
uv run autocad-bench-release build --output /tmp/autocad-release-a
uv run autocad-bench-release build --output /tmp/autocad-release-b
diff -ru /tmp/autocad-release-a /tmp/autocad-release-b
```

An empty `diff` means every artifact, manifest, and checksum is byte-for-byte
identical. If a project needs a different timestamp, pass the same
`--source-date-epoch` value to both builds and preserve it in the release
record.

## Version changes

- Change `project.version` in `pyproject.toml` for a code release.
- Change the bundle format/version only when the portable corpus contract
  changes incompatibly.
- Publish a new evaluator cache version instead of rewriting an existing
  evaluator directory.
- Never edit artifacts inside a completed release directory; rebuild into a
  new path.