From 358907b51f1d79e5b3bebe21254cb3720ce5867f Mon Sep 17 00:00:00 2001 From: tegwick Date: Wed, 27 May 2026 00:11:18 +0200 Subject: [PATCH] =?UTF-8?q?docs=20+=20chore(workplan):=20complete=20T05=20?= =?UTF-8?q?for=20CYA-WP-0004=20=E2=80=94=20lightweight=20release=20process?= =?UTF-8?q?=20(checklist=20+=20Makefile=20targets)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Makefile | 19 ++- docs/release-process.md | 117 ++++++++++++++++++ ...-0004-dev-install-and-release-packaging.md | 25 ++-- 3 files changed, 147 insertions(+), 14 deletions(-) create mode 100644 docs/release-process.md diff --git a/Makefile b/Makefile index 5b1dd13..4b81cbc 100644 --- a/Makefile +++ b/Makefile @@ -1,7 +1,7 @@ # Simple developer Makefile for can-you-assist # Focus: easy dev-head install and common tasks -.PHONY: dev-install install test clean dist +.PHONY: dev-install install test clean dist version release-prep check-dist # Install the package in editable mode from the current source # This is the recommended way to work on the latest code @@ -27,4 +27,19 @@ dist: clean # Show current version (useful after setuptools_scm changes) version: - python3 -c "import cya; print(cya.__version__)" \ No newline at end of file + python3 -c "import cya; print(cya.__version__)" + +# Prepare for a release (run tests + build clean artifacts) +release-prep: clean test dist + @echo "" + @echo "Release artifacts ready in dist/" + @echo "Next steps: create annotated git tag and push it." + +# Verify the built wheel in an isolated environment +check-dist: + @echo "Testing wheel in fresh venv..." + @python3 -m venv /tmp/cya-dist-check + @/tmp/cya-dist-check/bin/pip install dist/can_you_assist-*.whl --quiet + @/tmp/cya-dist-check/bin/cya --version + @rm -rf /tmp/cya-dist-check + @echo "Wheel verification successful." \ No newline at end of file diff --git a/docs/release-process.md b/docs/release-process.md new file mode 100644 index 0000000..c72e352 --- /dev/null +++ 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-.tar.gz` (sdist) +- `can_you_assist--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. \ No newline at end of file diff --git a/workplans/CYA-WP-0004-dev-install-and-release-packaging.md b/workplans/CYA-WP-0004-dev-install-and-release-packaging.md index 41c7d72..e03f5cf 100644 --- a/workplans/CYA-WP-0004-dev-install-and-release-packaging.md +++ b/workplans/CYA-WP-0004-dev-install-and-release-packaging.md @@ -144,23 +144,24 @@ completed: "2026-05-27" ```task id: CYA-WP-0004-T05 -status: todo +status: done priority: medium state_hub_task_id: "c97acc58-14d7-47b9-9ab3-936ab1eb92df" +started: "2026-05-27 ralph iter 5" +completed: "2026-05-27" ``` -- Document (and optionally script) the steps to cut a release: - 1. Decide on new version - 2. Update version metadata - 3. Run tests - 4. Build packages - 5. Create git tag -- Consider a small helper script or Makefile targets (`make release-prep`, `make build-dist`). -- Ensure the process is reproducible and documented in a `docs/release-process.md` or similar. +**Done.** -**Acceptance criteria**: -- A clear, written release checklist or script exists that a maintainer can follow with low risk of mistakes. -- The process produces artifacts that could be uploaded to a package index. +- Created `docs/release-process.md` — a clear, step-by-step, low-risk release checklist covering version decision → tests → build → tagging. +- Enhanced the `Makefile` with two very useful release targets: + - `make release-prep` (runs clean + test + dist in one go) + - `make check-dist` (smoke-tests the built wheel in a fresh venv) +- The process is fully reproducible and documented. + +**Acceptance criteria met**: +- A maintainer now has a written checklist + Makefile helpers that make cutting a release feel safe and boring. +- The process produces ready-to-upload artifacts. ### T06 — Update documentation for both installation methods