docs: QUICK-REFERENCE "Pages 404?" snippet recommends the wrong permissions
Nobody has claimed this yet.
- Dominant language
- Shell
- Stars
- 0
- Forks
- 1
- Avg merge
- 32m
- Merged PRs (30d)
- 3
Description
From the v0.8.0 validation study; context QuantEcon/lectures#11.
docs/QUICK-REFERENCE.md:312-317 ("Pages 404?") recommends permissions: contents: write — wrong for native Pages deployment, and worse: a permissions: block zeroes every unlisted scope, so pasting it into a working publish workflow drops pages and id-token, breaking the configure-pages → upload-pages-artifact → deploy-pages chain at publish-gh-pages/action.yml:68-78. Same doc is right at :90-93 and :241-245.
Same pass: docs/MIGRATION-GUIDE.md:244 and docs/ARCHITECTURE.md:68 give the build-jupyter-cache key as build-{env-hash}-{run-id}, dropping the update-hash segment of build-jupyter-cache/action.yml:95; docs/QUICK-REFERENCE.md:181 is correct, and neither stale line is on another open issue. :244 sits under "Step 5: Update cache.yml" → "After (Recommended: Using build-jupyter-cache Action)", so don't "correct" it to a conda-… key. The separate setup-environment drift — docs/QUICK-REFERENCE.md:180 and setup-environment/README.md:132 give conda-{os}-{hash(env.yml)}-{version}, missing the {env-name}/py{ver} of setup-environment/action.yml:134 — is on #109, out of scope.
-
docs/QUICK-REFERENCE.md:312-317→pages: write+id-token: write -
docs/MIGRATION-GUIDE.md:244anddocs/ARCHITECTURE.md:68→build-{env-hash}-{update-hash}-{run-id}
#109's checklist already carries "Fix #99 while in QUICK-REFERENCE.md" and #110 row 7 routes it there, so no separate PR; the cache-key lines are on no other checklist, so carry them in the same PR and close this as a duplicate of #109. Line edit only: PLAN item 10 (PLAN.md:80) proposes shrinking QUICK-REFERENCE.md to a one-screen link table, removing the troubleshooting block.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the three stale references: docs/QUICK-REFERENCE.md:312-317, docs/MIGRATION-GUIDE.md:244, and docs/ARCHITECTURE.md:68. Compare them with the correct examples and the referenced action definitions at publish-gh-pages/action.yml:68-78 and build-jupyter-cache/action.yml:95. Done means the Pages permissions and cache key match the action behavior, while the setup-environment drift remains out of scope.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github-actions
- Domain
- ci-cd, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 20/100