0015：将 Gitea 作为正式发布渠道

状态

已于 2026-09-02 经用户明确批准。本文自批准起冻结；后续若改变正式发布渠道、版本身份或迁移边界，应新增 design，不得回写本文。

supersedes: 0010（范围有限）：本文只替代 0010 中“正式版本只通过 GitHub tag 和 GitHub Release 交付”的渠道决定。0010 的版本身份、tag 不可移动、wheel 验收、SHA-256、分步确认和调用方责任继续有效。

1. 问题与当前事实

仓库的 origin 已改为 Gitea，main 已由用户推送到：

ssh://git@gitea.iomgaa.online:222/iomgaa/mdpolish.git

2026-09-02 的只读检查得到：

Gitea 仓库公开可读，默认分支是 main；
Gitea main 指向提交 6c0dd5974b4c1e1df481b9288e60b3829ac99f31；
Gitea 还没有 tag 和 Release；
本地已有 annotated tag v0.7.0，解析后也指向同一提交；
pyproject.toml 和根 README 的当前包版本都是 0.7.0；
根 README 仍把 GitHub 写成唯一正式发布渠道。

如果直接在 Gitea 发布而不记录渠道变化，当前事实会与 README 和已批准设计冲突。如果因为 Gitea 上尚无 Release 就重新使用 v0.1.0，会造成版本倒退；如果直接使用 v1.0.0，则会让 tag 与包内 0.7.0 版本不一致，并暗示尚未批准的稳定性承诺。

2. 目标与非目标

2.1 目标

将 Gitea 确定为后续正式源码和 Release 交付渠道；
在 Gitea 上发布已有版本 v0.7.0，保持 Git tag、包版本和 wheel 版本一致；
复用已经指向当前提交的本地 annotated tag，不创建同名的新 tag；
只上传能够证明与既有验收产物一致的 wheel，并公开 SHA-256；
更新根 README 中的发布渠道、安装地址和当前 Release 链接；
保留 GitHub 上既有 tag 和 Release，不删除、不改写历史。

2.2 非目标

不把版本重置为 v0.1.0，也不提前提升为 v1.0.0；
不改变清洗语义、公共 API、依赖、Python 支持范围或 wheel 内容；
不移动或重建本地 v0.7.0 tag；
不向 Gitea 推送其他历史 tag；
不删除或修改 GitHub 仓库、tag、Release 和附件；
不发布到 PyPI、其他包索引或其他制品仓库；
不读取真实材料，不修改其他仓库。

3. 方案比较

方案	优点	代价与问题	选择
Gitea 成为正式渠道，并迁移已有 `v0.7.0`	版本身份连续；与当前远程和包元数据一致	需要更新 README，并验证迁移附件	采用
Gitea 与 GitHub 长期同时作为正式渠道	任一站点不可用时仍可下载	两处 Release、说明和附件容易漂移	否决
在 Gitea 从 `v0.1.0` 重新编号	看起来像新仓库的第一版	同一项目版本倒退，包管理器和问题报告会混乱	否决
直接创建 `v1.0.0`	版本号醒目	tag、包元数据和稳定性承诺都不匹配	否决

4. 决定

Gitea 成为新的正式发布渠道。GitHub 上的现有内容只作为历史发布保留；本文不授权修改或删除它们。后续若恢复双渠道、回到 GitHub 或迁移到其他站点，需要新的 design。

Gitea 的第一份 Release 使用现有版本身份：

项目	值
tag	`v0.7.0`
tag 目标	`6c0dd5974b4c1e1df481b9288e60b3829ac99f31`
Release 标题	`mdpolish v0.7.0`
prerelease	否
draft	创建时可以先保存为草稿；附件和说明复核后再发布
wheel	`mdpolish-0.7.0-py3-none-any.whl`
wheel SHA-256	`b81a9a07fa0479854cd21d5a65f0f485cadf2031b5d731c3658ca10a1d72dc09`

Gitea Release 应说明这是 v0.7.0 的正式 Gitea 交付，不把“首次出现在 Gitea”描述成项目的首个版本。Release 附件至少包含已验收 wheel，并在 Release 正文或单独的 SHA256SUMS 附件中给出完整 SHA-256。

5. wheel 与 tag 一致性

优先取得既有 v0.7.0 Release 的同一 wheel，并在上传前计算 SHA-256。只有哈希与第 4 节完全一致时才可上传。

如果无法取得该文件，或哈希不一致，必须停止发布。重新构建 wheel 不自动等于原验收产物；如需重建，应从 v0.7.0 的准确提交构建，并重新执行根 README 中的 Python 检查、双 Python 版本 wheel 消费验证、附件内容检查和 SHA-256 记录。不得只因文件名相同就上传。

推送前必须再次证明本地 v0.7.0^{} 与 Gitea main 都是第 4 节提交。只推送这个准确 tag，不使用 --tags，避免把未经本轮确认的历史 tag 一并发布。

6. README 更新

根 README 是当前阶段与能力的唯一权威。实施本文时应：

把当前 Release 链接改为 Gitea v0.7.0；
把 Git direct reference 改为带 SSH 端口的 Gitea URL；
把 Release wheel 下载链接改为 Gitea 附件地址；
把“只通过 GitHub”改为“只通过 Gitea”；
保留私有仓库凭据由调用方管理、不发布到 PyPI 等边界；
不改写已实际完成的验证结果、wheel 大小和 SHA-256。

README 更新提交会晚于已经冻结的 v0.7.0 tag；它只修正默认分支上的当前渠道说明，不移动 tag，也不冒充 v0.7.0 源码提交的一部分。

7. 实施顺序与确认门

本文批准后按以下顺序实施：

将本文状态改为已批准并冻结；
更新根 README 的发布渠道与链接；
取得并校验既有 wheel，准备 Release 说明和 SHA-256；
执行文档镜像、Git diff、工作区状态，以及与实际修改相称的检查；
向用户展示最终 diff、验证结果、tag 目标和待上传附件；
获得用户对提交和推送文档改动的明确授权后，提交并推送 main；
获得用户对远端发布动作的明确授权后，只推送 v0.7.0 tag；
在 Gitea 创建草稿 Release，上传已校验附件并复核；
获得用户对公开发布的明确授权后，将草稿转为正式 Release；
只读复核 Release 的 tag、提交、附件下载、SHA-256 和公开页面。

早先关于“发布 v0.7.0”的方向确认不替代第 5、6、7、9 步在看到实际材料后的分步确认。任一步发现 tag 目标、包版本、附件哈希、权限或页面内容不一致，都停止发布，不移动 tag、不用近似附件继续。

8. 验收条件

根 README 与 Gitea 当前发布事实一致；
AGENTS.md 与 CLAUDE.md 除首行外仍完全一致；
Gitea v0.7.0^{} 指向 6c0dd5974b4c1e1df481b9288e60b3829ac99f31；
Gitea Release 绑定 v0.7.0，不是 draft 或 prerelease；
下载后的 wheel 文件名、包版本和 SHA-256 均与第 4 节一致；
没有推送其他 tag，没有修改 GitHub 或其他仓库；
工作区最终状态与本轮报告一致。

6.7 KiB Raw Blame History Unescape Escape