# 发布一个版本

> **更新触发点：第 2 档（同提交同改）**——`../README.md` 把常青文档的更新触发点分成三档，
> 第 2 档的意思是「改到相关的东西时，在同一个提交里把这份文档改对」。三种事情触发它：
> 发布用的地址、工具或凭据位置变了；步骤增删或换序；某次发布踩到新坑并因此加了一步。
>
> **当前状态：1.0.1 已经发布。** Gitea 仓库 `iomgaa/PolyLoop` 已建、remote 已接，`main` 与
> annotated tag `v1.0.1` 都推上去了；registry 上有 `polyloop-1.0.1.tar.gz` 与
> `polyloop-1.0.1-py3-none-any.whl`，包页面渲染出了 README 正文，Release 也建好了。
> **唯一还欠着的是包页面上的 Link to a repository**，那一步只能在网页上点（第九步）。

PolyGateway 的 registry 上，版本号是断的：`0.1.0, 1.0.0, 1.0.1, 1.0.2, 1.0.3, 1.0.4, 1.0.5,
1.1.1, 1.1.2`——中间缺了 1.0.6 和 1.1.0。这两个版本，版本号改了、CHANGELOG 写了、代码合进
main 了，就是从来没有上传过。当年发现之后的补救只是把流程写进文档，没有人回头把包补传上去，
所以到今天那个缺口还在。

这个缺口现在正在伤人：dissect 的 requirements 钉着 `polygateway>=1.0.6,<1.1`，而这个区间在
registry 上一个文件都没有。下游装不到任何修复，而且**没有任何一处会报错**——本地测试全绿，
git 历史干干净净，只有真去 registry 上看的人才发现那里什么都没有。

所以发布这件事的判据不是「本地步骤都跑通了」，而是**下游视角能看见的产物**：registry 上有那个
版本的文件、包页面的正文不是空白、仓库的 Releases 页有对应条目、装下来解开之后新代码真的在
里面。`CLAUDE.md` §1.10 把「发布」定义成这一整串而不是版本号 bump，理由就是上面这段。

---

## 一次性准备

这些事只做一次。它们没做全的表现都是发布走到一半才卡住，而那时候 tag 可能已经打出去了。

### 为什么发到自建 Gitea，不发公网 PyPI

这是一个实验室内部共用的库，用它的是 dissect、GovDoc-SaaS 和 CHSAnalyzer，没有外部用户。
公网 PyPI 上占一个名字要跟着负维护责任——那个名字一旦发出去就收不回来，而且实验室还有另外
几个库要一起管，散在两个地方管不动。自建 registry 把这几个库收在同一个 owner 下面，权限和
清理都在自己手里。

包本身是**公开的、匿名可装**，这一点和「不上公网」不矛盾：不上公网是为了少一份对外承诺，
公开可装是为了让下游的 CI 不必配任何凭据就能装上——凭据只有上传的人需要。

### 建 Gitea 仓库并接上 remote

发布目标是实验室自建的 Gitea 实例 `https://gitea.iomgaa.online`。仓库这么建：

```
tea repos create --name PolyLoop --description "实验室共用的 Agent 执行内核"
git remote add origin git@gitea.iomgaa.online:iomgaa/PolyLoop.git
```

`origin` 已经存在的话（比如仓库是从别处克隆来的），`git remote add` 会报
`error: remote origin already exists`，这时候先 `git remote -v` 看一眼它指向哪里，确认要改就用
`git remote set-url origin <地址>`。

仓库和包是两件事：仓库放代码、tag 和 Releases，包放在同一个 Gitea 实例的 PyPI registry 上。
**这个 registry 是 owner 级的，不是仓库级的**——它挂在用户 `iomgaa` 名下，`iomgaa` 名下所有
项目的包都堆在同一个索引里。两个地址：

| 用途 | 地址 |
|---|---|
| 上传 | `https://gitea.iomgaa.online/api/packages/iomgaa/pypi` |
| 索引（下游装包、验证用） | `https://gitea.iomgaa.online/api/packages/iomgaa/pypi/simple/` |

owner 级的直接后果是：包传上去之后不会自动和任何仓库产生关联，要手动挂（第九步）。

### 三个工具：tea、build、twine

`tea` 是 Gitea 的官方命令行。**这台机器上 `tea 0.15.0` 已经装好，而且已经 `tea login` 过这个
实例**，所以下面要用到的那个凭据文件是现成的。换一台机器的话，先装 tea 并 `tea login`，
否则凭据那一节和第九步都无从下手。

