NautilusTrader 发布工程指南:三分支模型、稳定版发布流水线与 Release Notes 编写规范

原创2026-10-09 22:50:471,708 阅读
文章标签:金融科技后端数据分析

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 创建是幂等的,重跑会更新已存在的草稿(如果之前已创建)。

恢复步骤

维护者按以下步骤人工创建标签并重跑失败作业:

  1. 在失败运行页面记下本次运行的提交 SHA。本地检出该提交,确认它携带的版本号:

    ./scripts/package-version.sh
    

    package-version.sh 优先用 Python 的 tomllib 解析 python/pyproject.toml 的 project.version,无 Python 环境时回退到 grep/sed 提取,是整个流水线版本读取的唯一入口。

  2. 在运行的精确提交上创建签名注解标签,沿用现有标签消息约定并推送:

    git tag -s v<version> -m "Released version <version>" <run-commit-sha>
    git push origin v<version>
    
  3. 本地校验标签:签名必须有效,且 git rev-parse 'v<version>^{commit}' 必须等于本次运行的提交 SHA:

    git tag -v v<version>
    git rev-parse 'v<version>^{commit}'
    
  4. 在失败运行页面选择 “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.toml workspace 中已设置版本
  • [ ] 确保 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 上)

Release Notes 编写标准

本部分规定在 RELEASES.md 中撰写发布说明的标准。仓库当前 RELEASES.md 首部(NautilusTrader 2.0.0rc7)即按此规范组织,可作为实际范例。

小节顺序

按以下顺序使用小节,某个版本没有对应条目时省略该小节:

  1. Enhancements
  2. Breaking Changes
  3. Security
  4. Fixes
  5. Internal Improvements
  6. Documentation Updates
  7. 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。

登录后查看全文
nautilus_trader