wehub-resource-sync
59 lines
2.2 KiB
Markdown
59 lines
2.2 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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`](.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:**
|
|
|
|
```bash
|
|
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:**
|
|
|
|
```bash
|
|
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`.
|