molecule-ai/molecule-ai-workspace-runtime
35
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(readme): clarify PyPI canonical vs git mirror staleness

Browse Source 
The existing README warns 'don't edit here, edit molecule-core/workspace/'
but doesn't address the asymmetry that bites consumers most often:
the PyPI wheel and this repo's git tree are not the same snapshot.

publish-runtime.yml builds the wheel from molecule-core staging HEAD
and uploads to PyPI on every tag. The git mirror push is a separate
step and can lag by hours (or be skipped on transient failure) while
the wheel still ships. So 'is module X in the published runtime?'
can't be answered by browsing this repo — only the wheel listing
is wire-truth.

Adds a 'PyPI is canonical, this git tree may lag' section with a
pip download + unzip recipe for verifying what's actually in a wheel.

Doc-only. Does not change publish behavior or mirror-guard policy.
This commit is contained in:
Hongming Wang 2026-05-01 20:13:31 -07:00
parent 05486e193c
commit baa828675c
1 changed files with 25 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
README.md
View File

@ -50,6 +50,31 @@ workflow rebuilds this mirror + uploads the new wheel to PyPI.
See [`docs/workspace-runtime-package.md`](https://github.com/Molecule-AI/molecule-core/blob/main/docs/workspace-runtime-package.md)
for the full publishing flow.
## PyPI is canonical, this git tree may lag
**The PyPI wheel is the canonical artifact** for runtime consumers
(workspace template images, the controlplane's runtime smoke harness,
local `pip install` users). What's in PyPI and what's checked into this
repo's git tree **may differ** — sometimes by hours, sometimes by days.
Why: the [`publish-runtime`](https://github.com/Molecule-AI/molecule-core/blob/main/.github/workflows/publish-runtime.yml)
workflow always publishes a fresh wheel built from `molecule-core`'s
`staging` HEAD, but the git mirror push that updates this repo is a
separate step and can lag (or, on transient failures, be skipped while
the wheel still ships). The mirror exists for **human readability** and
to give `mirror-guard` a concrete branch to enforce its
"no direct PRs" policy against — not as the wire-truth artifact.
**To check what's actually in a wheel:**
```bash
pip download molecule-ai-workspace-runtime==X.Y.Z --no-deps
unzip -l molecule_ai_workspace_runtime-X.Y.Z-*.whl
```
If you're chasing "is module X in the published runtime yet?", trust
the wheel listing, not this repo's `git log`.
## Why this split
The runtime needs to ship as a PyPI artifact (so the 8 workspace template