From baa828675c8cabc9ad030c3ef3d90127f669d20c Mon Sep 17 00:00:00 2001 From: Hongming Wang Date: Fri, 1 May 2026 20:13:31 -0700 Subject: [PATCH] docs(readme): clarify PyPI canonical vs git mirror staleness MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- README.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/README.md b/README.md index 14c5cc1..5312a05 100644 --- a/README.md +++ b/README.md @@ -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