From a6c56fba092c5cf412886f2170966a130037b9ca Mon Sep 17 00:00:00 2001
From: Bepr4 <63661977@qq.com>
Date: Wed, 2 Sep 2026 18:43:03 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=B0=86=E6=AD=A3=E5=BC=8F=E5=8F=91?=
=?UTF-8?q?=E5=B8=83=E6=B8=A0=E9=81=93=E8=BF=81=E7=A7=BB=E8=87=B3=20Gitea?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
README.md | 21 +--
.../design/0015-gitea-release-channel.md | 133 ++++++++++++++++++
2 files changed, 144 insertions(+), 10 deletions(-)
create mode 100644 research-wiki/design/0015-gitea-release-channel.md
diff --git a/README.md b/README.md
index fa0a470..1939c03 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,7 @@
`mdpolish` 是实验室共用的、项目无关的 Python Markdown 修改库。它提供函数式 `Modifier`、精确文本编辑执行器、
有序 `Pipeline`、正则修改器工厂，以及少量可以用合成样例完整说明的通用修改器。
-当前发布版本是 [`v0.7.0`](https://github.com/Bepr4/mdpolish/releases/tag/v0.7.0)。清洗核心只处理内存中的 Markdown
+当前发布版本是 [`v0.7.0`](https://gitea.iomgaa.online/iomgaa/mdpolish/releases/tag/v0.7.0)。清洗核心只处理内存中的 Markdown
字符串，不读取或写入文件，不提供默认流水线，也不包含任何项目的规则集合、数据清单或实验脚本。安装包另外提供一个
必须显式启动的本地只读评审器，用来展示项目已经保存的正式 `full` review JSON；它不替项目运行清洗或管理产物。
@@ -35,22 +35,22 @@
## 安装
-正式版本只通过 GitHub tag 和 GitHub Release 交付，不发布到 PyPI 或其他 Python 包索引。使用项目可以固定
+正式版本只通过 Gitea tag 和 Gitea Release 交付，不发布到 PyPI 或其他 Python 包索引。使用项目可以固定
不可移动的 tag：
```bash
-python -m pip install 'mdpolish @ git+https://github.com/Bepr4/mdpolish.git@v0.7.0'
-python -m pip install 'mdpolish[lexical] @ git+https://github.com/Bepr4/mdpolish.git@v0.7.0'
-python -m pip install 'mdpolish[frequency] @ git+https://github.com/Bepr4/mdpolish.git@v0.7.0'
+python -m pip install 'mdpolish @ git+ssh://git@gitea.iomgaa.online:222/iomgaa/mdpolish.git@v0.7.0'
+python -m pip install 'mdpolish[lexical] @ git+ssh://git@gitea.iomgaa.online:222/iomgaa/mdpolish.git@v0.7.0'
+python -m pip install 'mdpolish[frequency] @ git+ssh://git@gitea.iomgaa.online:222/iomgaa/mdpolish.git@v0.7.0'
```
-也可以安装同一 GitHub Release 附带的 wheel：
+也可以安装同一 Gitea Release 附带的 wheel：
```bash
-python -m pip install 'mdpolish[lexical] @ https://github.com/Bepr4/mdpolish/releases/download/v0.7.0/mdpolish-0.7.0-py3-none-any.whl'
+python -m pip install 'mdpolish[lexical] @ https://gitea.iomgaa.online/iomgaa/mdpolish/releases/download/v0.7.0/mdpolish-0.7.0-py3-none-any.whl'
```
-Release 页面同时提供 wheel 的 SHA-256 校验值。仓库或 Release 如果是私有的，调用方需要自行配置 GitHub 访问权限；
+Release 页面同时提供 wheel 的 SHA-256 校验值。仓库或 Release 如果是私有的，调用方需要自行配置 Gitea 访问权限；
库不会保存凭据。开发环境仍从本地工作树安装：
```bash
@@ -338,8 +338,9 @@ remove_marker = Modifier(
列表 continuation 和同深度引用；代码块、GFM pipe table、raw HTML table、混合候选行尾及无法确认的容器保持原文。
完整公共模型、选择流程和限制见
[`0009-generalized-mapped-line-join.md`](research-wiki/design/0009-generalized-mapped-line-join.md)，真实 backend 验收、
-版本身份和 GitHub 发布边界见
-[`0010-first-cross-project-library-delivery.md`](research-wiki/design/0010-first-cross-project-library-delivery.md)。
+版本身份和最初发布边界见
+[`0010-first-cross-project-library-delivery.md`](research-wiki/design/0010-first-cross-project-library-delivery.md)，当前 Gitea 发布渠道见
+[`0015-gitea-release-channel.md`](research-wiki/design/0015-gitea-release-channel.md)。
`html_table_entity_unescape()` 只在严格完整的 `| ` / ` | ` 文本中处理 `<`、`>` 和
`&`。`html_table_layout()` 只调整严格单行表格的外层行布局，并保留标签、属性和单元格内容。
diff --git a/research-wiki/design/0015-gitea-release-channel.md b/research-wiki/design/0015-gitea-release-channel.md
new file mode 100644
index 0000000..aac3489
--- /dev/null
+++ b/research-wiki/design/0015-gitea-release-channel.md
@@ -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 或其他仓库；
+- 工作区最终状态与本轮报告一致。
|