Skip to content

Commit 6db884b

Browse files
authored
fix(release): 新版本节排在 [Unreleased] 下面,并把攒的条目整段搬进去 (#472)
* fix(release): 新版本节排在 [Unreleased] 下面,并把攒的条目整段搬进去 Release Prep 的第一次实跑(v0.9.1)暴露出两个位置错误,都是「机器算得对的事留给人补」: 1. 新版本节插在 `# Changelog` 之后,也就是 `## [Unreleased]` 之上——顺序颠倒。 v0.9.0 那次是靠事后一笔人工提交(77df0fb)掰回来的。 2. 只插一个「🐛 修复 /(待填)」空占位,[Unreleased] 里攒的条目原地不动, 于是发版后文件里同时存在「新节是空的」和「旧条目还挂在 Unreleased 名下」。 同一个 77df0fb 补的就是这件事。 改法:有 [Unreleased] 时先切出它到下一个 `## [` 之间的正文,非空则整段搬进 新版本节、[Unreleased] 留空;为空才插占位节。搬的是位置不是内容,一个字不改—— 「新节里该写什么」这个判断仍然只由往 Unreleased 写条目的人做。返回体加 `moved`, 入口日志与收尾清单据此说真话。 回归测试重写为 8 条,锁住两个方向:插在下面(断言 indexOf 顺序)与整段搬走 (断言不含「(待填)」、小节整体搬、多小节不拆散),外加空 Unreleased 不产生多余 空行、带 BOM 与 CRLF 检出仍能命中、幂等与 header-not-found 契约。 CONTRIBUTING 的发布流程第 1、2 步同步改写:先前的「在 CHANGELOG 顶部插入占位节」 与「工作流只留一条 -(待填)」两句现在是假话。 * fix(release): 搬 [Unreleased] 条目时原样搬——保首行缩进,日志判据与计数分开 - changelog-prep: body.trim() 吃掉首行前导空格,四空格缩进代码块会降级成普通段落; 改为 stripBlankEdges() 只剥节边界空行,正文逐行原样保留,并以原文 eol 拼回 - changelog-prep: 成功分支加 movedContent 布尔,日志分支只看它; moved 只表示 `- ` 条目数 (正文非空但无条目时 moved 是 0,拿它当判据会打印「占位节」而它并不空) - release-prep: 第 3 步日志改三态 - 回归测试 8 → 10 条;双 README 徽章刷到 2171
1 parent 611d156 commit 6db884b

7 files changed

Lines changed: 164 additions & 31 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -148,9 +148,9 @@ Bug-fix PRs for existing desktop compatibility issues are still welcome.
148148

149149
Versioning follows semantic versioning (`MAJOR.MINOR.PATCH`). The mechanical parts are automated; the editorial parts stay with a human — **the machine writes what the version number alone determines, a human writes what needs judgement**. Full flow:
150150

151-
1. **Run the Release Prep workflow** (`.github/workflows/release-prep.yml`, manual dispatch, one input: the target version). It bumps `version` in `dsh-mneme/package.json` + `package-lock.json`, refreshes the test count in both READMEs (badge + the four `# N …tests` comment shapes), inserts the CHANGELOG placeholder section, adds placeholder rows to the version tables in both READMEs, flips a leftover 「🚧 准备中」 roadmap cell to released, and opens a `release-prep/X.Y.Z` PR.
151+
1. **Run the Release Prep workflow** (`.github/workflows/release-prep.yml`, manual dispatch, one input: the target version). It bumps `version` in `dsh-mneme/package.json` + `package-lock.json`, refreshes the test count in both READMEs (badge + the four `# N …tests` comment shapes), opens the new CHANGELOG section under `[Unreleased]` and moves whatever had accumulated there into it (a `- (待填)` placeholder is only left when `[Unreleased]` was empty), adds placeholder rows to the version tables in both READMEs, flips a leftover 「🚧 准备中」 roadmap cell to released, and opens a `release-prep/X.Y.Z` PR.
152152
2. **Fill in what only a human can write**, in that PR:
153-
- the CHANGELOG entries themselves (`## [X.Y.Z] - date`, split into 「修复 / 新增 / 测试」; the workflow only leaves `- (待填)`). End the section with a `### 贡献者 / Thanks` subsection summarising outside contributors (`git log vPrev..HEAD --format='%an <%ae>' | sort -u`; list non-maintainers as "GitHub handle + what they did", and keep the inline 「感谢 @handle」 in the entry too); omit it when there are none. **Keep entries neutral**: no references to non-public issue numbers and no internal experiment codenames — nobody reading this repository can resolve them.
153+
- the wording and the cuts in the CHANGELOG entries (`[Unreleased]` entries are already moved into the new section by the workflow — do not move them by hand; split them into subsections and rewrite them for outside readers). End the section with a `### 贡献者 / Thanks` subsection summarising outside contributors (`git log vPrev..HEAD --format='%an <%ae>' | sort -u`; list non-maintainers as "GitHub handle + what they did", and keep the inline 「感谢 @handle」 in the entry too); omit it when there are none. **Keep entries neutral**: no references to non-public issue numbers and no internal experiment codenames — nobody reading this repository can resolve them.
154154
- the theme text of the new placeholder rows in both READMEs;
155155
- one new row in each of the root README's 「📰 最近更新」 / 「📰 Recent updates」 tables (pure editorial content — the workflow never touches them).
156156
3. **Cross-minor releases only**: the workflow prints a warning instead of failing when `SECURITY.md`'s supported-versions table still names the previous minor. Shift both language tables down one row (new minor → active, previous minor → best-effort, and update the end-of-life notice below them) inside the same PR; until then `test/security-doc.test.js` is red, which is exactly when it should be.
@@ -346,9 +346,9 @@ DSH 上游仍处于 developer preview 阶段,API 与服务接口变动频繁
346346

347347
版本号遵循语义化版本(`MAJOR.MINOR.PATCH`)。机械的部分交给工作流,编辑判断的部分留给人——**版本号自己能确定的东西机器写,需要判断的东西人写**。完整流程:
348348

349-
1. **跑 Release Prep 工作流**(`.github/workflows/release-prep.yml`,手动触发,只填目标版本号)。它做这些:改 `dsh-mneme/package.json` 与 `package-lock.json` 的 `version`;刷新两个 README 的测试数(徽章 + 四种 `# N …测试` 注释形状);在 CHANGELOG 顶部插入版本占位节;给两个 README 的版本表各插一行占位;把路线图上遗留的「🚧 准备中」回填成已发布;最后推 `release-prep/X.Y.Z` 分支并开 PR。
349+
1. **跑 Release Prep 工作流**(`.github/workflows/release-prep.yml`,手动触发,只填目标版本号)。它做这些:改 `dsh-mneme/package.json` 与 `package-lock.json` 的 `version`;刷新两个 README 的测试数(徽章 + 四种 `# N …测试` 注释形状);在 `[Unreleased]` 下面开新版本节,并把里面攒的条目整段搬进去(只有 `[Unreleased]` 本来是空的才留一条 `- (待填)`);给两个 README 的版本表各插一行占位;把路线图上遗留的「🚧 准备中」回填成已发布;最后推 `release-prep/X.Y.Z` 分支并开 PR。
350350
2. **在这个 PR 里补上只有人能写的内容**:
351-
- CHANGELOG 的条目本身(`## [X.Y.Z] - 日期`,分「修复 / 新增 / 测试」;工作流只留一条 `- (待填)`)。小节末尾加 `### 贡献者 / Thanks` 汇总本版外部贡献者(`git log v上一版..HEAD --format='%an <%ae>' | sort -u`,非维护者逐条列「GitHub 用户名 + 一句话做了什么」,条目内也保留「感谢 @用户名」);无外部贡献者时省掉该小节。**条目一律用中性措辞**:不引用非公开的 issue 编号、不出现内部实验代号——它们在公开仓库里解析不出来,读者只会困惑。
351+
- CHANGELOG 条目的措辞与取舍(`[Unreleased]` 攒的条目工作流已整段搬进新版本节,**不用手搬**;把它们分节并改写成外部读者能看懂的话)。小节末尾加 `### 贡献者 / Thanks` 汇总本版外部贡献者(`git log v上一版..HEAD --format='%an <%ae>' | sort -u`,非维护者逐条列「GitHub 用户名 + 一句话做了什么」,条目内也保留「感谢 @用户名」);无外部贡献者时省掉该小节。**条目一律用中性措辞**:不引用非公开的 issue 编号、不出现内部实验代号——它们在公开仓库里解析不出来,读者只会困惑。
352352
- 两个 README 里新占位行的主题描述;
353353
- 根 README 的「📰 最近更新」与「📰 Recent updates」表各加一行头条(纯编辑内容,工作流从不改写这两张表)。
354354
3. **只有跨 minor 发版时**:`SECURITY.md` 的支持版本表还写着上一个 minor 时,工作流只警告不失败。在同一份 PR 里把中英两张表向下挪一格(新 minor 进活跃行、上一版进尽力维护行,并同步改下面的停止维护通知);在那之前 `test/security-doc.test.js` 是红的——那正是它该红的时候。

‎README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-3E63DD?style=flat-square" alt="license"></a>
1111
<a href="https://github.com/slow-stack/mneme/actions"><img src="https://img.shields.io/github/actions/workflow/status/slow-stack/mneme/ci.yml?style=flat-square&label=CI" alt="CI"></a>
1212
<a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-22%2B-3E63DD?style=flat-square&logo=nodedotjs&logoColor=white" alt="node"></a>
13-
<a href="https://github.com/slow-stack/mneme"><img src="https://img.shields.io/badge/tests-2167%20passed-3E63DD?style=flat-square" alt="tests"></a>
13+
<a href="https://github.com/slow-stack/mneme"><img src="https://img.shields.io/badge/tests-2171%20passed-3E63DD?style=flat-square" alt="tests"></a>
1414
<a href="https://codecov.io/gh/slow-stack/mneme"><img src="https://img.shields.io/codecov/c/github/slow-stack/mneme/main?style=flat-square" alt="coverage"></a>
1515
<a href="https://github.com/awesome-dsh-plugin/awesome-dsh-plugin"><img src="https://awesome-dsh-plugin.com/badge.svg" alt="Awesome"></a>
1616
</p>
@@ -268,7 +268,7 @@ dsh-mneme-serve # 默认 ~/.dsh/memory + 127.0.0.1:8790
268268

269269
```bash
270270
cd dsh-mneme && npm install
271-
npm test # 2167 个测试
271+
npm test # 2171 个测试
272272
npm run stress # 三轴线压测
273273
npm run sync # src → lib 同步
274274
```
@@ -546,7 +546,7 @@ Community projects that wire mneme into more platforms — not part of this repo
546546

547547
```bash
548548
cd dsh-mneme && npm install
549-
npm test # 2167 tests
549+
npm test # 2171 tests
550550
npm run stress # three-axis stress test
551551
npm run sync # src → lib sync
552552
```

‎dsh-mneme/CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@
2626

2727
- **Release 正文从「CHANGELOG 逐字搬运」改成「标题 + 一句导语 + 折叠细节」(新增 `dsh-mneme/scripts/release-notes.mjs`)**:此前 `release.yml` 用内联 `node -e` 把 CHANGELOG 该节原样写进 Release 说明,于是 v0.9.0 的 Release 页有 29921 字符、单条子弹最长 3318 字符——正文里全是决策理由与变异验证,读者要点开一屏才知道这条在说什么。抽取搬到独立模块并改成**分层渲染**:每条子弹保留粗体标题与一句导语(默认可见),其余正文折进 `<details>`,**CHANGELOG 本体一个字不动**(那是含决策理由与审计线索的完整记录,压缩只发生在对外渲染这一步)。导语切分规则全由真实语料逼出:句末标点只认 `。!?` 而**刻意不认半角句号**(版本号里的点是同一字符,认了会切在版本号中间);软标点断点必须**括号平衡**(v0.9.0 实测切出过「GET /external-api(明文回吐 Bearer,」这种把从句切断的收尾);导语不得短于 24 字符(有条首句只有 8 个字的「两处水源在说谎。」,离开上下文没有信息量);正文本身比上限还短时整段就是导语、不再加省略号(否则凭空说「后面还有」)。回归锁 17 条进新增的 `test/release-notes.test.js`(含真进程端到端:渲染后 CHANGELOG 字节不变、找不到小节必须非零退出且报出是哪一版),`test/release-workflow.test.js` 补一条「正文抽取必须调模块、不许退回内联脚本」。**两条评审意见都是真 bug,各补一条锁**:一是「短正文保护」原先守在 `lede()` 末尾、排在软断点搜索之后,短正文里只要有逗号就会被加省略号,逗号恰是末字时省略号后面什么都没有、折叠块是空的——这条保护必须最先执行;二是渲染单位错成了「行」,而 CHANGELOG 里有 **179 行缩进续行**(0.8.6 / 0.8.7 / 0.8.12 等老版本集中出现,另有 59 行缩进子列表),逐行 trim 会把续行甩到条目的 `<details>` 外面并丢掉缩进,读者看到的是「正文只有一句,剩下的莫名其妙散在下面」——改为先 `splitBlocks()` 切出「一条子弹 + 它的全部续行」再按**条目**渲染,且**导语只从条目首行取**(把续行拼回正文再切,换行会混进可见行,续行又被推回 details 外面)。变异验证三轮共十处全部变红(删短正文保护 / 去掉括号平衡 / 导语上限归零 / 软断点 `consumed` 少记一位 / details 与正文之间去掉空行 / 删入口守卫 / 删版本格式校验 / 短正文保护挪回末尾 / 退回逐行渲染 / 导语改从整段取)。
2828

29+
- **发版准备把新版本节插在了 `[Unreleased]` 之上,且把攒着的条目留在原地(第一次实跑暴露,随后按评审意见补两处)**:改造后的 Release Prep 工作流第一次在真实 main 上跑 v0.9.1,`gh pr create` 因组织策略失败(GitHub Actions 不允许开 PR,属合理默认,不改),但脚本已经跑完并推了分支——于是它的产出能被直接审。产出是错的,两个位置错误:新版本节被插在 `# Changelog` 之后、也就是 `## [Unreleased]` **之上**,得到「`[0.9.1]` 排在 `[Unreleased]` 前面」的颠倒顺序;`[Unreleased]` 里攒的 9 条条目**原地不动**,新节里只有一条「🐛 修复 /(待填)」。两处都有同一个历史痕迹作证:v0.9.0 那次发版(`a9f8e35`)之后靠一笔人工提交 `77df0fb`「v0.9.0 版本节补上内容——把 [Unreleased] 攒的 27 条搬进来」才掰回来——**机器算得对的事不该留给人补**。现在先切出 `[Unreleased]` 到下一个 `## [` 之间的正文:非空则整段搬进新版本节、`[Unreleased]` 留空;为空才插占位节。搬位置不搬内容,一个字不改,所以「新节里该写什么」仍然只由往 `[Unreleased]` 写条目的人做。**两条评审意见都是真问题,各补一条锁**:一是用 `moved`(`- ` 条目数)当「有没有搬」的判据是错的——正文非空但一条 `- ` 都没有时 `moved` 是 0,入口会打印「占位节(`[Unreleased]` 本来是空的)」,而它显然不空;改为独立字段 `movedContent` 决定日志分支、`moved` 只用来把话说得更具体。二是 `body.trim()` 会吃掉首行的前导空格,`[Unreleased]` 首行若是四空格缩进代码块就会降级成普通段落,与「原样搬」矛盾;改为只剥节边界空行(并以原文行尾拼回,免得 CRLF 文件退化成混合行尾)。回归测试 8 条 → 10 条。
2930
## [0.9.0] - 2026-10-17
3031

3132
## 🆕 新增

‎dsh-mneme/README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
[![npm version](https://img.shields.io/npm/v/@modusensus/dsh-mneme?color=blue&label=npm)](https://www.npmjs.com/package/@modusensus/dsh-mneme)
66
[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
77
[![Awesome](https://awesome-dsh-plugin.com/badge.svg)](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
8-
[![tests](https://img.shields.io/badge/tests-2167%20passed-success)](https://github.com/slow-stack/mneme)
8+
[![tests](https://img.shields.io/badge/tests-2171%20passed-success)](https://github.com/slow-stack/mneme)
99
[![CI](https://img.shields.io/github/actions/workflow/status/slow-stack/mneme/ci.yml)](https://github.com/slow-stack/mneme/actions)
1010
[![node](https://img.shields.io/badge/node-22%2B-blue)](https://nodejs.org)
1111
[![npm downloads](https://img.shields.io/npm/d18m/@modusensus/dsh-mneme.svg?color=blue&label=downloads)](https://www.npmjs.com/package/@modusensus/dsh-mneme)
@@ -673,7 +673,7 @@ src/
673673
├── api.js # HTTP 路由(Web 面板数据通道,含 /conflicts 冲突队列)
674674
└── index.js # 插件接线
675675
lib/ # src 的同步分发产物(npm run sync,prepack 钩子在发布时自动跑;一致性由 scripts/check-sync.js 在 CI 与 release.yml 校验——它只查不同步;唯一手写例外 lib/client.js——Web 面板 bundle,sync 不覆盖)
676-
test/ # 2167 个 node:test 测试(审计与三轴线压测不变量;src↔lib 一致性由 scripts/check-sync.js 发布闸门校验)
676+
test/ # 2171 个 node:test 测试(审计与三轴线压测不变量;src↔lib 一致性由 scripts/check-sync.js 发布闸门校验)
677677
scripts/ # e2e-dsh.js 端到端演示 · stress-dsh.js 三轴线压测 · sync-lib.js 同步 · check-sync.js 发布闸门 · benchmark-recall.js / benchmark-embed.js / benchmark-rerank.js 基准 · sync-test-badge.mjs 测试徽章 · build-runtime-manifest.mjs 运行时清单
678678
```
679679
@@ -682,7 +682,7 @@ scripts/ # e2e-dsh.js 端到端演示 · stress-dsh.js 三轴线压
682682
```bash
683683
cd dsh-mneme
684684
npm install # 安装 peer 依赖(以 devDependencies 形式,用于本地测试)
685-
npm test # 运行 2167 个测试
685+
npm test # 运行 2171 个测试
686686
npm run stress # 三轴线压测:长会话检索 / 冲突仲裁 / 多 Agent 并发(离线 mock LLM)
687687
npm run sync # 把 src/ 同步到 lib/(发布时由 prepack 钩子自动执行)
688688
```

0 commit comments

Comments
 (0)