| name | publish |
| description | Step-by-step release workflow for publishing ftree-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 ftree-kg project. |
Publish Skill — ftree-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
poetry version patch
Verify: grep '^version' pyproject.toml
4. Commit the release
git add pyproject.toml CHANGELOG.md
FTREEKG_SKIP_SNAPSHOT=1 git commit -m "chore: release vX.Y.Z"
Use FTREEKG_SKIP_SNAPSHOT=1 to prevent the post-commit hook from creating 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
- Update any docs referencing the install command or version if they changed
- Save a snapshot:
ftreekg snapshot save X.Y.Z --repo . --commit $(git rev-parse HEAD) --branch main
Rollback
If something went wrong after poetry publish:
- PyPI releases cannot be deleted (only yanked):
poetry run twine yank ftree-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
