Pratik Bhadane
307beeca02
Prepare the first public 1.0.0 release and finish the remaining CI hardening work. Highlights: - align Python, Rust, WASM, Conda, API, MCP, and docs version metadata to 1.0.0 - promote package metadata to Production/Stable and update stability/versioning docs for the stable series - move the accumulated Unreleased notes into a dated 1.0.0 changelog section and keep a fresh top-level Unreleased block - strengthen the changelog checker so it validates a single top-level Unreleased section - fix the CI/package support mismatch by declaring Python >=3.10 consistently and gating pandas-ta extras to Python 3.12+ - restore Sphinx autodoc compatibility for documented ferro_ta.<module> imports by registering module aliases - make the TA-Lib benchmark guardrail less flaky by checking median and tail-percentile speedups instead of failing on a single mild outlier - switch PyPI publishing to OIDC-only trusted publishing and wire the changelog check into the required CI gate - apply the Ruff-driven cleanup across the Python and test tree and refresh uv/cargo lockfiles Validated locally: - python3 scripts/check_changelog.py - uv run --with ruff ruff check python tests - uv run --with ruff ruff format --check python tests - uv lock --check - sphinx-build -b html docs docs/_build -W --keep-going - build/install the ferro_ta 1.0.0 wheel successfully
108 lines
4.0 KiB
Markdown
108 lines
4.0 KiB
Markdown
# Versioning & Release Policy
|
||
|
||
**ferro-ta** uses [Semantic Versioning 2.0.0](https://semver.org/).
|
||
|
||
## Version numbers: `MAJOR.MINOR.PATCH`
|
||
|
||
| Component | Increment when… |
|
||
|-----------|-----------------|
|
||
| **MAJOR** | A breaking API change is introduced (indicator removed, parameter renamed, return-type changed). |
|
||
| **MINOR** | New indicators, features, or bindings are added in a backward-compatible way. |
|
||
| **PATCH** | Bug fixes, performance improvements, documentation-only changes, or dependency bumps that do not change the public API. |
|
||
|
||
## Supported Python versions
|
||
|
||
We support the **three most recent stable Python minor releases** at the time
|
||
of a MINOR or MAJOR release. Python versions that have reached end-of-life
|
||
(EOL) per the [Python release calendar](https://devguide.python.org/versions/)
|
||
are removed in the next MINOR release; this counts as a non-breaking change.
|
||
|
||
Currently supported: **3.10, 3.11, 3.12, 3.13** (see `pyproject.toml`).
|
||
|
||
## Release playbook
|
||
|
||
1. **Bump the version** in `Cargo.toml` and `pyproject.toml` to the new version
|
||
(e.g. `1.0.1`).
|
||
2. **Update `CHANGELOG.md`**: move the `[Unreleased]` block to a new dated section
|
||
`[1.0.1] — YYYY-MM-DD` and open a fresh `[Unreleased]` block.
|
||
3. **Commit** the version bump and changelog update with message
|
||
`chore: release v1.0.1`.
|
||
4. **Create a tag**: `git tag v1.0.1 && git push origin v1.0.1`.
|
||
5. **Create a GitHub Release** for tag `v1.0.1` — the CI `build-wheels` and
|
||
`publish` jobs trigger automatically on `release: published`.
|
||
|
||
## Breaking-change policy
|
||
|
||
- Removing an indicator or changing its signature is a **MAJOR** change.
|
||
- Changing a default parameter value is a **MINOR** change (with a deprecation
|
||
notice in the changelog).
|
||
- Fixing a numeric output to match TA-Lib more closely is a **PATCH** change
|
||
(but noted clearly in the changelog).
|
||
|
||
## Changelog maintenance
|
||
|
||
Every PR that changes user-visible behaviour must add an entry to the
|
||
`[Unreleased]` section of `CHANGELOG.md`. CI enforces this for PRs that
|
||
touch `src/`, `python/`, or `wasm/`.
|
||
|
||
---
|
||
|
||
## API Stability Guarantees
|
||
|
||
The following modules are considered **stable API** as of `1.0.0` and will not
|
||
have breaking changes in minor releases:
|
||
|
||
| Module | Stability |
|
||
|---|---|
|
||
| `ferro_ta` (top-level) — all `__all__` names | Stable |
|
||
| `ferro_ta.overlap`, `ferro_ta.momentum`, etc. | Stable |
|
||
| `ferro_ta.batch` | Stable |
|
||
| `ferro_ta.streaming` | Stable |
|
||
| `ferro_ta.extended` | Stable |
|
||
| `ferro_ta.exceptions` | Stable |
|
||
| `ferro_ta.registry` | Stable |
|
||
| `ferro_ta.backtest` | Stable |
|
||
| `ferro_ta.pipeline` | Stable |
|
||
| `ferro_ta.config` | Stable |
|
||
| `ferro_ta.gpu` (optional) | Beta — API may evolve |
|
||
| `ferro_ta._utils` (private) | Not stable — do not import directly |
|
||
|
||
### v1.0 readiness checklist
|
||
|
||
- [x] All 155+ TA-Lib indicators implemented and tested
|
||
- [x] Type stubs (`.pyi`) for all public functions
|
||
- [x] Sphinx documentation for all modules
|
||
- [x] Streaming bar-by-bar API (9 classes)
|
||
- [x] Batch execution API
|
||
- [x] Extended indicators (10 beyond TA-Lib)
|
||
- [x] WASM bindings (9 indicators)
|
||
- [x] Pandas integration (transparent)
|
||
- [x] Polars integration (transparent)
|
||
- [x] Backtesting harness
|
||
- [x] Plugin registry
|
||
- [x] Error model and input validation
|
||
- [x] Release playbook (RELEASE.md)
|
||
- [x] Changelog (CHANGELOG.md)
|
||
- [x] Version consistency CI check
|
||
- [x] Fuzzing (cargo-fuzz, SMA + RSI)
|
||
- [x] Optional GPU backend (CuPy)
|
||
- [x] Indicator pipeline API
|
||
- [x] Configuration defaults API
|
||
- [x] Jupyter notebook examples
|
||
|
||
### Post-1.0 notes
|
||
|
||
With `1.0.0` released:
|
||
1. The package now uses the `Development Status :: 5 - Production/Stable` classifier.
|
||
2. `CHANGELOG.md` now contains the `[1.0.0]` release section.
|
||
3. This file now reflects the stable-series SemVer contract.
|
||
|
||
### Compatibility matrix
|
||
|
||
| Python | Platform | Status |
|
||
|---|---|---|
|
||
| 3.10–3.13 | Linux x86_64 (manylinux) | ✅ Supported |
|
||
| 3.10–3.13 | macOS x86_64 | ✅ Supported |
|
||
| 3.10–3.13 | macOS aarch64 (Apple Silicon) | ✅ Supported |
|
||
| 3.10–3.13 | Windows x86_64 | ✅ Supported |
|