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