docs: 将正式发布渠道迁移至 Gitea

2026-09-02 18:43:03 +08:00
parent 6c0dd5974b
commit a6c56fba09
2 changed files with 144 additions and 10 deletions
@@ -0,0 +1,133 @@
+# 0015：将 Gitea 作为正式发布渠道
+
+## 状态
+
+已于 2026-09-02 经用户明确批准。本文自批准起冻结；后续若改变正式发布渠道、版本身份或迁移边界，
+应新增 design，不得回写本文。
+
+`supersedes: 0010`（范围有限）：本文只替代 `0010` 中“正式版本只通过 GitHub tag 和 GitHub Release
+交付”的渠道决定。`0010` 的版本身份、tag 不可移动、wheel 验收、SHA-256、分步确认和调用方责任继续有效。
+
+## 1. 问题与当前事实
+
+仓库的 `origin` 已改为 Gitea，`main` 已由用户推送到：
+
+```text
+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. 实施顺序与确认门
+
+本文批准后按以下顺序实施：
+
+1. 将本文状态改为已批准并冻结；
+2. 更新根 README 的发布渠道与链接；
+3. 取得并校验既有 wheel，准备 Release 说明和 SHA-256；
+4. 执行文档镜像、Git diff、工作区状态，以及与实际修改相称的检查；
+5. 向用户展示最终 diff、验证结果、tag 目标和待上传附件；
+6. 获得用户对提交和推送文档改动的明确授权后，提交并推送 `main`；
+7. 获得用户对远端发布动作的明确授权后，只推送 `v0.7.0` tag；
+8. 在 Gitea 创建草稿 Release，上传已校验附件并复核；
+9. 获得用户对公开发布的明确授权后，将草稿转为正式 Release；
+10. 只读复核 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 或其他仓库；
+- 工作区最终状态与本轮报告一致。