docs(workspace-runtime): migrate github.com refs at source (#41) #15
Ghost
Loading…
Reference in New Issue
Block a user
No description provided.
Delete Branch "docs/workspace-runtime-readme-source-edit"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
What
Source-side fix for internal#41 — workspace-runtime mirror's published README + in-monorepo workspace-runtime docs reference suspended-GitHub URLs.
Per saved memory
reference_runtime_repo_is_mirror_only, mirror-guard rejects direct PRs tomolecule-ai-workspace-runtime. The fix lives at source (this monorepo); the mirror inherits the new content on nextruntime-v*tag (publish-runtime workflow regenerates the README fromscripts/build_runtime_package.py'sREADME_TEMPLATE).Files changed (3)
scripts/build_runtime_package.pyREADME_TEMPLATEfirst-line "Shared workspace runtime for [Molecule AI]" link → Gitea; doc-link to workspace-runtime-package.md → Gitea path-shape (/src/branch/main/).workspace/build-all.shdocs/workspace-runtime-package.mdLEFT AS-IS
scripts/build_runtime_package.py:379, 392— historical issue cross-refs (#2936, #2937). Per Q3 audit-trail decision.workspace/Python source code (.pyfiles) — github paths in docstrings + log strings. Cross-repo Go-module-style migration handles these (per #37 Q5 + parked follow-ups). Out of scope for #41.docs/workspace-runtime-package.md:254-256—gh repo create … --template Molecule-AI/...— gh CLI doesn't talk to Gitea. Per internal#45 parked follow-up.docs/workspace-runtime-package.md:276—ghcr.io/molecule-ai/workspace-template-<runtime>:latest— per internal#46 ghcr→ECR migration (separate concern).Phase 2 design
SSOT: README content lives in
scripts/build_runtime_package.py'sREADME_TEMPLATEconstant. Single edit point; build script copies into the wheel + mirror on everyruntime-v*tag.Alternatives considered:
A. Edit at source (this PR) ✅ chosen. Single SSOT, mirror auto-regenerates, future runs propagate.
B. Direct edit on the mirror ❌ rejected — mirror-guard rejects per saved memory
reference_runtime_repo_is_mirror_only; would also be lost on next regenerate.C. Bypass mirror via OOB push ❌ rejected — defeats the purpose of mirror-guard; future regenerate still wins.
Security check: no untrusted-input handling, no auth/session/permissions changes, no new data collection, no scope expansion. Pure-docs edit. On the record.
Versioning + back-compat: no interface/API change. The mirror's published README will diff on the next
runtime-v*tag; consumers reading the mirror's README see the new link. No deprecation cycle needed (URL is informational, not load-bearing).Phase 4 verification plan
python -c "from scripts import build_runtime_package; print(build_runtime_package.README_TEMPLATE[:200])"to confirm no syntax error in the template constant.scripts/build_runtime_package.pylocally (if it has a dry-run mode) or inspect the would-be output.runtime-v*tag push (or manualworkflow_dispatch); confirm the published wheel's PyPI README contains the new Gitea link, and themolecule-ai-workspace-runtimemirror's README.md is updated.DoD
Pure-docs PR + 1 build-script string-edit. No tests / observation / migration / version bump. Security on-record. Back-compat: additive (URL is informational).
Hostile self-review (3 weakest spots)
The starter-repo-recreation note is a known-incomplete fix.
molecule-ai-workspace-template-starterdoesn't exist on Gitea (404 verified). The doc now points at a Gitea URL that 404s. Mitigation: explicit inline note "the starter repo did not survive the 2026-05-06 GitHub-org-suspension migration; recreation tracked at internal#41." Reader knows it's an interim state. Accepted because: alternative (delete the section about "Writing a new adapter") loses critical onboarding documentation; alternative (rewrite the section to use a different template-creation flow without a starter) is bigger than #41 scope.The mirror's CONTRIBUTING.md is unchanged. I noted earlier the CONTRIBUTING in the mirror has 4
Molecule-AI/molecule-coreslug refs. CONTRIBUTING is not auto-regenerated bybuild_runtime_package.py(only README is) — so it's hand-coded in the mirror, and mirror-guard rejects direct edits. Mitigation: This PR doesn't address CONTRIBUTING; either (a) add a CONTRIBUTING template tobuild_runtime_package.pyso it's regenerated alongside README, or (b) carve out a one-time exception in mirror-guard to allow a CONTRIBUTING-only edit. Both options are bigger than the simple URL-substitution scope of #41. Accepted because: CONTRIBUTING content is mostly unchanged and the slug refs ALSO 404 today, so they're equally broken — fixing in same PR would expand scope without functional benefit. Filed implicitly as continuation of #41.The publish-runtime workflow itself uses
Molecule-AI/molecule-corein its OIDC trust-publisher claim (per workflow file header comment). If the OIDC trust-policy at PyPI was updated to expect Gitea's issuer post-suspension, the publish should still work. If not, this PR's change won't reach PyPI. Mitigation: per internal#46 §4 (OIDC vendor-trust-policy section), security-auditor's audit flaggedmolecule-core/publish-runtime.yml:79for verification. Accepted because: that's #46's scope, not #41's; my source-side edit is correct independently of whether the publish actually fires.Refs: internal#41, internal#37, internal#38, internal#42, internal#45, internal#46.
The molecule-ai-workspace-runtime mirror is regenerated on every runtime-v* tag from this monorepo's workspace/. Per saved memory reference_runtime_repo_is_mirror_only, mirror-guard rejects direct PRs to the mirror; edit at source. Source-side files that propagate to the mirror's published README + read by users of the in-monorepo workspace-runtime docs: - scripts/build_runtime_package.py (the README generator): * line 281 README_TEMPLATE: 'Shared workspace runtime for Molecule AI' link → Gitea * line 399 doc-link to workspace-runtime-package.md → Gitea path (with /src/branch/main/ shape) LEFT AS-IS (per Q3 audit-trail decision): * lines 379, 392 historical issue cross-refs (#2936, #2937) - workspace/build-all.sh:5 — comment block linking to template-* repos. Migrated to Gitea path-shape. - docs/workspace-runtime-package.md: * lines 101-108 adapter→repo table (8 templates, all PUBLIC on Gitea) — Gitea URLs * line 247 starter-repo link — substituted host + added inline note that starter doesn't survive the suspension migration (recreation pending; cross-link to this issue) * line 259 generic git clone command for new templates → Gitea * line 289 second starter mention — same handling as 247 Files NOT touched in this PR: - workspace/ Python source code (.py files) — those use github paths in docstrings + a few log strings; fix bundled with the cross-repo Go-module-style migration (per #37 Q5 + parked follow-ups). - 'Writing a new adapter' section's `gh repo create` command (line 254-256) — gh CLI doesn't talk to Gitea (per #45 parked follow-up). - 'Writing a new adapter' section's ghcr.io image ref (line 276) — per #46 ghcr→ECR migration (separate concern). After this PR merges to staging + a runtime-v* tag is pushed, the mirror's published README will inherit the Gitea link. Until then the mirror's README continues to reference github.com/Molecule-AI (stale but historical-marker-correct since the mirror existed pre-suspension). Refs: molecule-ai/internal#41, molecule-ai/internal#37, molecule-ai/internal#38, molecule-ai/internal#42, molecule-ai/internal#45, molecule-ai/internal#46Doc-sweep / install-path migration. Independent review.