docs(skill): capture lessons from poly-uri bootstrap#12
Open
jadb wants to merge 1 commit into
Open
Conversation
Source: the hop-top/poly-uri release session that exposed half a dozen non-obvious failure modes (shell-operator bug, pnpm 11 strict-mode, PyPI OIDC matching drift, tag-predates-workflow, PEP 440 normalization, dirty release-please PRs after main moves) plus the gaps in greenfield setup that current SKILL.md left implicit. Adds three sibling docs under docs/: - bootstrap-checklist.md — ordered greenfield setup. Covers org secrets (with explicit list of secrets that exist on hop-top but are NOT consumed by any workflow — PACKAGIST_*), mirror repo creation, per-registry registration (npm, crates.io, PyPI, Packagist, go proxy), release-please config seed values, first-release walkthrough, and per-registry verification commands. - failure-modes.md — extended symptom→cause→fix for each painful lesson. Includes workflow-log excerpts (exact error strings to grep), root-cause analysis, the fix, and an explicit "what does NOT work" list for traps where multiple fixes look plausible. Covers shell-operator trap (#9), tag-predates-workflow, pnpm 11 strictDepBuilds + allowBuilds replacement, PyPI invalid-publisher (both common cause and pending-publisher drift bug), PEP 440 version display mismatch, missing GitHub Environment, dirty release-please PRs, immutability after failed retries. - browser-playbooks.md — ibr-driveable verbal walkthroughs for each web-side setup step. Each playbook gives the URL, the literal form values, an ibr prompt template, and a verification command. Covers: PyPI pending trusted publisher (with the workflow_ref-is-the-caller trap called out), PyPI project-scoped publisher migration (post- first-publish), PyPI API token mint (account-wide for bootstrap, project-scoped after), Packagist package submission (must use mirror URL not source), GitHub Environment creation (API preferred over browser), crates.io email verification. SKILL.md gets surgical edits: - Common Pitfalls table expanded with the six new traps, each linking to the detailed treatment in failure-modes.md. - Front-matter description broadened to cover the new troubleshooting + bootstrap surface area. - See also section restructured to reference the three new docs. Existing SKILL.md sections (Mental model, Pinning, Facade pattern, Secrets reference, PyPI auth modes, Install model, ecosystems reference) preserved as-is. Total: 406 lines in SKILL.md, 218+171+245 lines in the three new docs. All under the 500-line soft cap.
There was a problem hiding this comment.
Pull request overview
This PR expands the consumer-facing hop-top/.github skill documentation with bootstrap sequencing, browser-driven registry setup playbooks, and troubleshooting guidance from recent polyglot release wiring.
Changes:
- Adds greenfield setup checklist for polyglot repos.
- Adds failure-mode documentation for tag/workflow, PyPI, pnpm, and registry retry issues.
- Adds browser playbooks for PyPI, Packagist, GitHub Environments, and crates.io setup, plus SKILL.md cross-links.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 7 comments.
| File | Description |
|---|---|
SKILL.md |
Updates skill description, Common Pitfalls, and See also links. |
docs/bootstrap-checklist.md |
Adds ordered setup checklist for new polyglot repos. |
docs/browser-playbooks.md |
Adds web-side setup walkthroughs and verification steps. |
docs/failure-modes.md |
Adds troubleshooting entries and escape hatches for known release failures. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| @@ -0,0 +1,245 @@ | |||
| # Browser playbooks | |||
|
|
|||
| Verbal step-by-step walkthroughs for each web-side setup. Each playbook is structured so an AI assistant with browser access (e.g. via [`ibr`](https://github.com/...) with cookies from a logged-in chrome session) can drive the flow. | |||
Comment on lines
+123
to
+126
| After extraction, set the org-level secret on GitHub: | ||
|
|
||
| ```bash | ||
| gh secret set PYPI_REGISTRY_TOKEN --org <org> --visibility all --body "pypi-AgEI..." |
Comment on lines
+207
to
+208
| - npm: check `npm view <pkg> versions --json` before retrying. If version landed, the publish step will fail; the rest of the pipeline (test, build, mirror) is the only thing being re-exercised — that's fine. | ||
| - PyPI: same shape. Once `hop_top_uri-0.2.0a1.tar.gz` is uploaded, re-running publish step errors. Mirror still updates. |
Comment on lines
+47
to
+48
| - Adding a wrapper script you commit to the repo and exec via path — works, but the script approach is cleaner. | ||
|
|
Comment on lines
+103
to
+104
| "packages": { | ||
| ".": { "release-type": "go", "component": "my-pkg", "exclude-paths": ["ts","py","rs","php","go"], "prerelease": true, "prerelease-type": "alpha.0", "versioning": "prerelease" }, |
|
|
||
| ## Common pitfalls | ||
|
|
||
| Detailed treatment of each entry — including symptoms you'll see in workflow logs and verification commands — in [docs/failure-modes.md](docs/failure-modes.md). |
Comment on lines
+123
to
+126
| After extraction, set the org-level secret on GitHub: | ||
|
|
||
| ```bash | ||
| gh secret set PYPI_REGISTRY_TOKEN --org <org> --visibility all --body "pypi-AgEI..." |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Distills the painful lessons from hop-top/poly-uri's bootstrap session into the skill so the next polyglot setup doesn't replay them. Three new docs under `docs/` plus surgical edits to SKILL.md.
What's added
docs/bootstrap-checklist.md (NEW, 171 lines)
Ordered greenfield setup for a brand-new polyglot hop-top repo:
docs/failure-modes.md (NEW, 218 lines)
Extended symptom→cause→fix entries for each non-obvious failure mode encountered:
run: $CMDbreaks shell operators (&&, |, ;) in test/build-command inputs #9). Includes a "what does NOT work" list (`sh -c "..."`, `eval`) because the obvious workarounds also fail for the same reason.docs/browser-playbooks.md (NEW, 245 lines)
ibr-driveable walkthroughs for every web-side setup step. Each playbook:
Covers: PyPI pending trusted publisher, PyPI project-scoped publisher (post-first-publish migration), PyPI API token mint (account-wide for bootstrap + project-scoped after), Packagist submission, GitHub Environment creation (API preferred), crates.io email verification.
SKILL.md edits (surgical)
Sizes
```
406 SKILL.md
189 docs/architecture.md
171 docs/bootstrap-checklist.md
245 docs/browser-playbooks.md
218 docs/failure-modes.md
```
All under the 500-line soft cap from AGENTS.md conventions.
Why these specifically
Every entry has a corresponding session experience — none are speculative. The list was extracted from the actual sequence of failures during hop-top/poly-uri's release wiring; today's session needed 8 retries on PyPI alone before we identified the matching-drift bug and shipped the `pypi-auth: token` escape hatch (#10).
Test plan