`build` 和 `twine` 已经在 `pyproject.toml` 的 dev extra 里，所以装过开发环境就有：

```
make install
```

「extra」是 Python 打包里的可选依赖组，`pip install -e ".[dev]"` 装的就是 dev 这一组，
`make install` 跑的正是它。**把这两个放进 extra 是刻意的**：PolyGateway 那边它们不在任何
extra 里，于是它的发布流程必须多写一条「记得先装这两个」，而那种一年用几次的准备步骤迟早
有人漏，漏了的表现是发布走到第六步才报 `No module named build`。代价是每个协作者的环境
多两个包，换来发布这条路上少一个人工前提。

**上传工具是 `twine`，不是别的。** `uv publish` 这条路不走，因为本仓库的环境是 conda，
多引一个包管理器会让「现在装的到底是哪份依赖」多一个答案。`tea` 也传不了包：`tea 0.15.0`
根本没有 packages 子命令，它在整套流程里只用来建 Release。

### 命令的两种形状

`Makefile` 里每个 target 内部已经包好了 `PYTHONUNBUFFERED=1 conda run --live-stream -n
PolyLoop`，所以 `make ci`、`make test` 在裸 shell 里直接敲就对，**再套一层 conda run 是错的**。

而 `python -m build`、`twine`、`pip download` 这类直接调 Python 的命令没有这层包装，要自己
写全那个前缀。前缀的两段缺一不可：conda 和 Python 各缓冲一层输出，只拆一层的话长跑命令
全程无输出，直到进程结束才一次性吐出（`CLAUDE.md` §4）。

### 凭据：token 在哪、怎么传

凭据是一个 Gitea access token，它在 `~/.config/tea/config.yml` 的 `logins` 段里，字段名是
`token`——那是 `tea login` 时存下来的。**它不在 `~/.pypirc`**：那个文件里只有公网 PyPI 的段，
照着 `.pypirc` 找会一无所获。手上没有 token 的人在 Gitea 的用户设置里新签一个，勾上 package
的读写权限，上传要的就是这一项。

token 只经环境变量传给 twine，不写进命令行，也不写进任何文件：命令行会进 shell 历史，也会
出现在同一台机器上任何人的 `ps` 输出里，而**这台机器是和别人共用的**。具体的三个 export
在第七步，不在这里——`read -rs` 读进来的值只活在当前那个 shell 里，换一个终端窗口、
或者中间 `exit` 过一次，就得重设一遍。

### 让包元数据齐全，特别是 `readme`

`pyproject.toml` 的 `[project]` 里必须有 `readme = "README.md"`。缺了它，包能构建、能通过
`twine check`、能上传成功、能被 `pip download` 下下来，**而 registry 的包页面正文是一片空白**。
PolyGateway 的 1.1.2 就是这样发出去的：三步全绿，页面什么都没有。这是唯一一个三道机器检查
全绿还能出错的坑，所以第九步必须用眼睛看一次页面。

`twine check` 对这种情况只给警告，不给非零退出码，所以它拦不住。发布前直接看一眼：

```
grep -n '^readme' pyproject.toml
```

没有输出就是缺了，补上再走后面的步骤。

---

## 每次发布的九步

前两步（README 与 CHANGELOG）互相依赖，一起做：改 README 要用到版本号，而版本号由这一版
改了什么决定，那是 CHANGELOG 那一步的事。除此之外顺序是死的，每一步都压着后面某一步的
前提——理由写在各步自己那里。

`X.Y.Z` 代表这次要发的版本号，`vX.Y.Z` 是它对应的 tag。前三步在一个分支上做（例如
`release/vX.Y.Z`），第四步才合进 `main`。

### 1. 改 README

`README.md` 的「安装」一节里，安装命令带着版本约束（现在是 `polyloop==1.0.*` 这个形状，
`gateway` extra 那条命令里还有一份）。**发新版时这几行要跟着改**——那是 README 里唯一会随
版本失效的东西。

这一步排在最前面，是因为 `python -m build` 会把当时的 README 整个固化进 sdist 与 wheel 的元
数据里，registry 包页面显示的正文就是那一份。发布之后再改仓库里的 README，包页面纹丝不动——
要改只能重发一个版本。PolyGateway 的 1.1.1 就是带着一份过期 README 发出去的。

版本约束那一行漏改的后果是：下游照着 README 装，会被锁在旧版本上，而他不会怀疑一份刚发布
的文档。

### 2. 把 CHANGELOG 定版

