Repository navigation
Setup docs point at files a render does not contain, and describe a manual publish route that publishes nothing #15
Copy link
Copy link
Closed
Labels
documentationImprovements or additions to documentationImprovements or additions to documentation
Description
Versions: python-library-template 8ebf45d, Copier 9.18.2
The setup instructions have drifted from what a render actually contains, in three places:
- The post-generation message ends with "See NEW_LIBRARY_CHECKLIST.md for full details." (
copier.yml:47-57). ButNEW_LIBRARY_CHECKLIST.md.jinjasits in the repository root, outside_subdirectory: template, so it is never rendered. 7509b31 moved it there fromtemplate/. A new project has no file by that name. The checklist still opens with "Delete this file after completing setup", which suggests it was meant to be generated. README.md:45-48says to runpython scripts/setup_repo.py ...and thengit rm scripts/setup_repo.py .claude/LIBRARY_CREATION.mdin the new library.README.md:66and.claude/LIBRARY_CREATION.md:25-54repeat the instruction ("Must Delete Before First Commit"). Neither file is in a render, because both live only in the template repository; a render'sscripts/holds justemit_markdown.py. Thegit rmfails. Step 3 of the checklist is right: run the script from the template repository.NEW_LIBRARY_CHECKLIST.md.jinja:84-89describes a manual publish route:git tag <slug>-v0.1.0,git push origin <slug>-v0.1.0, "Then create a GitHub Release from that tag". Since 4c9f596 (May 24),publish.ymllistens only toworkflow_runof Release Please and toworkflow_dispatch, so pushing a tag or creating a Release triggers nothing. The real manual route isgh workflow run publish.yml -f tag=<slug>-vX.Y.Z(but see publish.yml can publish from any branch or tag: the pypi environment has no deployment policy and the tag input is used as-is #10 about that input).
Reproduction
In a render of 8ebf45d (copier copy --defaults --trust --vcs-ref 8ebf45d gh:bedrock-python/python-library-template demo-lib):
cd demo-lib
ls NEW_LIBRARY_CHECKLIST.md scripts/setup_repo.py .claude/LIBRARY_CREATION.md; ls scripts
git init -q -b master && git add -A && git commit -qm init
git rm scripts/setup_repo.py .claude/LIBRARY_CREATION.md
sed -n '3,11p' .github/workflows/publish.ymlActual
> Running task 1 of 1: echo "Template generated. Next steps: ... See NEW_LIBRARY_CHECKLIST.md for full details."
ls: cannot access 'NEW_LIBRARY_CHECKLIST.md': No such file or directory
ls: cannot access 'scripts/setup_repo.py': No such file or directory
ls: cannot access '.claude/LIBRARY_CREATION.md': No such file or directory
emit_markdown.py
fatal: pathspec 'scripts/setup_repo.py' did not match any files
on:
workflow_run:
workflows: ["Release Please"]
types: [completed]
workflow_dispatch:
inputs:
tag:
description: "Release tag to publish (e.g. demo-lib-v0.1.0 or v0.1.0)"
required: true
There is no push: tags trigger and no release trigger.
Why
These are the first instructions a new library's author reads, and each of the three either points at nothing or fails. The third is the worst: it ends in a tag and a GitHub Release with nothing published, and nothing reports an error.
Proposal
- Move the checklist back to
template/NEW_LIBRARY_CHECKLIST.md.jinjaso the post-generation message is true. It already renders project-specific commands and tells the reader to delete it afterwards. Alternatively, keep it in the template repository and have the message link to it by URL. - Remove the
git rmline fromREADME.md:48, the "Deletescripts/setup_repo.pybefore initial commit" bullet atREADME.md:66, and sections 2-3 of.claude/LIBRARY_CREATION.md. Keep "run it from the template repo". - Replace "Or to publish manually" with the
workflow_dispatchcommand, or drop it until publish.yml can publish from any branch or tag: the pypi environment has no deployment policy and the tag input is used as-is #10 settles how a manual publish should look.
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
documentationImprovements or additions to documentationImprovements or additions to documentation
Activity
AlexeyShalaev commentedon Oct 16, 2026
Plan, one point at a time:
template/NEW_LIBRARY_CHECKLIST.md.jinja, so the post-generation message points at a file that exists. I checked that this works with Generated projects have no .copier-answers.yml, so copier update cannot bring template fixes into them #14. After a library deletes the checklist,copier update(9.19.1) leaves it deleted, even when the template has changed it since.git rmline, the "deletescripts/setup_repo.py" bullets and sections 2–3 of.claude/LIBRARY_CREATION.mdgo. What's left says to run the script from the template repository.gh workflow run publish.yml -f tag=<slug>-vX.Y.Z, run frommaster. That command is right today and stays right after publish.yml can publish from any branch or tag: the pypi environment has no deployment policy and the tag input is used as-is #10/Publish does not wait for CI on the released commit, and overwrites __version__.py from the tag instead of checking it #11. The fix there keeps the input but only accepts it frommaster, for a tag whose commit is onmasterand passed CI. The tag-push recipe is removed.AlexeyShalaev commentedon Oct 16, 2026
The fix is in #22. The checklist is rendered again, the
git rmand delete instructions are gone, and the manual route isgh workflow run publish.yml --ref master -f tag=<tag>, which stays right after #18.docs: setup instructions match what a render contains
docs: setup instructions match what a render contains (#22)