docs + chore(workplan): complete T05 for CYA-WP-0004 — lightweight release process (checklist + Makefile targets)

2026-05-27 00:11:18 +02:00
parent 2306f05ebf
commit 358907b51f
3 changed files with 147 additions and 14 deletions
--- a/docs/release-process.md
+++ b/docs/release-process.md
@@ -0,0 +1,117 @@
+# 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:
+
+```bash
+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
+
+```bash
+make test
+```
+
+All tests must pass.
+
+### 4. Build clean distribution packages
+
+```bash
+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
+
+```bash
+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
+
+```bash
+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:
+
+```bash
+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
+
+```bash
+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.