Pratik Bhadane
213 lines
6.4 KiB
Markdown
213 lines
6.4 KiB
Markdown
# Release Playbook
|
|
|
|
This document describes the step-by-step process for cutting a new **ferro-ta** release.
|
|
Follow every step in order to produce a consistent, reproducible release.
|
|
|
|
For the packaging and release overview, see [PACKAGING.md](PACKAGING.md).
|
|
|
|
---
|
|
|
|
## Publish matrix (all automatic on release)
|
|
|
|
| Artifact | How |
|
|
|-------------|-----|
|
|
| **PyPI** | CI job `publish` using PyPI Trusted Publishing (OIDC) |
|
|
| **npm (WASM)** | Workflow `wasm-publish`|
|
|
| **crates.io** | CI job `publish-cratesio` |
|
|
|
|
PyPI releases are expected to include:
|
|
|
|
- Wheels for CPython 3.10, 3.11, 3.12, and 3.13
|
|
- Linux x86_64 (`manylinux_2_17`)
|
|
- macOS universal2
|
|
- Windows x86_64
|
|
- One source distribution (`sdist`)
|
|
|
|
---
|
|
|
|
## Pre-release checklist
|
|
|
|
Before starting a release:
|
|
|
|
- [ ] All CI checks are green on `main`: Rust (fmt, clippy), tests (with coverage gate),
|
|
lint (ruff), typecheck (mypy, pyright), docs (Sphinx), WASM, audit (cargo-audit,
|
|
pip-audit), fuzz (no crashes).
|
|
- [ ] **Security audit clean:** Run `cargo audit` and `pip-audit` locally and confirm
|
|
no high/critical vulnerabilities. Address any findings before tagging.
|
|
```bash
|
|
cargo audit
|
|
pip-audit # or: uv run --with pip-audit pip-audit
|
|
```
|
|
- [ ] No open blocking issues or PRs that must land first.
|
|
- [ ] `CHANGELOG.md` has a `## [X.Y.Z]` section (not `[Unreleased]`) with all
|
|
changes since the last release documented under `### Added`, `### Changed`,
|
|
`### Fixed`, `### Removed` headings.
|
|
- [ ] Public docs match the release: `docs/conf.py`, `docs/changelog.rst`, and
|
|
`docs/support_matrix.rst` reflect the version and current support status.
|
|
|
|
---
|
|
|
|
## Step 1 — Decide the version number
|
|
|
|
Follow [Semantic Versioning 2.0.0](https://semver.org/) and the policy in
|
|
[VERSIONING.md](VERSIONING.md):
|
|
|
|
| Change type | Version component to bump |
|
|
|---|---|
|
|
| Breaking API change (indicator removed, parameter renamed, return type changed) | **MAJOR** |
|
|
| New indicators, features, or bindings (backward-compatible) | **MINOR** |
|
|
| Bug fixes, performance, docs-only, dependency bumps | **PATCH** |
|
|
|
|
Example: current version is `0.1.0` and you are adding new indicators → new version is `0.2.0`.
|
|
|
|
---
|
|
|
|
## Step 2 — Sync version everywhere
|
|
|
|
These files must carry **the same version string** (e.g. `0.2.0`). The easiest
|
|
way to do that is:
|
|
|
|
```bash
|
|
python3 scripts/bump_version.py 0.2.0
|
|
python3 scripts/bump_version.py --check
|
|
```
|
|
|
|
That script updates the tracked release-version carriers for you.
|
|
|
|
Files covered by the bump script:
|
|
|
|
| File | Location |
|
|
|------|----------|
|
|
| `Cargo.toml` | Root (source of truth) |
|
|
| `crates/ferro_ta_core/Cargo.toml` | Same version for crates.io publish |
|
|
| `crates/ferro_ta_core/README.md` | Installation snippet should show the current crate version |
|
|
| `pyproject.toml` | Root |
|
|
| `wasm/package.json` | Package version |
|
|
| `conda/meta.yaml` | Conda recipe version |
|
|
| `docs/conf.py` | Default Sphinx release must resolve to the same version |
|
|
|
|
**`Cargo.toml`** (root):
|
|
```toml
|
|
[package]
|
|
name = "ferro_ta"
|
|
version = "X.Y.Z" # ← or use scripts/bump_version.py X.Y.Z
|
|
```
|
|
|
|
**`pyproject.toml`**:
|
|
```toml
|
|
[project]
|
|
version = "X.Y.Z" # ← must match Cargo.toml exactly
|
|
```
|
|
|
|
> **Rule:** `Cargo.toml` is the source of truth. Sync the others to match before tagging.
|
|
|
|
---
|
|
|
|
## Step 3 — Update CHANGELOG.md
|
|
|
|
1. Open `CHANGELOG.md`.
|
|
2. Rename the `[Unreleased]` section to `[X.Y.Z] — YYYY-MM-DD` (today's date).
|
|
3. Add a fresh empty `[Unreleased]` section at the top.
|
|
4. Update the comparison links at the bottom:
|
|
|
|
```markdown
|
|
[Unreleased]: https://github.com/pratikbhadane24/ferro-ta/compare/vX.Y.Z...HEAD
|
|
[X.Y.Z]: https://github.com/pratikbhadane24/ferro-ta/compare/vPREVIOUS...vX.Y.Z
|
|
```
|
|
|
|
Follow the [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format:
|
|
`Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`.
|
|
|
|
Also update the docs-facing release surfaces for the same version:
|
|
|
|
- `docs/changelog.rst` with a concise release-notes entry
|
|
- `docs/support_matrix.rst` if supported versions, tested wheels, or module
|
|
stability changed
|
|
|
|
---
|
|
|
|
## Step 4 — Commit the version bump
|
|
|
|
```bash
|
|
git add Cargo.toml crates/ferro_ta_core/Cargo.toml pyproject.toml wasm/package.json CHANGELOG.md
|
|
git commit -m "chore: release v0.2.0"
|
|
git push origin main
|
|
```
|
|
|
|
Wait for CI to pass on this commit before proceeding.
|
|
|
|
---
|
|
|
|
## Step 5 — Create and push the tag
|
|
|
|
```bash
|
|
git tag v0.2.0
|
|
git push origin v0.2.0
|
|
```
|
|
|
|
> Tags must be in the form `vMAJOR.MINOR.PATCH` (e.g. `v0.2.0`).
|
|
|
|
---
|
|
|
|
## Step 6 — Create a GitHub Release
|
|
|
|
1. Go to **Releases → Draft a new release** in the GitHub UI.
|
|
2. Select the tag `v0.2.0` you just pushed.
|
|
3. Set the release title to `v0.2.0`.
|
|
4. Paste the changelog section for `v0.2.0` into the release notes.
|
|
5. Click **Publish release**.
|
|
|
|
Publishing the release triggers the CI wheel build jobs, `build-sdist`, and `publish`
|
|
automatically (the workflow responds to `release: published`). The PyPI upload
|
|
uses Trusted Publishing via GitHub OIDC, so no `PYPI_API_TOKEN` secret is used.
|
|
|
|
---
|
|
|
|
## Step 7 — Monitor CI and verify PyPI
|
|
|
|
1. Watch the **Actions** tab: the release wheel jobs, `build-sdist`, `publish` (PyPI), `publish-cratesio` (crates.io), and the **wasm-publish** workflow (npm).
|
|
2. After the `publish` job succeeds, verify the package is live:
|
|
|
|
```bash
|
|
pip install ferro-ta==0.2.0
|
|
python -c "import ferro_ta; print(ferro_ta.__version__ if hasattr(ferro_ta,'__version__') else 'ok')"
|
|
```
|
|
|
|
For version-specific verification, also check at least one install on each
|
|
supported Python line, for example:
|
|
|
|
```bash
|
|
uv venv --python 3.13 .venv-313
|
|
. .venv-313/bin/activate
|
|
uv pip install ferro-ta==0.2.0
|
|
python -c "import ferro_ta; print(ferro_ta.SMA([1.0, 2.0, 3.0], 2))"
|
|
```
|
|
|
|
3. If anything fails: fix the issue, bump to a patch version (`0.2.1`), and repeat.
|
|
|
|
---
|
|
|
|
|
|
---
|
|
|
|
## Hotfix releases
|
|
|
|
For urgent bug fixes on a released version:
|
|
|
|
1. Branch from the release tag: `git checkout -b hotfix/0.1.1 v0.1.0`
|
|
2. Apply the fix, bump to `0.1.1`, update CHANGELOG.
|
|
3. Merge the branch into `main`.
|
|
4. Tag and release as above.
|
|
|
|
---
|
|
|
|
> **Note:** `ferro_ta_core` is published to crates.io automatically by the CI job `publish-cratesio` when you publish a release (requires `CARGO_REGISTRY_TOKEN` secret).
|
|
|
|
---
|
|
|
|
## See also
|
|
|
|
- [VERSIONING.md](VERSIONING.md) — versioning policy and breaking-change rules
|
|
- [CHANGELOG.md](CHANGELOG.md) — changelog history
|
|
- [CONTRIBUTING.md](CONTRIBUTING.md) — development setup and PR guidelines
|