From faa2279f00581c4a0dc60d84e50898e37291127a Mon Sep 17 00:00:00 2001 From: caoqianming Date: Thu, 13 Aug 2026 13:55:47 +0800 Subject: [PATCH] docs(release): separate development pushes from releases --- AGENTS.md | 8 +++++--- CHANGELOG.md | 6 ++++++ RUN.md | 12 ++++++++++++ tests/test_changelog.py | 10 ++++++++++ 4 files changed, 33 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3230740..f5d6abb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -36,8 +36,11 @@ ## 文档与版本 -- 版本号、`CHANGELOG.md`、`PROGRESS.md` 在 push 前统一更新一次，不按每个 commit 更新。 -- push 前更新 `PROGRESS.md`：补“已完成关键能力”条目，状态表变化随之更新，新增或删除模块时同步文件清单。 +- 开发 push 与正式发布分离：功能开发期间允许持续 commit / push，不因此提升版本号，也不新增已发布的 `CHANGELOG.md` 数字版本条目。 +- 尚未发布但需要预先整理的用户文案写在 `CHANGELOG.md` 顶部 `## Unreleased`；该区不会被前端更新日志接口解析。正式发布时再把它改成 `## <版本> — <日期>`。 +- 版本号与用户版 `CHANGELOG.md` 只在功能稳定、准备上线时通过单独的 release commit 统一更新；同一次发布中校准 `PROGRESS.md`，不按每个开发 commit 更新。 +- 阶段性成果可随开发更新 `PROGRESS.md`；正式发布前补“已完成关键能力”条目，状态表变化随之更新，新增或删除模块时同步文件清单。 +- 未完成且不能让线上用户接触的功能，应在独立功能分支开发、待稳定后合并生产分支；若必须提前合并或部署，则使用默认关闭的 feature flag，并限制为管理员或测试账号启用。 - 版本号唯一事实源是 `core/__init__.py::__version__`： - patch：bug 修复、重构、调参、新 skill、样式； - minor：成批新功能或明显对外行为变化； @@ -59,4 +62,3 @@ ## 领域语境 主要使用方是中国建筑材料科学研究总院，核心语境是无机非金属材料研发与生产，包括水泥、混凝土、玻璃、陶瓷、耐火材料和新型建材。典型任务是配方研发、性能测试、XRD/SEM/热分析、实验数据建模，以及申报书、调研报告、专利和论文写作。默认按材料研发而非建筑施工、结构计算或 BIM 理解需求。 - diff --git a/CHANGELOG.md b/CHANGELOG.md index 22decda..104b68e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,7 +3,13 @@ > 面向用户的更新说明,由 `GET /v1/changelog` 解析后在前端「点版本号」弹层展示。 > 维护口径:只记**用户可感知**的变化("能干什么了"而不是"改了哪个模块"),纯内部重构 / 修复不记, > 所以不是每个版本号都有条目。条目格式 `## <版本> — <日期>`,新条目加在最上面。 +> 开发中的用户文案可先写入 `## Unreleased`；该区不会被前端解析，正式发布时再替换为数字版本和日期。 > 工程口径的完整记录见 `PROGRESS.md` / git log。 + +## Unreleased + + + ## 0.65.2 — 2026-08-13 - 粘贴、拖拽或选择附件发送后，对话中的用户消息会保留附件卡片；图片同时显示可点击放大的缩略图，刷新历史对话后也不会消失。 diff --git a/RUN.md b/RUN.md index bf8f619..78736c9 100644 --- a/RUN.md +++ b/RUN.md @@ -538,6 +538,18 @@ sudo bash deploy/update_bluegreen.sh > 蓝绿部署机(生产,已 bootstrap)一律用 `sudo bash deploy/update_bluegreen.sh`(见上节)。 > 下面的 `update.sh` 是单实例版:host backend 机 / 内网机 / 未切蓝绿的部署继续用。 +开发 push 与正式发布是两个动作：开发期间可以持续 push，但不提升 +`core/__init__.py::__version__`，也不新增 `CHANGELOG.md` 的数字版本条目。需要提前整理的 +用户文案写在 `## Unreleased`，前端不会展示。功能稳定后创建单独的 release commit，统一完成： + +1. 将 `## Unreleased` 改为 `## <版本> — <日期>`，只保留用户可感知的变化； +2. 更新 `core/__init__.py::__version__`； +3. 校准 `PROGRESS.md`，并按变更类型同步本文件或 `DESIGN.md`； +4. 部署并验证 `/healthz` 与 `/v1/changelog`。 + +未完成且不能向线上用户开放的功能应留在功能分支，稳定后再合并生产分支；必须提前部署时， +使用默认关闭且仅向管理员或测试账号开放的 feature flag。 + **一把梭(单实例):`deploy/update.sh`** ```bash diff --git a/tests/test_changelog.py b/tests/test_changelog.py index 48a1626..143b34a 100644 --- a/tests/test_changelog.py +++ b/tests/test_changelog.py @@ -8,6 +8,10 @@ SAMPLE = """# 更新日志 > 导语在首个条目前,应被丢弃。 +## Unreleased + +- 尚未发布,不能出现在用户版接口中 + ## 0.55.0 — 2026-07-09 - 条目 A @@ -36,6 +40,12 @@ class ChangelogParseTests(unittest.TestCase): def test_preamble_before_first_entry_is_dropped(self) -> None: es = _parse_changelog(SAMPLE) self.assertNotIn("导语", es[0]["body_md"]) + self.assertNotIn("尚未发布", es[0]["body_md"]) + + def test_unreleased_section_is_not_returned(self) -> None: + es = _parse_changelog(SAMPLE) + self.assertNotIn("Unreleased", [e["version"] for e in es]) + self.assertEqual([e["version"] for e in es], ["0.55.0", "0.54.1", "0.53.0"]) def test_real_changelog_file_parses(self) -> None: # 仓库里的真文件:格式坏了(条目头打错 / 空正文)在 CI 就翻车,不等用户点开才发现