# 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 或其他仓库；
- 工作区最终状态与本轮报告一致。