ferro-ta/VERSIONING.md

Versioning & Release Policy

ferro-ta uses Semantic Versioning 2.0.0.

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 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. 0.2.0).
2. Update CHANGELOG.md: move the [Unreleased] block to a new dated section [0.2.0] — YYYY-MM-DD and open a fresh [Unreleased] block.
3. Commit the version bump and changelog update with message chore: release v0.2.0.
4. Create a tag: git tag v0.2.0 && git push origin v0.2.0.
5. Create a GitHub Release for tag v0.2.0 — 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 (v1.0 preparation)

The following modules are considered stable API as of the v0.1.x series 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

• All 155+ TA-Lib indicators implemented and tested
• Type stubs (.pyi) for all public functions
• Sphinx documentation for all modules
• Streaming bar-by-bar API (9 classes)
• Batch execution API
• Extended indicators (10 beyond TA-Lib)
• WASM bindings (9 indicators)
• Pandas integration (transparent)
• Polars integration (transparent)
• Backtesting harness
• Plugin registry
• Error model and input validation
• Release playbook (RELEASE.md)
• Changelog (CHANGELOG.md)
• Version consistency CI check
• Fuzzing (cargo-fuzz, SMA + RSI)
• Optional GPU backend (CuPy)
• Indicator pipeline API
• Configuration defaults API
• Jupyter notebook examples

Path to v1.0

When the v1.0 release is cut:

1. Remove any Beta classifiers from pyproject.toml.
2. Update CHANGELOG.md with the [1.0.0] release section.
3. Update this file to reflect stable status.
4. Consider adding Stable :: Stable PyPI classifier.

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