docs/RELEASING.md

# Releasing

Releases are built and published by [`.github/workflows/release.yml`](../.github/workflows/release.yml)
when a GitHub Release is published. PyPI never sees a password or token: the workflow authenticates with
[Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC).

## One-time setup (needs the PyPI account owner)

The project name `lumen-rag` was unclaimed on PyPI when this was written (checked 2026-10-18). The first
upload claims it, so register it before anyone else does.

1. Create a PyPI account with 2FA, if there is none: https://pypi.org/account/register/
2. Add a **pending publisher** (the project does not exist yet, so it is "pending"):
   https://pypi.org/manage/account/publishing/ → *Add a new pending publisher*
   - PyPI project name: `lumen-rag`
   - Owner: `WickTech`
   - Repository name: `lumen-rag`
   - Workflow name: `release.yml`
   - Environment name: `pypi`
3. In the GitHub repo: *Settings → Environments → New environment* named `pypi`. Add yourself as a
   required reviewer so every publish needs a manual approval click.
4. (Recommended) Do a dry run on TestPyPI first: add a second pending publisher on https://test.pypi.org
   and a `testpypi` environment, then point a copy of the publish step at
   `repository-url: https://test.pypi.org/legacy/`.

## Releasing a version

1. Update `__version__` in `lumen_rag/__init__.py` and the `CHANGELOG.md` heading (replace *unreleased*
   with the date).
2. Open a PR; make sure CI, the PR eval report and Security are green; merge.
3. Run the workflow's build and smoke test without publishing: *Actions → Release → Run workflow*
   (the `workflow_dispatch` path builds, runs `twine check`, and installs the wheel in a clean virtualenv).
4. Create the release: *Releases → Draft a new release*, tag `vX.Y.Z` on `master`, publish.
   The workflow refuses to run if the tag does not match `lumen_rag.__version__`.
5. Approve the `pypi` environment when GitHub asks. Verify:
   ```bash
   python -m venv /tmp/v && /tmp/v/bin/pip install lumen-rag && /tmp/v/bin/lumen --help
   ```
6. In `README.md`, change the install section to lead with `pip install lumen-rag`.

## Things that cannot be undone

- A published version number can never be reused, and a file can be *yanked* but not replaced. If a release
  is broken, publish a new patch version.
- Anything in the sdist or wheel is public. The sdist is limited by an include list in `pyproject.toml`
  (package, tests, eval data, scripts, docs); check `tar tzf dist/*.tar.gz` before a release.

## What the workflow checks

- Tag equals `lumen_rag.__version__`.
- `twine check` accepts the metadata and README.
- The wheel installs into a clean virtualenv away from the checkout, `lumen --help` runs, and a one-document
  ingest + query returns a citation.