generated from coulomb/repo-seed
117 lines
3.2 KiB
Markdown
117 lines
3.2 KiB
Markdown
# 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. |