`CHANGELOG.md` 里那个「未发布」段落改成这一版的标题，形状是 `## X.Y.Z（YYYY-MM-DD）`，
日期就是发布当天，例如 `## 1.0.1（2026-08-11）`。改完在它上面留一个空的「未发布」段落，
给下一版接着攒。

这一步排在改版本号之前，是因为**它才是决定版本号该是多少的地方**：这一版改了什么，决定了
它是 patch、minor 还是 major。倒过来做的话，版本号是先拍出来的，CHANGELOG 只是去凑它。

### 3. 两处版本号同步

版本号写在两处，必须一致：

- `pyproject.toml` 的 `project.version`
- `src/polyloop/__init__.py` 的 `__version__`

双写是刻意的：运行时读不到构建元数据（未安装的源码树里 `importlib.metadata` 查不到这个包），
而下游报 bug 时第一件事就是问版本号。代价就是两处会漂移，所以
`tests/unit/test_package.py` 有一条断言钉住它，PolyGateway 那边同一条测试逮住过两次漏改。
改完立刻跑一次：

```
make test
```

**在这一步就跑，而不是等第四步那次 `make ci`**：这时候改动还没合进 main，改起来不牵扯任何
别人的东西。漂移的后果不会当场出现——下游报 bug 时说的版本号和实际装的不是同一个，
而这种错查起来要绕很远。

**版本号定高了想往回改，要动三个文件**：两处版本号加 CHANGELOG。PolyGateway 有一次把 1.1.0
改回 1.0.4，就是这三处一起改的。**那次是在 1.0.4 还没发布之前**——发布前的版本号只是文件里
的三个字符串，随便改；一旦第七步传上去，那个版本号就永久占住了，只能往前发新的
（第七步那个 409）。

### 4. 合并进 main、push，并在 main 上重跑全套件

```
git checkout main
git merge --no-ff release/vX.Y.Z
git push origin main
```

`--no-ff` 让这次发布在历史上留下一个可辨认的合并点。前三步本来就在 main 上做的话，跳过
merge 直接 push。

**push 是外部可见动作，按 `CLAUDE.md` §2 要先得到批准。** 批准的对象是「发这个版本」这件事
整体，不是每一条 git 命令——批过之后第五步那次 tag push 不用再问一遍。

推完在 **main 上**跑一次完整检查：

```
make ci
```

在 main 上重跑而不是信任分支上那次结果，是因为要发布的是 main 这个 commit 的内容，而它是
合并的产物——分支上绿不代表合完还绿。

这条命令超过一分钟，按 `CLAUDE.md` §4 放进 tmux 跑，并且**末尾不许接管道**：`| tail` 会让退出
码变成管道最后一节的，于是失败的测试跑报成 exit 0，看起来一切正常。

### 5. 打 annotated tag 并 push

```
git tag -a vX.Y.Z -m "vX.Y.Z"
git push origin vX.Y.Z
```

**annotated，不是轻量 tag，挂在 main 上刚刚验过的那个 commit 上。** 这条写死是因为
PolyGateway 那边没写死：它的 tag 有的挂在 merge commit、有的挂在某个 feat commit，其中
`v1.0.0` 还是个轻量 tag。轻量 tag 只是一个指向 commit 的指针，没有作者、日期和消息，
`git describe` 默认也不认它，于是「这个版本是谁在什么时候发的」这个问题在那一版上没有答案。

tag 打在构建之前，是为了让 registry 上的那个包一定对应得上一个 git commit。反过来（先传包
后打 tag）的失败形态是漏打：PolyGateway 的 1.0.1 与 1.0.2 有 CHANGELOG、registry 上也有包，
但至今没有 tag，没人说得清那两个包是从哪个 commit 构建出来的。

tag 是 git 里的东西，Release 是 Gitea 里的东西，打了前者不会长出后者，所以还有第九步。

### 6. 构建，并 `twine check`

```
rm -rf dist/
PYTHONUNBUFFERED=1 conda run --live-stream -n PolyLoop python -m build
PYTHONUNBUFFERED=1 conda run --live-stream -n PolyLoop twine check dist/*
```

`python -m build` 在 `dist/` 下产出两个文件，两个都要传：

- **sdist**（`polyloop-X.Y.Z.tar.gz`，source distribution）是源码包，里面是构建这个版本所需的
  源文件加一份 `PKG-INFO` 元数据。装它的人本地跑一次构建。
- **wheel**（`polyloop-X.Y.Z-py3-none-any.whl`，二进制分发包）是装好即用的形态，pip 优先取它，
  因为不用在下游机器上跑构建。`py3-none-any` 表示它对 Python 3 通用、不挑平台。

