can-you-assist/docs/release-process.md

Release Process (Lightweight)

Goal: Cut a new release of can-you-assist with low risk of mistakes and produce clean distribution artifacts.

This process is intentionally manual and lightweight. It can be automated later (CI + PyPI publishing).

Prerequisites

• You have write access to the repository.
• You have run make dev-install (or equivalent) so all dev tools are available.
• You are on a clean main branch with all changes committed and pushed.

Step-by-Step Release Process

1. Decide on the new version

Use semantic versioning:

• MAJOR.MINOR.PATCH (e.g., 0.2.0, 0.3.1, 1.0.0)

Check the current version:

make version

Decide the next version and note it (e.g., 0.2.0).

2. Update version metadata (if not using git tags for releases)

Note

: With setuptools_scm (T02), the version is primarily driven by git tags for releases. For a clean release, we will create a git tag. The version in pyproject.toml can stay dynamic.

If you want an explicit version bump before tagging (optional but sometimes useful for clarity):

• The version is derived from the upcoming git tag. You do not need to edit files for the release version itself.

3. Run the full test suite

make test

All tests must pass.

4. Build clean distribution packages

make clean
make dist

This produces artifacts in dist/:

• can_you_assist-<version>.tar.gz (sdist)
• can_you_assist-<version>-py3-none-any.whl (wheel)

5. (Optional but recommended) Smoke-test the built wheel

python3 -m venv /tmp/verify-release
/tmp/verify-release/bin/pip install dist/can_you_assist-*.whl
/tmp/verify-release/bin/cya --version
/tmp/verify-release/bin/cya --help
rm -rf /tmp/verify-release

The cya command must work and report the correct release version.

6. Commit any final release-related changes (if any)

Normally there should be none after T02 (versioning is dynamic via tags).

7. Create and push the release tag

git tag -a v0.2.0 -m "Release v0.2.0"
git push origin v0.2.0

This tag will be picked up by setuptools_scm on the next build and will produce the clean version 0.2.0.

8. (Future) Upload to PyPI

Once we have a PyPI publication workflow:

python -m twine upload dist/*

For now, the dist/ artifacts can be shared manually or attached to a GitHub release.

Makefile Targets Useful for Releases

make clean          # Remove build artifacts
make dist           # Build sdist + wheel (recommended)
make version        # Show current version
make test           # Run tests

You can add more targets later (e.g., make release-prep that combines clean + test + dist).

Safety Notes

• Never push a tag until you have verified the build and tests.
• Release tags should be annotated (-a).
• After a release, you can continue development on main — the next dev versions will automatically become 0.2.0.devN+... thanks to setuptools_scm.

Future Improvements (Out of Scope for This Slice)

• Automated release via GitHub Actions on tag push
• Automatic PyPI upload on release
• Changelog generation from commits
• Signed releases

---

This process is intentionally simple so a single maintainer can execute it reliably with low cognitive load.