Skip to content

docs: setup instructions match what a render contains - #22

Merged
AlexeyShalaev merged 1 commit into
masterfrom
fix/15-setup-docs
Oct 16, 2026
Merged

AlexeyShalaev merged 1 commit into
masterfrom
fix/15-setup-docs

Conversation

@AlexeyShalaev

Copy link
Copy Markdown
Member

The problem

The setup instructions had drifted from what a render contains:

  1. The post-generation message ends with "See NEW_LIBRARY_CHECKLIST.md". 7509b31 moved that file out of template/, so no render had it.
  2. README.md and .claude/LIBRARY_CREATION.md said to git rm scripts/setup_repo.py .claude/LIBRARY_CREATION.md in the new library. Neither file is in a render, so the command fails.
  3. The checklist's manual publish route was to push a tag and create a GitHub Release. Since 4c9f596, publish.yml listens only to Release Please's workflow_run and to workflow_dispatch, so that route ends in a tag and a Release, with nothing published and no error.

The decision

  1. The checklist is rendered again (template/NEW_LIBRARY_CHECKLIST.md.jinja). It already renders project-specific commands and tells the reader to delete it, and the "Done" list now ends with that step. I considered keeping it in the template repository and linking to it by URL. A rendered copy has the project's own slug, org and package name in every command, and with Generated projects have no .copier-answers.yml, so copier update cannot bring template fixes into them #14 in place it costs nothing later. I checked with Copier 9.19.1 that a library which deleted the checklist keeps it deleted through copier update, even after the template changes it.
  2. The delete instructions are gone. What's left says to run setup_repo.py from the template repository after the first CI pass. That is the checklist's Step 3, and the only way it works. .claude/LIBRARY_CREATION.md §3 now follows that order (generate, commit, create and push, then setup), and its checklists no longer ask to delete files that aren't there.
  3. The manual route is the dispatch: gh workflow run publish.yml --ref master -f tag=<slug>-vX.Y.Z. All ten successful manual publishes in the org were done this way. It is also right after fix: publish only reviewed commits that passed CI #18, which keeps the input but only accepts it from master for a tag on master whose CI passed. The checklist now says that pushing a tag or creating a Release publishes nothing.

Evidence

Render of origin/master against a render of this branch:

before: ls: cannot access 'NEW_LIBRARY_CHECKLIST.md': No such file or directory
after:  NEW_LIBRARY_CHECKLIST.md        (no unrendered {{ }} or {% %} left; commands read demo-lib / demo_lib)
both:   scripts/ = emit_markdown.py only, no .claude/   (so the removed git rm could never have worked)

The rendered Step 6 now reads:

gh workflow run publish.yml --ref master -f tag=demo-lib-v0.1.0

The generated gate passes with the checklist present: ruff (which excludes *.md) and mypy are clean, 1 test passed, and uv build builds both files. The checklist is not in the sdist, whose include list is explicit.

Closes #15

The post-generation message pointed at NEW_LIBRARY_CHECKLIST.md, which
7509b31 had moved out of template/, so no render contained it. README.md and
.claude/LIBRARY_CREATION.md told the reader to git rm scripts/setup_repo.py
and .claude/LIBRARY_CREATION.md from the new library, and neither file is in
a render. The checklist's manual publish route pushed a tag and created a
GitHub Release, and nothing listens to either.

The checklist is rendered again (copier update leaves it deleted once a
library deletes it). The delete instructions are gone, and what remains says
to run setup_repo.py from the template repository. The manual route is the
Publish workflow's dispatch from master, which is how every successful
manual publish in the org has been done.

Closes #15
@AlexeyShalaev
AlexeyShalaev merged commit 6bfcef6 into master Oct 16, 2026
3 checks passed
@AlexeyShalaev
AlexeyShalaev deleted the fix/15-setup-docs branch October 16, 2026 15:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

1 participant