NautilusTrader 发布工程指南:三分支模型、稳定版发布流水线与 Release Notes 编写规范
NautilusTrader 发布工程指南:三分支模型、稳定版发布流水线与 Release Notes 编写规范
导读
本文是 NautilusTrader 仓库(nautilus_trader,生产级 Rust 原生交易引擎)的版本发布运维手册。它系统讲解项目维护者如何通过 develop / nightly / master 三分支模型组织日常开发、预发布测试与稳定版发布,并详细拆解以 GitHub Release 为锚点的 build 工作流——从构建 wheel、安全审计、创建标签与草稿 Release,到发布 crates.io / PyPI / R2 制品,再到校验注册表与发布正式 Release 的完整链路。读完本文,你将掌握:如何按步骤完成一次稳定版发布、发布标签缺失时如何人工恢复、两个版本号的维护规则、crates.io Trusted Publishing 的配置方法,以及撰写高质量 Release Notes 的分节与措辞标准。文中所有结论均可在仓库的 build 工作流、发布脚本 与 发布检查清单 对应源码中验证。
概览:三分支发布模型
NautilusTrader 使用三分支模型,每个分支承担不同的发布职责:
| 分支 | 定位 | 自动发布行为 |
|---|---|---|
develop |
日常活跃开发 | 每次 push 发布开发版(dev)wheel 到 Cloudflare R2 |
nightly |
预发布测试 | 发布所有受支持的预发布 wheel 与 CLI 二进制 |
master |
稳定版 | 触发完整的发布流水线 |
将发布提交合并到 master 后,流水线会自动完成一系列动作:从 python/pyproject.toml 读取版本并打标签、创建草稿 GitHub Release、上传发布制品、向 crates.io 发布 Cargo crates、向 PyPI 发布 wheel 与 sdist、正式发布 GitHub Release、构建 Docker 镜像并触发文档重建。
在 build 工作流 的 on.push.branches 中可以看到这四个触发分支的配置(test-ci、test-pre-commit 用于 CI 自测,develop、nightly、master 为正式分支),且 develop 分支同时接受 pull_request 事件。工作流顶层声明了最小权限原则(contents: read、actions: read),并通过 plan 作业计算本次运行是否执行测试、是否发布 wheel 以及发布目标环境,供后续作业统一引用。
稳定版发布工作流
build 工作流将 GitHub Release 视为稳定版发布的锚点:先创建草稿 Release,把 wheel 与 sdist 制品上传到该草稿,然后才把这些包发布到软件包索引(packages.nautechsystems.io、PyPI、crates.io);只有当注册表校验与最终完整性制品全部完成之后,工作流才正式发布 GitHub Release。
flowchart TD
push["Push to master"]
wheels["Build wheel artifacts<br/>Linux x86/ARM, macOS, Windows"]
audits["Release gates<br/>Rust suite + cargo-deny + cargo-vet<br/>Cargo publish + docs/features preflights"]
security["security-audit<br/>Zizmor + supply chain"]
tag["tag-release<br/>Create tag and draft GitHub release"]
wheel_assets["publish-wheels-master<br/>Upload wheels to GitHub release and R2<br/>release env"]
build_sdist["build-sdist<br/>Build sdist workflow artifact"]
sdist_asset["upload-sdist-release<br/>Upload sdist to GitHub release"]
crates["publish-cargo-crates<br/>crates.io Trusted Publishing<br/>release env"]
wheel_pypi["publish-wheels-pypi<br/>Attest and publish wheels to PyPI<br/>release env"]
sdist_pypi["publish-sdist-pypi<br/>Attest and publish sdist to PyPI<br/>release env"]
integrity["publish-release-integrity<br/>Checksums and registry verification<br/>Attestation siblings and cleanup"]
publish_release["publish-github-release<br/>Publish draft release<br/>Verify release attestation"]
push --> wheels
push --> audits
push --> security
wheels --> tag
audits --> tag
security --> tag
tag --> build_sdist
build_sdist --> sdist_asset
tag --> sdist_asset
tag --> wheel_assets
wheels --> wheel_assets
sdist_asset --> wheel_assets
wheel_assets --> wheel_pypi
wheel_assets --> crates
wheel_pypi --> sdist_pypi
sdist_asset --> sdist_pypi
crates --> integrity
wheel_pypi --> integrity
sdist_pypi --> integrity
tag --> integrity
integrity --> publish_release
tag --> publish_release
流水线的关键闸门作业
对照 build 工作流 的作业定义,可以把上图映射到具体实现:
- 构建闸门:
build(Linux x86,Python 3.13/3.14)、build-linux-arm、build-macos、build-windows仅在nightly与master上构建非 x86 平台 wheel,使用 maturin 以--locked和 release profile 构建;rust-tests-linux-x86负责 Rust 全量测试(make cargo-test,启用capnp、hypersync、nautilus-serialization/sbe、nautilus-infrastructure/postgres等特性)。 - 发布闸门:
cargo-deny与cargo-vet仅在master上运行;release-cargo-publish-preflight调用publish-cargo-crates.sh --check与--dry-run验证发布计划;release-docs-features-preflight运行docsrs-check、check-features、check-all-targets,确保 docs.rs 与 feature 组合在发布前可用。 - 安全闸门:
security-audit复用独立工作流执行 Zizmor 与供应链检查,tag-release将其列为依赖,审计失败则禁止打标签。
编辑 build.yml 时必须保持的顺序规则
该流程的健壮性依赖一组严格的先后顺序约束,任何对 .github/workflows/build.yml 的修改都必须保持这些规则:
- 任何发布制品上传或软件包注册表发布之前,草稿 GitHub Release 必须已经存在。
tag-release必须依赖security-audit,确保安全审计失败后稳定版打标签流程无法继续。- wheel 与 sdist 制品必须先附加到 GitHub Release,然后才能开始软件包索引发布(
packages.nautechsystems.io、PyPI、crates.io)。 - PyPI 与 crates.io 的 Trusted Publishing 作业必须保持
environment: release与id-token: write,因为注册表依赖release环境。 - 非 OIDC 的完整性校验与制品上传作业应避免使用
environment: release,除非确实需要 release 环境的密钥或审批。 publish-release-integrity必须在 PyPI 与 crates.io 发布之后运行。它先生成发布清单,依据清单校验各注册表,只有校验通过后才附加最终完整性制品。publish-github-release必须是稳定版发布的最后一个作业。GitHub 官方建议先创建草稿 Release、附加全部制品、再发布草稿,最后才启用 Release 不可变性。一旦为仓库启用 Release 不可变性,已发布的 Release 制品与发布标签将无法更改,只有标题和发布说明仍然可编辑。该作业在发布前校验最终草稿制品集合,并在发布草稿后校验 GitHub 的 Release 签名证明(attestation)。
从实现上看,tag-release 作业(build.yml 第 1152 行起)使用 salsify/action-detect-and-tag-new-version 创建标签,随后通过 Verify release tag 校验标签指向的提交等于 GITHUB_SHA,再用 softprops/action-gh-release 以 draft: true 创建草稿,并将 RELEASES.md 中截取的首个版本段作为发布说明(body_path: RELEASE.md)。
恢复缺失的发布标签
Create git tag 步骤只有在本次运行的提交版本与上一提交(HEAD~1)版本不同、且标签尚不存在时,才创建 v<version>。因此,当一次运行的提交携带的版本与其父提交相同,标签永远不会被创建;而标签缺失时,无论失败作业被重跑多少次,Verify release tag 都会失败。这是重试发布的典型形态:版本号 bump 之后有多个提交落到 master,导致重试运行携带的版本与父提交相同。由于 tag-release 是草稿 Release 与所有下游发布作业的锚点,标签缺失期间运行无法继续。
先判断:重跑还是人工恢复
首先检查标签是否存在、本次运行的提交是否 bump 了版本:
- 标签缺失且本次提交 bump 了版本:重跑失败作业即可。一旦失败作业通过,
tag-release就会创建标签。 - 标签缺失且本次提交携带的版本与父提交相同:任何重跑都不会创建标签,必须走下面的人工打标签流程。
人工打标签恢复的原理
人工恢复之所以可行,是因为 tag-release 的其余机制保持不变:
- 人工推送标签后的重跑中,
Create git tag在相同规则下跳过创建。 Verify release tag要求v<version>能解析到本次运行的提交(GITHUB_SHA),因此在该提交上人工推送的标签恰好能通过校验。- 草稿 Release 创建是幂等的,重跑会更新已存在的草稿(如果之前已创建)。
恢复步骤
维护者按以下步骤人工创建标签并重跑失败作业:
-
在失败运行页面记下本次运行的提交 SHA。本地检出该提交,确认它携带的版本号:
./scripts/package-version.shpackage-version.sh 优先用 Python 的
tomllib解析python/pyproject.toml的project.version,无 Python 环境时回退到grep/sed提取,是整个流水线版本读取的唯一入口。 -
在运行的精确提交上创建签名注解标签,沿用现有标签消息约定并推送:
git tag -s v<version> -m "Released version <version>" <run-commit-sha> git push origin v<version> -
本地校验标签:签名必须有效,且
git rev-parse 'v<version>^{commit}'必须等于本次运行的提交 SHA:git tag -v v<version> git rev-parse 'v<version>^{commit}' -
在失败运行页面选择 “Re-run failed jobs”。
Verify release tag会因已推送的标签而通过,草稿 Release 创建与下游发布作业继续执行。
仅在发布提交与版本号都最终确定时才执行此操作。标签是永久的发布锚点,一旦启用 Release 不可变性,已发布的发布标签就无法更改。如果 v<version> 已存在但指向不同提交,不要移动或重新推送该标签,而应调查不一致的原因——这种情况下 Verify release tag 会按设计失败。
版本号管理
项目维护两个版本号:
| 文件 | 作用域 |
|---|---|
python/pyproject.toml |
Python 包 |
Cargo.toml(workspace) |
Rust crates |
两者独立 bump。Python 版本驱动 v<python-version> 发布标签。以 aN、bN、rcN 结尾的版本创建 GitHub 预发布(prerelease),正式版本创建普通 Release。当前仓库中,python/pyproject.toml 的版本为 2.0.0rc7(预发布形态),Cargo.toml 的 workspace 版本为 0.66.0。
判定逻辑由 release-version-policy.bash 实现:^<a href="https://link.gitcode.com/i/75d8da0f28938404d307befbf2bdf264" target="_blank">0-9]+(\.[0-9]+){2}$ 判定为 release,^[0-9]+(\.[0-9]+){2}(a|b|rc)[0-9]+$ 判定为 prerelease,其他格式直接报错。tag-release 作业读取该结果设置草稿 Release 的 prerelease 标记。此外 tag-release 还会强制校验 [RELEASES.md 第一行必须以 # NautilusTrader <version> 开头,与 Python 版本完全一致,否则发布无法继续。
crates.io 发布
build 工作流通过 publish-cargo-crates 作业发布 Cargo crates。该作业使用 crates.io Trusted Publishing(通过 GitHub Actions OIDC),因此不依赖持久的 cargo token。需要在 crates.io 上为每个 crate 配置:
| 字段 | 值 |
|---|---|
| Owner | nautechsystems |
| Repository | nautilus_trader |
| Workflow | build.yml |
| Environment | release |
配置完成后,为 crate 启用 Trusted Publishing Only。从未发布过的 crate 需要先进行一次人工初始发布,crates.io 才允许配置 trusted publisher。发布前的自动检查由 check-crates-io-trusted-publishing.sh 完成:它枚举所有可发布 workspace crates(publish == null 或显式包含 crates-io),逐个调用 crates.io API 校验 trustpub_only 字段必须为 true。
按依赖顺序逐个发布
CI 发布不使用 cargo publish --workspace。发布作业运行 scripts/ci/publish-cargo-crates.sh,该脚本:
- 基于
cargo metadata --no-deps输出,用 jq 计算可发布 crates 的拓扑排序,按依赖顺序一次发布一个(脚本输出带序号的可视化发布计划); - 跳过 crates.io 上已存在的版本(HTTP 404 判定为不存在、200 判定为已存在,其他状态码直接失败);
- 每次发布后轮询 crates.io API 与 sparse index,确认新版本在两个通道都可见后才发布其依赖方(
wait_for_version,默认超时 300 秒、轮询间隔默认 30 秒,均可通过环境变量调整); - 发布失败时按指数退避重试(默认最多 3 次,
CARGO_PUBLISH_ATTEMPTS可调,build.yml 中设为 5); - 上传前检查两类阻塞项:若可发布 crate 依赖某个本地
publish = false且 crates.io 上不存在的 crate,直接失败;可选(optional)本地依赖同样算作阻塞,因为发布一个解析到不存在 crate 的公开 feature 会让该 feature 不可用。
脚本支持的三种模式与关键环境变量如下:
# 校验发布计划(不发布)
bash scripts/ci/publish-cargo-crates.sh --check
# 干跑:校验计划 + 依赖消费者检查
bash scripts/ci/publish-cargo-crates.sh --dry-run
# 实际发布(需要 CARGO_REGISTRY_TOKEN,优先来自 Trusted Publishing)
bash scripts/ci/publish-cargo-crates.sh
关键可调环境变量:CARGO_PUBLISH_ATTEMPTS(默认 3)、CARGO_PUBLISH_DELAY_SECONDS(默认 30)、CARGO_PUBLISH_POLL_SECONDS、CARGO_PUBLISH_RETRY_DELAY_SECONDS、CARGO_PUBLISH_SUCCESS_DELAY_SECONDS、CARGO_PUBLISH_WAIT_TIMEOUT_SECONDS(默认 300)、CARGO_REGISTRY_API_URL(默认 https://crates.io/api/v1)、CARGO_SPARSE_INDEX_URL(默认 https://index.crates.io)。
发布后校验与人工发布例外
verify-published-registries.bash 在 publish-release-integrity 作业中执行发布后校验,对每个 crate 版本:
- 只有 crates.io 显示该版本由本仓库 trusted-publish 时,才将其记为
previously_published(校验trustpub_data.provider == "github"且repository匹配、sha指向本次运行提交则为current_release); - 用户(token)发布的 crate 版本仍然失败,除非
CRATES_IO_MANUAL_PUBLISH_EXCEPTIONS以crate@version形式逐一列出每个恢复条目,用于紧急 token 发布恢复; - 被接受的例外条目记录在
crates-manifest.json中,release_status为manual_token_publish;格式错误或未被使用的例外条目会使作业失败(脚本会校验crate@version正则并比对"已使用"集合); - 错误的 trusted-publishing 仓库身份、校验和或 sparse index 不匹配同样导致失败。
crates-manifest.json 还会作为最终完整性制品附加到 GitHub Release(publish-release-integrity 作业的 Upload crates manifest 步骤),并在 verify-github-release-assets.bash 中被要求必须存在且非空。
发布检查清单
发布前(在 develop 上)
- ] 定稿 [RELEASES.md:审查所有条目,删除空小节
- [ ] 确保 python/pyproject.toml 与
Cargo.tomlworkspace 中已设置版本 - [ ] 确保 CI 发布的每个 crate 都已配置 crates.io Trusted Publishing:
bash scripts/ci/check-crates-io-trusted-publishing.sh - [ ] 确保
develop上所有 CI 检查通过
发布中
- [ ] 将
develop合并进nightly,确认 nightly CI 通过 - [ ] 将
nightly合并进master - [ ] 确认
build工作流完整执行:- 为 Linux x86/ARM、macOS、Windows 构建 wheel
cargo-deny与cargo-vet通过security-audit通过其 Zizmor 与供应链检查- 打标签前发布文档/feature 与 Cargo 发布预检通过
- 创建标签与草稿 GitHub Release
- 在软件包注册表发布前,wheel 与 sdist 已附加到 GitHub Release
- Cargo crates 已发布到 crates.io,或因版本已存在而跳过
- wheel 与 sdist 已发布到 PyPI
- 在附加发布校验和、crates manifest 与签名证明伴随文件(attestation siblings)之前,注册表校验通过
- 在全部发布制品与完整性制品附加后,GitHub Release 正式发布
- 若运行因发布标签缺失而失败,参照恢复缺失的发布标签后重跑失败作业
- ] 确认
docker工作流完成(镜像已构建并推送;[docker.yml 在master/nightly分支触发) - [ ] 确认
build-docs工作流完成(触发文档重建)
发布后(在 develop 上)
- ] 更新 [RELEASES.md 中已发布版本的发布日期
- [ ] 在已完成版本下方添加水平分隔线
--- - ] 在 [RELEASES.md 顶部添加下一个版本模板(见下文模板)
- [ ] 将 python/pyproject.toml 版本 bump 到下一个发布号
- ] 同步 bump 教程与 how-to 中
Cargo.toml片段里的 crate 版本([docs/concepts/rust.md、docs/how_to/run_rust_backtest.md、docs/how_to/run_rust_live_trading.md)
Release Notes 编写标准
本部分规定在 RELEASES.md 中撰写发布说明的标准。仓库当前 RELEASES.md 首部(NautilusTrader 2.0.0rc7)即按此规范组织,可作为实际范例。
小节顺序
按以下顺序使用小节,某个版本没有对应条目时省略该小节:
- Enhancements
- Breaking Changes
- Security
- Fixes
- Internal Improvements
- Documentation Updates
- Deprecations
Enhancements(增强)
新特性与用户可见的改进。
格式:
- Added `subscribe_order_fills(...)` and `unsubscribe_order_fills(...)` for `Actor`
- Added Bybit conditional orders support
- Added support for `OrderBookDepth10` requests (#2955), thanks @faysou
准则:以 "Added" 开头;代码元素用反引号;具体说明加了什么,而不是怎么实现的。
Breaking Changes(破坏性变更)
可能破坏现有代码的变更。
格式:
- 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
准则:以 "Removed"、"Renamed" 或 "Changed" 开头;简要说明迁移路径。
Security(安全)
防止崩溃、未定义行为或数据损坏的安全加固与修复,包括从 Internal Improvements 提升而来的重要加固。
格式:
- 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
准则:包含溢出/下溢修复、内存安全改进、FFI 防护、数据完整性修复;聚焦用户影响——本来可能发生什么;排除常规依赖更新、轻微加固或仅测试的修复;该版本没有安全条目时整节省略。
Fixes(修复)
提升正确性但不构成安全问题的缺陷修复。
格式:
- Fixed reduce-only order panic when quantity exceeds position
- Fixed Binance order status parsing for external orders (#3006), thanks for reporting @bmlquant
准则:以 "Fixed" 开头。
Internal Improvements(内部改进)
实现细节与基础设施变更。
格式:
- 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
准则:使用 "Added"、"Implemented"、"Improved"、"Optimized"、"Upgraded"、"Refined"、"Standardized";依赖升级要带上版本号。
Documentation Updates(文档更新)
指南与示例的变更。
格式:
- Added rate limit tables with links to official docs
- Improved dark and light themes for readability
- Fixed broken links
Deprecations(弃用)
标记为将来移除的特性。
格式:
- Deprecated `some_config_option`; disable (`False`) to maintain consistent behavior. Will be removed in future version
准则:说明迁移路径并提供替代方案。
署名(Attribution)
- 为外部贡献者署名:
thanks @username或thanks for reporting @username。 - 社区贡献与复杂特性附带 issue/PR 编号:
(#1234)。
风格(Style)
- 使用句子式大小写(仅首词大写)。
- 不以句号结尾。
- 代码元素用反引号。
- 聚焦改了什么,而非怎么改的。
要具体:
Bad: Improved Binance adapter
Good: Improved Binance fill handling when instrument not cached
安全分级判定
以下情况归入 Security:
- 内存安全(威胁稳定性的溢出、下溢、除零)。
- 可能破坏状态的未定义行为或崩溃。
- 数据完整性(NaN/Infinity 传播、导致损坏的竞态)。
- 防止注入或利用的输入校验(SQL 注入、命令注入、路径遍历)。
- 构建加固(non-exec stack、FFI 防护)。
- 用户应该知道的显著加固。
否则归入 Fixes(逻辑错误与 panic)或 Internal Improvements(轻微加固)。注意:纯逻辑 panic 归入 Fixes,除非它威胁系统稳定性或数据损坏。
示例对照
Security(可能崩溃/损坏):
- Fixed divide-by-zero in margin calculations that could crash the engine
- Fixed integer overflow in model arithmetic that could crash the process
Fixes(错误但安全):
- Fixed Binance order status parsing for external orders
- Fixed position purge logic to prevent purging re-opened position
Enhancements(用户可见):
- Added Bybit conditional orders support
Internal(实现层面):
- Implemented Bybit ping/pong handling
Release Notes 模板
发布后把下面模板添加到 RELEASES.md 顶部,作为下一版本的工作区:
# NautilusTrader <VERSION> Beta
Released on TBD (UTC).
### Enhancements
### Breaking Changes
### Security
### Fixes
### Internal Improvements
### Documentation Updates
### Deprecations
---
小结:一次发布的关键要点
- 三分支各司其职:
develop产 dev wheel、nightly产预发布产物、master触发完整发布流水线,合并顺序必须是develop→nightly→master。 - Release 是锚点:草稿 Release 先于一切发布动作存在;wheel/sdist 先挂到 GitHub Release 再进软件包索引;
publish-release-integrity必须在 PyPI 与 crates.io 之后运行;publish-github-release是最后一个作业。 - 标签不可儿戏:标签是永久发布锚点;标签缺失时先判断提交是否 bump 版本,只有版本号最终确定才走人工签名打标签恢复,标签指向不一致时只排查、不移动。
- 版本号双轨独立:Python 版本驱动
v<version>标签,aN/bN/rcN结尾自动标记为预发布;Rust crates 版本在Cargo.toml独立维护。 - crates.io 走 Trusted Publishing:按依赖顺序逐个发布、跳过已存在版本、双通道确认可见;用户 token 发布仅能通过显式例外恢复并记录到
crates-manifest.json。 - Release Notes 有标准:固定七小节顺序、句子式大小写、动词开头、聚焦 what 而非 how,安全类条目按用户影响分级,杜绝"Improved Binance adapter"式空洞描述。
如需查看完整实现,可继续阅读 .github/workflows/build.yml、scripts/ci/publish-cargo-crates.sh、scripts/ci/verify-published-registries.bash 与 RELEASES.md。