一个包传两份，是为了让「pip 直接装」和「有人要从源码构建、或者在 pip 取不到 wheel 的环境里
装」两种情况都能满足。

先清 `dist/`，因为第七步是 `twine upload dist/*`：留着上一个版本的产物，那一批会被一起重传，
而 registry 会用 409 拒绝任何一个已经存在的版本号，于是整条上传命令失败。

`twine check` 验的是元数据能不能被 registry 渲染。它**只警告不拦**（`readme` 缺失就是警告的
一种），所以它绿不代表包页面正常，那件事要等第九步用眼睛确认。

### 7. 上传到 registry

三个环境变量先摆好。**每开一个新 shell 都要重设 `TWINE_PASSWORD`**——`read -rs` 的值只活在
当前这个 shell 里，换个窗口就没了，而它没设的时候 twine 会去交互式地问，或者直接报认证失败：

```
export TWINE_USERNAME=iomgaa
read -rs -p 'Gitea token: ' TWINE_PASSWORD && export TWINE_PASSWORD
export TWINE_REPOSITORY_URL=https://gitea.iomgaa.online/api/packages/iomgaa/pypi
```

token 从哪来、为什么必须走环境变量，见准备阶段那一节。然后传：

```
NO_PROXY=gitea.iomgaa.online PYTHONUNBUFFERED=1 conda run --live-stream -n PolyLoop \
    twine upload dist/*
```

`NO_PROXY` 不能省。这台机器设了 `http_proxy` / `https_proxy`，指向一个到不了外面的本地代理，
而 Gitea 在内网——不排除代理的话这一步会卡住或直接连接失败，且报出来的错和凭据错误长得很像。
所有访问 `gitea.iomgaa.online` 的命令都要带它，第八、第九步同样。

**同一个版本号重传会被 registry 用 409 拒绝，而且传上去的东西改不了。** 发现内容有问题的唯一
出路是 bump 一个新版本号重走一遍九步。PolyGateway 有一次是先在 Gitea 侧手工把包删掉才重传的，
那是在删自己刚传的东西且确认没有下游装过的前提下——一旦有人装过，删包就等于把别人的构建打断，
那时候只能往前发新版。

### 8. 验证已发布

**轻量的一条**，纯 GET，看某个版本在不在：

```
NO_PROXY=gitea.iomgaa.online curl -s \
    https://gitea.iomgaa.online/api/packages/iomgaa/pypi/simple/polyloop/
```

它返回一页链接，列出这个包在 registry 上的所有文件名。刚传的那个版本的 sdist 和 wheel 都要在
里面。这条命令不装任何东西、不写任何状态，随时可以重跑。

**然后走一遍下游真正会走的路**。`pip download` 默认只取 wheel，所以这条命令拿到的是 `.whl`：

```
cd "$(mktemp -d)"
NO_PROXY=gitea.iomgaa.online PYTHONUNBUFFERED=1 conda run --live-stream -n PolyLoop \
    pip download --no-deps \
    --index-url https://gitea.iomgaa.online/api/packages/iomgaa/pypi/simple/ \
    "polyloop==X.Y.Z"
unzip -l polyloop-X.Y.Z-py3-none-any.whl
unzip -p polyloop-X.Y.Z-py3-none-any.whl polyloop/__init__.py | grep __version__
```

`--no-deps` 是因为这里验的是 polyloop 这一个包能不能取到，不是它的依赖树装不装得起来。

**「下载成功」不算数，必须解开看里面的东西。** 通过的判据是三条：`unzip -l` 列出的文件里
十个模块的 `.py` 和 `polyloop/py.typed` 都在；`__version__` 是这一版而不是上一版；这次新增或
改动的公共名字 grep 得到（`unzip -p ... polyloop/<模块>.py | grep <名字>`）。理由是包和 git
之间没有任何机器约束——构建时工作区不干净、`dist/` 没清、传错了文件，都会让一个「下载成功」
的包里装着旧代码。

sdist 要单独取。它里面那份 `PKG-INFO` 的正文就是包页面要渲染的 README，可以在这里先看一眼
（1.0.1 那次是 6462 个字符，1.0.2 是 9566 个）：

```
NO_PROXY=gitea.iomgaa.online PYTHONUNBUFFERED=1 conda run --live-stream -n PolyLoop \
    pip download --no-deps --no-binary :all: --no-build-isolation \
    --index-url https://gitea.iomgaa.online/api/packages/iomgaa/pypi/simple/ \
    "polyloop==X.Y.Z"
tar -xzf polyloop-X.Y.Z.tar.gz -O polyloop-X.Y.Z/PKG-INFO | head -40
```

