Releases

This guide covers the release process and the standards for writing release notes.

Overview

NautilusTrader uses a three-branch model:

• develop: active development; publishes dev wheels to Cloudflare R2 on every push.
• nightly: pre-release testing; publishes alpha wheels and CLI binaries.
• master: stable releases; triggers the full release pipeline.

Pushing to master automatically tags the version from pyproject.toml, creates a GitHub release, publishes wheels and sdist to PyPI, builds Docker images, and triggers a docs rebuild.

Versioning

The project maintains two version numbers:

These are bumped independently. The Python version drives the release tag (v1.223.0).

Release checklist

Pre-release (on develop)

• Finalize RELEASES.md: review all items, remove empty sections
• Ensure versions are set in pyproject.toml and Cargo.toml workspace
• Ensure all CI checks pass on develop

Release

• Merge develop into nightly, verify nightly CI passes
• Merge nightly into master
• Verify the build workflow completes:
  • Wheels built for Linux x86/ARM, macOS, Windows
  • cargo-deny and cargo-vet pass
  • Tag created and GitHub release published
  • Wheels and sdist published to PyPI
• Verify the docker workflow completes (images built and pushed)
• Verify the build-docs workflow completes (docs rebuild triggered)

Post-release (on develop)

• Update the release date in RELEASES.md for the published version
• Add horizontal separator --- below the completed release
• Add the next version template at the top of RELEASES.md (see below)
• Bump pyproject.toml version to the next release number

Release notes

This section documents the standards for writing release notes in RELEASES.md.

Sections

Use the following sections in this order:

1. Enhancements
2. Breaking Changes
3. Security
4. Fixes
5. Internal Improvements
6. Documentation Updates
7. Deprecations

Omit sections that have no items for a given release.

Enhancements

New features and user-visible improvements.

Format:

- Added `subscribe_order_fills(...)` and `unsubscribe_order_fills(...)` for `Actor`
- Added BitMEX conditional orders support
- Added support for `OrderBookDepth10` requests (#2955), thanks @faysou

Guidelines:

• Start with "Added".
• Use backticks for code elements.
• Be specific about what was added, not how.

Breaking Changes

Changes that may break existing code.

Format:

- Removed `nautilus_trader.analysis.statistics` subpackage - must import from `nautilus_trader.analysis`
- Renamed `BinanceAccountType.USDT_FUTURE` to `USDT_FUTURES`
- Changed `start` parameter to required for `Actor` data request methods

Guidelines:

• Start with "Removed", "Renamed", or "Changed".
• Explain migration path briefly.

Security

Security hardening and fixes that prevent crashes, undefined behavior, or data corruption. Includes significant hardening improvements elevated from Internal Improvements.

Format:

- Fixed non-executable stack for Cython extensions to support hardened Linux systems
- Fixed divide-by-zero and overflow bugs in model crate that could cause crashes
- Fixed core arithmetic operations to reject NaN/Infinity values and improve overflow handling

Guidelines:

• Include overflow/underflow fixes, memory safety improvements, FFI guards, data integrity fixes.
• Focus on user impact: what could have happened.
• Exclude routine dependency updates, minor hardening, or test-only fixes.
• Omit this section entirely if there are no security items for the release.

Fixes

Bug fixes that improve correctness but don't qualify as security issues.

Format:

- Fixed reduce-only order panic when quantity exceeds position
- Fixed Binance order status parsing for external orders (#3006), thanks for reporting @bmlquant

Guidelines:

• Start with "Fixed".

Internal Improvements

Implementation details and infrastructure changes.

Format:

- Added ARM64 support to Docker builds
- Ported `PortfolioAnalyzer` to Rust
- Improved clock and timer thread safety
- Upgraded Rust (MSRV) to 1.90.0
- Upgraded `pyo3` crates to v0.26.0

Guidelines:

• Use "Added", "Implemented", "Improved", "Optimized", "Upgraded", "Refined", "Standardized".
• Include version numbers for dependency upgrades.

Documentation Updates

Changes to guides and examples.

Format:

- Added rate limit tables with links to official docs
- Improved dark and light themes for readability
- Fixed broken links

Deprecations

Features marked for removal.

Format:

- Deprecated `convert_quote_qty_to_base`; disable (`False`) to maintain consistent behaviour. Will be removed in future version

Guidelines:

• Explain migration path and provide alternatives.

Attribution

• Credit external contributors: thanks @username or thanks for reporting @username.
• Include issue/PR numbers for community contributions and complex features: (#1234).

Style

• Use sentence case (capitalize first word only).
• Do not end with periods.
• Use backticks for code elements.
• Focus on what changed, not how.

Be specific:

❌ Improved Binance adapter
✅ Improved Binance fill handling when instrument not cached

Security classification

Include in Security if the change addresses:

• Memory safety (overflow, underflow, divide-by-zero that threatens stability).
• Undefined behavior or crashes that could corrupt state.
• Data integrity (NaN/Infinity propagation, race conditions leading to corruption).
• Input validation preventing injection or exploitation (SQL injection, command injection, path traversal).
• Build hardening (non-exec stack, FFI guards).
• Significant hardening that users should know about.

Otherwise use Fixes (for logic bugs and panics) or Internal Improvements (for minor hardening).

Note: Plain logic panics belong in Fixes unless they threaten system stability or data corruption.

Examples

Security (could cause crashes/corruption):

- Fixed divide-by-zero in margin calculations that could crash the engine
- Fixed non-executable stack for Cython extensions to support hardened systems

Fixes (incorrect but safe):

- Fixed Binance order status parsing for external orders
- Fixed position purge logic to prevent purging re-opened position

Enhancements (user-facing):

- Added BitMEX conditional orders support

Internal (implementation):

- Implemented BitMEX ping/pong handling

Release notes template

# NautilusTrader <VERSION> Beta

Released on TBD (UTC).

### Enhancements

### Breaking Changes

### Security

### Fixes

### Internal Improvements

### Documentation Updates

### Deprecations

---