| name | publish |
| description | Step-by-step release workflow for publishing diary-kg to PyPI using Poetry. Use this skill when the user wants to cut a release, bump the version, update the CHANGELOG, tag a commit, build and publish to PyPI, or run any part of the release pipeline for the diary-kg project. |
Publish Skill — diary-kg Release Workflow
Prerequisites
- Clean working tree (
git status shows no uncommitted changes)
- All tests passing (
poetry run pytest)
- Pre-commit checks passing (
pre-commit run --all-files)
- PyPI credentials configured (
poetry config pypi-token.pypi <token>)
Release Steps
1. Decide the version bump
Follow Semantic Versioning:
| Change | Bump |
|---|
| Bug fixes only | patch (0.5.2 → 0.5.3) |
| New features, backward-compatible | minor (0.5.2 → 0.6.0) |
| Breaking changes | major (0.5.2 → 1.0.0) |
2. Update CHANGELOG.md
Move items from ## [Unreleased] to a new versioned section:
## [X.Y.Z] - YYYY-MM-DD
Leave ## [Unreleased] empty at the top for future entries.
3. Bump version in pyproject.toml and src/diary_kg/init.py
poetry version patch
Then update __version__ in src/diary_kg/__init__.py to match.
Verify: grep '^version' pyproject.toml and grep __version__ src/diary_kg/__init__.py
4. Commit the release
git add pyproject.toml src/diary_kg/__init__.py CHANGELOG.md
DIARYKG_SKIP_SNAPSHOT=1 git commit -m "chore: release vX.Y.Z"
Use DIARYKG_SKIP_SNAPSHOT=1 to prevent the pre-commit hook from rebuilding indices and writing a snapshot on a release commit.
5. Tag the release
git tag -a vX.Y.Z -m "Release vX.Y.Z"
6. Build the distribution
poetry build
Artifacts appear in dist/. Verify they look correct:
ls -lh dist/
7. Publish to PyPI
poetry publish
To test against TestPyPI first:
poetry publish -r testpypi
8. Push to GitHub
git push origin main --tags
After Release
- Save a PyCodeKG snapshot of the released source:
pycodekg snapshot save X.Y.Z --repo .
- Save a DiaryKG corpus snapshot if the corpus changed:
diarykg snapshot save -v X.Y.Z
Rollback
If something went wrong after poetry publish:
- PyPI releases cannot be deleted (only yanked):
poetry run twine yank diary-kg X.Y.Z
- Revert the commit:
git revert HEAD then git push
- Delete the tag:
git tag -d vX.Y.Z && git push origin :refs/tags/vX.Y.Z
