# Prep Release

> Release Preparation

- Skill: `koaning/prep-release` (Agent Skill)
- Install (CLI): `npx skillmds@latest add koaning/prep-release`
- Raw SKILL.md: https://api.skillmd.com/api/skills/koaning/prep-release/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: koaning (https://skillmd.com/u/koaning)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/koaning/prep-release

---

# Release Preparation

Prepare a new wigglystuff release. Follow these steps:

## Instructions

1. **Determine the new version**: Read `pyproject.toml` for the current version and the latest entry in `CHANGELOG.md`. If the version has already been bumped, use that. Otherwise, bump the patch version (e.g., 0.2.24 -> 0.2.25).

2. **Bump version** in `pyproject.toml` (if not already done).

3. **Add a changelog entry** at the top of `CHANGELOG.md` following the existing format:
   - Use `## [x.y.z] - YYYY-MM-DD` header with today's date
   - Add `### Added`, `### Changed`, `### Fixed`, or `### Removed` subsections as appropriate
   - Look at the git diff against `main` to determine what changed

4. **Update all documentation locations** for any new widgets:
   - `docs/reference/<widget-name>.md` — create a reference doc following the pattern in existing reference pages (use `::: wigglystuff.module.ClassName` mkdocstrings directive + a synced traitlets table)
   - `zensical.toml` — add the widget to the `nav` Reference section
   - `docs/index.md` — add to the appropriate gallery section (main gallery or 3rd party gallery)
   - `readme.md` — add to the appropriate gallery table (main gallery or 3rd party table)
   - `docs/llms.txt` — add a one-line entry in the appropriate section
   - `CLAUDE.md` — add a row to the quick reference table
   - `wigglystuff/__init__.py` — verify the widget is imported and listed in `__all__`

5. **For 3rd party widgets** (those requiring non-core dependencies like neo4j, torch, wandb):
   - Place them in the "3rd party widgets" section of the galleries (not the main gallery)
   - Use a molab link for the demo instead of a local example page
   - Use `MOLAB_LINK_HERE` as a placeholder if the molab link is not yet available and tell the user they need to fill it in
   - Screenshot path should be `docs/assets/gallery/<widgetname>.webp` — tell the user if one is missing (run `uv run python scripts/png_to_webp.py` if a PNG was added)

6. **Check dependencies**: Read `pyproject.toml` and verify that no 3rd party widget dependency (neo4j, torch, wandb, etc.) has been added to core `[project] dependencies`. These must only appear under `[project.optional-dependencies]` as extras. Core dependencies should only include packages needed by all widgets (anywidget, numpy, pillow, python-dotenv). If a 3rd party dep has leaked into core dependencies, remove it.

7. **Bump demo `wigglystuff==X.Y.Z` pins**: Every `demos/*.py` notebook has a PEP 723 `# /// script` header pinning a published `wigglystuff` version. For any demo that was added or modified in this release (anything in `git diff origin/main -- demos/` since the previous tag), update its pin to the new version. Otherwise `uv run demos/<name>.py` will fetch the old release and the new feature will be missing. Grep `demos/ -l "wigglystuff=="` to find pins; you do not need to bump untouched demos.

8. **Verify nothing is missed**: Check the git diff to make sure all new/changed widgets have corresponding updates in all locations listed above.

9. **Commit, push, and open a PR — but do NOT merge.** Run the mechanics without asking for confirmation: commit the release changes, push the branch, and open a PR against `main` (`gh pr create --base main`). Then STOP — leave the merge to the user; never run `gh pr merge`. Only pause earlier if there's a genuine blocker (failing tests, merge conflicts, ambiguous diff) — not for the commit/PR steps themselves.

10. **Report** what was done and what still needs manual action (e.g., adding screenshots, replacing molab link placeholders).