startrail-org--pixelrag/RELEASING.md

Releasing PixelRAG to PyPI

PixelRAG ships as a single PyPI package, pixelrag — one distribution that bundles the umbrella CLI plus every stage module (pixelrag_render, pixelrag_embed, pixelrag_index, pixelrag_serve). The core install is light (rendering only); heavy ML stages are extras:

pip install pixelrag            # pixelshot + pixelrag umbrella (no torch)
pip install 'pixelrag[serve]'   # + search API   (also [embed], [index], [all])

train/ is a separate local project and is not published.

Publishing is automated by .github/workflows/release.yml using an account-scoped PyPI API token stored as a repo secret.

One-time setup

1. Create an account-scoped PyPI API token at https://pypi.org/manage/account/token/. Copy the pypi-... value.

2. Store it as the PYPI_API_TOKEN repo secret:

   gh secret set PYPI_API_TOKEN --repo StarTrail-org/PixelRAG
   

   (or repo Settings → Secrets and variables → Actions → New repository secret).

Cutting a release

1. Bump the version:

   uv version X.Y.Z
   

2. Commit and push.

3. Publish a GitHub Release with tag vX.Y.Z (matching the version). That fires release.yml, which builds and publishes pixelrag to PyPI.

Dry run

Actions → Release to PyPI → Run workflow (leave dry_run checked) builds the package and lists artifacts without uploading. Use it to sanity-check before a real release.

Notes

• README images on PyPI. The README uses repo-relative image paths (docs/assets/...), which render on GitHub but not on the PyPI project page. To show them on PyPI, switch those <img src> to absolute https://raw.githubusercontent.com/... URLs.
• sdist scope. The repo root holds large data dirs (.venv, tiles, arxiv, …); the package restricts its sdist to the source dirs + README.md + LICENSE ([tool.hatch.build.targets.sdist] in pyproject.toml).
• Superseded packages. pixelrag-render, pixelrag-embed, pixelrag-index, and pixelrag-serve were published once (0.1.0) before consolidation and are now yanked; everything lives in pixelrag.