0–5 分钟：release inventory
阅读 pyproject、version source、build backend、package data rules、entry points、README、license 和 current release docs。
成功标准当前 release path 和 metadata 可见。
Python 发布清单 · 更新 2026-06-27
Python Packaging Publishing Checklist：pyproject.toml、Build Backends、Wheels、sdists、TestPyPI、Twine、uv 与 Release Rollback
面向 Python libraries 和 CLIs 的实用 release checklist：避免 uv 迁移、build metadata、wheel/sdist publishing、changelog、credentials 和 rollback 在发布时出问题。
Python toolchain migration 只有在 publishing 仍然可用时才算完成。一个项目本地用 uv 跑得很好，release 时仍可能因为 metadata、build backends、package data、wheels、sdists、credentials、TestPyPI、dependency constraints 或 changelog rules 没测而失败。
这份 checklist 是 Python Toolchain Migration Checklist 之后的 release-specific layer。uv 可以管理 project/build workflows，mise 可以 pin uv 和 release tools，但 publishing 需要自己的闸门：package metadata、build backend behavior、wheel/sdist inspection、TestPyPI dry run、token handling、provenance notes、rollback plan 和 post-release monitoring。
RepoDaily 判断
不要因为本地 uv sync 能跑，就替换 Python 项目的 release path。可发布的迁移必须证明 clean build artifacts、正确 metadata、可复现 wheels/sdists、安全 credentials、TestPyPI 或 dry-run validation、changelog/version alignment，以及 rollback 或 yanked-release plan。
快速矩阵
| 发布区域 | 检查什么 | 通过信号 | 停止信号 |
|---|---|---|---|
| Project metadata | name、version、description、license、authors、classifiers、URLs、Python requires | Metadata 渲染正确并匹配 README/changelog | 包名错误、license 过期、Python range 不支持 |
| Build backend | setuptools、hatchling、flit、poetry-core、maturin 或 uv build path | Clean isolated build 产出预期 artifacts | Build 依赖 local files、hidden env 或 old Poetry-only behavior |
| Wheel artifact | Wheel filename、tags、imports、package data、console scripts | Fresh venv install 后 import 和 CLI 可用 | 缺文件、tags 错、import fail、entry points broken |
| sdist artifact | Source contents、pyproject、tests/docs policy、generated files | sdist 可 isolation rebuild wheel | sdist 漏必要 package data 或包含 secrets |
| Dependencies | Runtime deps、optional extras、upper/lower bounds、environment markers | 支持的 Python versions/platforms 上 install 成功 | Internal deps 未 pin、extras broken、markers 不兼容 |
| Credentials | PyPI/TestPyPI token、secret storage、CI environment、maintainer access | Token scoped 且存于 CI/secret manager | Token 出现在 shell history、repo、logs 或 chat |
| Dry run | TestPyPI 或 internal index publish/install cycle | 从 test artifact install 成功 | 只测试了 local build |
| Rollback | Yank/delete policy、version bump rule、hotfix owner、incident notes | 团队知道何时 yank、patch 或 publish fix | 没有 bad release plan |
Publishing 准备度评分卡
在修改官方 publishing instructions 前，先给 release path 打分。
| 准备区域 | 0 分 | 1 分 | 2 分 | Reviewer 问题 |
|---|---|---|---|---|
| Metadata | 不完整或过期 | 大体正确 | 已 review 且匹配 docs | PyPI 会展示正确叙事吗？ |
| Artifacts | 不检查 artifacts | 只检查 wheel | Wheel 和 sdist 都已 inspect/install | Clean environment 能用这个 package 吗？ |
| CI release path | 本地 laptop 手动 release | 部分 CI automation | 有 owned CI release job 和 scoped secrets | 谁能 publish，如何 audit？ |
| Dependency policy | Bounds 未知 | 有一些 version rules | Bounds/extras/markers 已测试 | 支持哪些 versions 和 platforms？ |
| Dry run | 无 | 只 local build | TestPyPI 或 internal index install 已测试 | 我们测试了 published artifact 吗？ |
| Rollback | 无计划 | 非正式 owner | Yank/patch/notify playbook 已记录 | Bad release 后怎么办？ |
30 分钟 Python Publishing Smoke Test
在把 package release path 迁移到 uv 或 CI automation 前使用。
5–12 分钟：clean build
在 clean environment 里 build wheel/sdist，并列出 artifact names 和 contents。
成功标准两个 artifacts 都存在且 contents 看起来符合预期。
12–18 分钟：install smoke test
创建 fresh environment，从 wheel 或 sdist install，import package，并跑 CLI/help 或 minimal function tests。
成功标准Installed artifact 不依赖 source checkout assumptions 也能工作。
18–24 分钟：publish dry run
验证 upload credentials，并尽可能通过 TestPyPI 或 staging publish/install。
成功标准Published artifact 可以从 index install。
24–30 分钟：release decision
决定 migrate、keep old path、patch metadata、test longer，或分配 release owner 和 rollback plan。
成功标准下一步 release 有 owner、evidence 和 rollback path。
Publishing 决策流程
- 先分类 package：library、CLI、plugin、internal package、native-extension package、data package 或 monorepo subpackage。
- Review `pyproject.toml`、build backend、version source、package data、entry points、dependency groups、optional extras、Python version support、license 和 README rendering。
- 在 clean environment 里 build wheel 和 sdist，然后 inspect contents，再发布任何东西。
- 把 built wheel 和 sdist 安装到 fresh environment，并运行 import、CLI 和 minimal smoke tests。
- 可能时发布到 TestPyPI 或 internal dry-run index，再从该 index install 验证真实 published artifact。
- 最后才更新 release docs 或 CI 使用 uv/mise-backed publishing；在一次成功 release 或 owner sign-off 前保留 old path。
场景表
| 场景 | Release 模式 | 额外护栏 |
|---|---|---|
| Pure Python library | Build wheel/sdist，inspect metadata，install both artifacts，run import smoke test | 检查 Python version range 和 dependency markers |
| Python CLI tool | 验证 console script entry points 和 fresh venv command execution | 从 installed wheel 运行 help/version command |
| 包含 data files 的 package | 检查 wheel/sdist contents 里的 package data 和 exclusions | 确认没有 private data 或 generated junk 被包含 |
| Native extension 或 Rust-backed package | 构建 platform-specific artifacts 并测试 tags | 使用 platform matrix 或 release tooling owner review |
| Internal package index | 先发布到 internal dry-run 或 staging index | 验证 credentials、index URL 和 dependency resolution |
| Poetry-to-uv migration | 保留 existing release path，直到 build/publish parity 被证明 | 切换前比较 metadata 和 artifact contents |
| Emergency hotfix | Patch version、minimal diff、clean artifact、install smoke test、publish、monitor | 不要复用 broken version number |
Publishing 风险清单
Local success, published failure
Package 可能因为 source paths 在磁盘上而本地 import 成功。必须测试 wheel 和 sdist 安装后的 artifact。
Metadata drift
Package metadata、README、changelog、license 和 Python support 可能互相矛盾，需要一起 review。
sdist surprise
只测 wheel 会隐藏 missing source files。好的 sdist 应能在 isolation 中 rebuild wheel。
Credential leakage
Publishing tokens 应 scoped 并存放在 CI 或 secret manager，绝不 commit 或贴进聊天。
Version-number trap
版本一旦发布，复用通常不安全。发布前定义 patch/yank behavior。
Dependency overconfidence
过松或错误的 dependency bounds 会在 downstream install 后破坏用户，而不是在本地测试时暴露。
Publishing 实施模式
Build in clean env
使用 clean environment 或 CI job，避免 hidden local files 和 editable installs 掩盖 packaging problems。
Inspect before publish
上传到任何 index 前，先列出 wheel/sdist contents 并检查 metadata。
Install the artifact
对 built/published artifact 运行 smoke tests，而不是对 source checkout。
TestPyPI or staging index
可行时使用 dry-run index 验证 upload 和 install behavior。
mise pins release tools
需要 release 可复现时，用 mise pin uv、Python、twine 或其他 release tools。
Release PR checklist
每个 release PR 记录 version、changelog、artifacts tested、credentials path、publisher 和 rollback owner。
常见问题
给 toolchain migration 后发布 Python packages 的维护者提供简短答案。
uv 会替代 Twine 或 PyPI release policy 吗？
不会。uv 可以支持 build 和 project workflows，但 release policy 仍需要 artifact inspection、credentials、dry run、changelog 和 rollback rules。
Wheel 和 sdist 都要测吗？
对 published packages 来说应该都测。Wheel 和 sdist 的失败模式不同，下游用户可能依赖任一路径。
TestPyPI 什么时候有用？
在真正 public release 前，用它验证 upload/install behavior 和 metadata rendering。
坏的 PyPI release 能覆盖吗？
不要依赖覆盖。应使用新版本，必要时 yank，发布修复，并记录 incident。
相关雷达
相关 RepoDaily 解读
来源
Feedback
这页是否帮助你做出决定？
匿名反馈只用于判断内容是否真正有用。