**`--no-build-isolation` 不能省，而漏了它的失败形态会指向错误的方向。** `--no-binary :all:`
让 pip 取 sdist 而不是 wheel，而 pip 拿到 sdist 之后会去构建它的元数据，构建要先装
`pyproject.toml` 里 `build-system.requires` 那个 setuptools——`--index-url` 已经把索引整个换成
了这个 registry，那儿只有 polyloop，没有 setuptools。报出来的是：

```
ERROR: Failed to build 'polyloop' when installing build dependencies for polyloop
```

这句话读起来像刚传上去的那个包坏了，而实际上包好好的，坏的是这条命令的索引配置。
`--no-build-isolation` 让 pip 用当前 conda 环境里已经装着的 setuptools（`dev` 那组的 `build`
带着它），不去索引找。

跳过构建隔离不影响这一步的判据：这里验的是 registry 上那份 sdist 的**内容**对不对，不是
「下游能不能从源码把它构建出来」。真要验后者，索引那一项得写成 `--extra-index-url`，让 PyPI
仍然在链上。

这一步单独占一个位置，而不是并进第七步说一句「传完了」，是因为 PolyGateway 那两个缺失版本
的形态就是「本地看起来全做完了」——只有一条真的去 registry 取一次的命令能区分开。

### 9. 建 Release，并以下游视角核对包页面

先把 CHANGELOG 里这一版那一段抽出来存成一个文件（例如 `/tmp/release-notes.md`），它就是
Release 的正文。然后：

```
NO_PROXY=gitea.iomgaa.online tea releases create --repo iomgaa/PolyLoop \
    --tag vX.Y.Z --title "vX.Y.Z" --note-file /tmp/release-notes.md
```

也可以在网页上建，内容一样。Release 挂在第五步那个 tag 上。

**只打 tag 不建 Release，Releases 页会长期为空。** PolyGateway 的 tag 里只有最后一个有对应的
Release，于是那个仓库的 Releases 页看起来像一个从没发布过的项目——而 Releases 页是不熟悉这个
项目的人第一个会去看的地方。

然后打开包页面，做两件事：

- **手动点 Link to a repository，把包挂到 `iomgaa/PolyLoop` 上。** 包不会自动挂——PyPI 元数据
  里没有仓库这个字段，而这个 registry 是 owner 级的，它没有办法猜出这个包属于哪个仓库。
  **这个实例的 link API 返 404，脚本化不了**，整个流程里只有这一件事必须用鼠标点。
- **看一眼正文不是空白**。空白说明 `readme` 那件事漏了，见准备阶段最后一节。

最后逐一打开这三样，全部对得上才算发完：registry 包页面（正文 + 仓库链接）、仓库的 Releases
页、第八步解出来的文件。前八步全绿而发布其实没成，正是开头 PolyGateway 那个缺口的形态——
**判据必须是外部可见的结果，不是本地跑通了几条命令。**

---

## 下游怎么装

装法的权威是 `README.md` 的「安装」一节，那里有当前该用的完整命令和版本约束。发布的人要
知道的是它为什么长那样，以及下游最容易在哪两处摔跤。

**索引地址必须由下游自己带。** polyloop 不在公网 PyPI 上，而 pip 默认只认公网 PyPI；这台
开发机上也没有任何全局 pip 配置兜底（`pip config list` 是空的，三个可能位置的 `pip.conf`
都不存在）。全局配置本来就不该指望：它是每台机器各自的状态，下游的开发机和 CI 容器多半
干脆没有，所以「自己带索引地址」是普遍成立的要求，不是这台机器的特殊情况。

**用 `--extra-index-url`，不是 `--index-url`。** 后者会把默认源整个换掉，于是除了 polyloop
之外的依赖都装不到。写进 `requirements.txt` 的话，`--extra-index-url` 那一行必须排在
`polyloop` 那一行之前——pip 是按顺序读这个文件的，写在后面等于对上面那行不生效。

**代理是本机特有的那一条。** `NO_PROXY=gitea.iomgaa.online` 只在设了指向内网代理的机器上
需要（这台开发机就是），别的机器不必带。带上也不会有副作用，所以 README 里直接写了它。

**版本约束一定要带上界。** 破坏性变更会发生在 major 上（`CLAUDE.md` §1.3），没有上界的
`polyloop` 一行会在某天自动装上一个签名已经变了的版本，而下游那边表现成一次莫名其妙的
`ImportError`。上界具体钉在哪一档以 README 那一节为准，发新版时跟着它改（第一步）。