# 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.