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