Skip to content

Setup docs point at files a render does not contain, and describe a manual publish route that publishes nothing #15

Closed

Description

@AlexeyShalaev

Versions: python-library-template 8ebf45d, Copier 9.18.2

The setup instructions have drifted from what a render actually contains, in three places:

  1. The post-generation message ends with "See NEW_LIBRARY_CHECKLIST.md for full details." (copier.yml:47-57). But NEW_LIBRARY_CHECKLIST.md.jinja sits in the repository root, outside _subdirectory: template, so it is never rendered. 7509b31 moved it there from template/. 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.
  2. README.md:45-48 says to run python scripts/setup_repo.py ... and then git rm scripts/setup_repo.py .claude/LIBRARY_CREATION.md in the new library. README.md:66 and .claude/LIBRARY_CREATION.md:25-54 repeat the instruction ("Must Delete Before First Commit"). Neither file is in a render, because both live only in the template repository; a render's scripts/ holds just emit_markdown.py. The git rm fails. Step 3 of the checklist is right: run the script from the template repository.
  3. NEW_LIBRARY_CHECKLIST.md.jinja:84-89 describes 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.yml listens only to workflow_run of Release Please and to workflow_dispatch, so pushing a tag or creating a Release triggers nothing. The real manual route is gh 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.yml

Actual

 > 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.jinja so 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 rm line from README.md:48, the "Delete scripts/setup_repo.py before initial commit" bullet at README.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_dispatch command, 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.

Activity

  1. AlexeyShalaev commented on Oct 16, 2026

    @AlexeyShalaev
    MemberAuthor

    Plan, one point at a time:

    1. The checklist moves back to 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.
    2. The git rm line, the "delete scripts/setup_repo.py" bullets and sections 2–3 of .claude/LIBRARY_CREATION.md go. What's left says to run the script from the template repository.
    3. "Or to publish manually" becomes gh workflow run publish.yml -f tag=<slug>-vX.Y.Z, run from master. 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 from master, for a tag whose commit is on master and passed CI. The tag-push recipe is removed.
  2. AlexeyShalaev commented on Oct 16, 2026

    @AlexeyShalaev
    MemberAuthor

    The fix is in #22. The checklist is rendered again, the git rm and delete instructions are gone, and the manual route is gh workflow run publish.yml --ref master -f tag=<tag>, which stays right after #18.

  3. added a commit that references this issue on Oct 16, 2026
    07ab2f8
  4. added a commit that references this issue on Oct 16, 2026
    6bfcef6
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions