docs: write down the release procedure that keeps getting skipped

Bumping the version is not releasing. 1.0.6 and 1.1.0 both got a version bump and a changelog entry but were never uploaded, so the registry sat at 1.0.5 and downstream could not install any of those fixes. The ordering matters in one non-obvious way: README has to be correct before the build, because sdist freezes whatever is there at that moment. That is exactly how 1.1.1 shipped with a stale README. The install pin is called out by name since it is the easiest line to forget and the most damaging to leave wrong. Also records where the Gitea token actually lives — tea's config, not .pypirc — after that misreading led to a wrong "no credentials" claim.
docs: correct the telemetry field count and document backpressure
2026-08-06 12:44:06 -04:00 · 2026-08-06 12:33:45 -04:00 · 2026-08-06 12:24:44 -04:00 · 2026-08-06 12:12:42 -04:00
3 changed files with 25 additions and 3 deletions
@@ -78,6 +78,27 @@ make ci        # 只读验证(check + test)
 ### 4.4 Git 工作流
 - 一切开发在 feature 分支,严禁直改 main;频繁语义化提交;提交**必须**调用 `commit` skill;大改动前先提交回滚点。

+### 4.4.1 发布流程(每步都是历史欠账换来的,不得跳步)
+
+> [!CRITICAL]
+> **发布 = 合并 + push + tag + 构建 + 上传 registry。只 bump 版本号不叫发布。**
+> 教训: 1.0.6 与 1.1.0 都完成了版本号 bump 与 CHANGELOG,却从未上传,registry 长期停在 1.0.5——下游 `pip install` 拿不到任何修复,且无人发现。
+
+按顺序执行,**构建之前**必须先改完所有文档:
+
+| # | 动作 | 要点 |
+|---|---|---|
+| 1 | **更新 README** | 打包会把当时的 README 固化进 sdist,**发布后再改就来不及了**(包里那份永远是旧的)。逐项核对: 安装命令的版本约束(`==1.1.*` 这类**极易漏改**,漏了下游就被锁在旧版)、能力表是否覆盖新行为、数字型断言是否仍成立(如遥测字段数,须用 `inspect.signature` 实测而非凭记忆) |
+| 2 | CHANGELOG 定版 | "未发布" → `## X.Y.Z(日期)` |
+| 3 | 版本号 | `pyproject.toml` + `src/polygateway/__init__.py` 两处必须一致 |
+| 4 | 合并 main + push | `--no-ff`;合并后在 main 上重跑 `make lint` 与全套件 |
+| 5 | **打 tag 并 push** | `git tag -a vX.Y.Z -m "..."` + `git push origin vX.Y.Z`。历史上多个版本漏打 |
+| 6 | 构建 | `rm -rf dist && python -m build && python -m twine check dist/*` |
+| 7 | **上传 registry** | 凭据在 `~/.config/tea/config.yml`(tea CLI 的 Gitea token,**不在** `~/.pypirc`);token 走 `TWINE_PASSWORD` 环境变量,不进命令行<br>`TWINE_USERNAME=iomgaa TWINE_PASSWORD=$TOKEN python -m twine upload --repository-url https://gitea.iomgaa.online/api/packages/iomgaa/pypi dist/*` |
+| 8 | **验证已发布** | `pip download --no-deps --index-url .../pypi/simple/ "polygateway==X.Y.Z"`,并解包确认新代码在内。**不验证不算发布完成** |
+
+Gitea 包 registry 是 **owner 级**(`/iomgaa/-/packages/`)不是仓库级;PyPI 元数据不含仓库字段,故不会自动挂到 `PolyGateway/packages`,需在包页面手动 Link to a repository。
+
 ### 4.5 配置管理
 - 工程配置走 `pydantic-settings` + `.env`(模板 `.env.example`,敏感项不提交);严禁硬编码默认值;缺失关键配置直接报错。
 - 多源命名约定 `{SCOPE}__{PROVIDER}__{N}__{FIELD}`;韧性参数键名沿用三项目习惯(`LLM_TIMEOUT` 等),降低迁移成本。
@@ -15,9 +15,10 @@
 | 错误分类重试 | 一切失败落入四分类(见下),由分类决定重试/换源/熔断;429 属 pushback 不消耗重试预算;退避含 jitter 且尊重 Retry-After |
 | 熔断 | 双通道(连续失败 + 失败率窗口,健康证据抑制误熔);半开单探针带租约(持有者死亡自动回收);epoch fencing 拒绝迟到写回;开路时长指数递增 |
 | 自适应并发 | AIMD:429 削减、成功缓升,防止打爆上游 |
+| 背压与判死 | 配额满可选等待或快速失败;等待期按双条件判死(本地非生产性等待与全局无进展**同时**超窗)。stall 窗口只计**非生产性**等待(429 退避/配额轮询/熔断冷却),与 `TIMEOUT_S` 无耦合 |
 | 响应缓存 | Redis/内存;key 含 model + messages 摘要 + namespace/租户 + salt,多模态 content 先摘要再 hash(防毒化);可 per-call 绕过(科研重采样) |
 | 流式看门狗 | TTFT / inter-token / 总超时三层活性;thinking token 刷活性不计结果;截断流(缺 `[DONE]`)判瞬时不入缓存 |
-| 遥测与成本 | 每次调用(含缓存命中与失败)必录 18 字段;SQLite / Postgres 后端;按价格表折算成本;多模态内容摘要落库不存原图 |
+| 遥测与成本 | 每次调用(含缓存命中与失败)必录 22 字段;SQLite / Postgres 后端;按价格表折算成本落库(注意 `LLMResponse.cost` 本身恒为 `None`,成本只进遥测);多模态内容摘要落库不存原图 |
 | 结构化输出 | json_repair 修复 / 原生 schema 双策略 + 校验失败有界带反馈重问 |
 | OCR | MonkeyOCR 双端点(文本转录 + 版面解析),bbox 数值防御下沉,逐源健康预检 `check_health()` |
 | Embedding | 分批、维度校验、与 chat 同一治理栈 |
@@ -30,7 +31,7 @@

 ```bash
 pip install --extra-index-url https://gitea.iomgaa.online/api/packages/iomgaa/pypi/simple/ \
-    "polygateway[redis,postgres,structured]==1.0.*"
+    "polygateway[redis,postgres,structured]==1.1.*"
 ```

 核心仅依赖 `httpx` + `pydantic`;按需选 extras:
@@ -245,7 +245,7 @@ class StructuredOutputStrategy(Protocol):

@runtime_checkable
 class TelemetryRecorder(Protocol):
-    """遥测后端;20 字段冻结(M1 设计 §4.4 + issue #3),唯一调用点是 TelemetryEmitter。
+    """遥测后端;22 字段冻结(M1 设计 §4.4 + issue #3/#4),唯一调用点是 TelemetryEmitter。

    新增参数不设默认值: 库外无第三方实现者(三项目迁移时删除了各自的同名
    Protocol),完整签名的成本为零,而少写一列会被 emitter 的降级吞成 warning。
Author	SHA1	Message	Date
iomgaa	c2e9f5396c	docs: write down the release procedure that keeps getting skipped Bumping the version is not releasing. 1.0.6 and 1.1.0 both got a version bump and a changelog entry but were never uploaded, so the registry sat at 1.0.5 and downstream could not install any of those fixes. The ordering matters in one non-obvious way: README has to be correct before the build, because sdist freezes whatever is there at that moment. That is exactly how 1.1.1 shipped with a stale README. The install pin is called out by name since it is the easiest line to forget and the most damaging to leave wrong. Also records where the Gitea token actually lives — tea's config, not .pypirc — after that misreading led to a wrong "no credentials" claim.	2026-08-06 12:44:06 -04:00
iomgaa	d2cb8770df	docs: correct the telemetry field count and document backpressure Three README drifts, none of them about issue #8 alone: - the telemetry row said 18 fields; record_llm_call takes 22 (verified by inspect.signature). ports.py claimed 20 in its own docstring, so both records of the same fact were stale. - LLMResponse.cost is hardcoded to None on the chat path (retry.py:519). Cost only ever reaches telemetry. The old doc site named this as a known trap, so the capability row now says it outright. - backpressure had no row at all, which is what issue #8 was about.	2026-08-06 12:33:45 -04:00
iomgaa	80bc94c42d	docs: point the install pin at 1.1.x The pin still said ==1.0.*, which caps downstream at 1.0.5 and hides every fix since. Now that 1.1.1 is actually in the registry the pin can move; it was missed when 1.1.0 was tagged.	2026-08-06 12:24:44 -04:00
iomgaa	bb69ecf0da	Merge branch 'feat/issue-8-stall-budget' stall 判定改为非生产性等待口径(issue #8)并发布 1.1.1。	2026-08-06 12:12:42 -04:00