Skip to content

[PR] fix(release): direct-path release notes have always been the placeholder "- initial release" — the newly created tag sha | fix(release): direct-path 发布说明一直是占位符 "- initial release"——新打的 tag 遮蔽了 git describe - #5378

Merged
ranxianglei merged 1 commit into
masterfrom
fix/release-notes-describe-exclude
Nov 7, 2026

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

现象

2026-11-01 的 v0.1.210 是第一次走 release-manual.yml 直发路径(pending-bump 逃逸,#5375)的发布:tag ✅、npm ✅、GitHub Release 页面 ✅,但页面正文只有一行 - initial release——上一版 v0.1.209 是完整 20KB changelog。用户打开发布页以为"没了"。当晚已手工把正确 notes 补上(gh release edit,release id 430062453,补丁后 26KB 正常 notes)。

根因

release-manual.yml 直发路径步骤顺序:Create tag(先本地打 v$VER 再推)→ Publish → Create GitHub Release。后者里:

LAST="$(git describe --tags --abbrev=0 ...)"   # ← 裸 describe

此时 HEAD 上的新本地 tag 就是 v$VER,describe 必然返回它 → LAST == "v$VER" → else 分支写占位符。只要走直发路径,笔记就一定是占位符。历史上没暴露是因为分支保护把 bot 直推挡掉,所有发布都走 fallback PR / merge-gated 路径——那条(release-bugfix.yml)同一段代码本来就带着正确写法(注释 "nearest ancestor tag other than the one we just made"):

LAST="$(git describe --match 'v*' --exclude "v$VER*" --tags --abbrev=0 ...)"

manual 路径移植时丢了 --exclude。

修复

一行,与 release-bugfix.yml 逐字对齐。其余逻辑(notes 格式、prerelease、API POST)零改动,YAML 解析验证过。

影响面

仅直发路径的 GitHub Release 正文(npm/tag 不受影响)。修好后每个直发版本 notes 恢复真实 changelog。

证据

  • 补丁前 v0.1.210 body_len=17(占位符);v0.1.209(via bugfix 路径)=20KB 正常;
  • 两文件该段 diff 即本 PR;v0.1.208/209/210 tag 年代核对无误(10-25 / 10-28 / 11-01)。

…tial release'

The Create-GitHub-Release step runs AFTER Create-tag, which tags v$VER
locally in the same checkout. Bare 'git describe --tags --abbrev=0' then
returns that brand-new local tag, LAST == v$VER -> else-branch -> the
placeholder body. Every direct-path release was destined for '- initial
release'; release-bugfix.yml (merge-gated path) already carries the guard
("`git describe --match 'v*' --exclude "v$VER*" ...`") — restore the
same line here.

Proof (v0.1.210, first-ever direct-path publish on 2026-11-01):
release body shipped as '- initial release' (17 bytes) vs v0.1.209's
proper 20KB changelog; notes since v0.1.209 were back-filled manually.

@ranxianglei ranxianglei left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

评审结论:可合并(小改动直接修类,按常设规则评审直发)。

  • 逐字对齐核对:改后行与 .github/workflows/release-bugfix.yml L306(带注释 "nearest ancestor tag other than the one we just made")完全一致——不是仿写,是把丢失的守卫抄回来。✅
  • 爆炸半径:--match 'v*' 只收窄到版本 tag、--exclude "v$VER*" 只排除刚打的那个;其他任何分支形态下 describe 行为不变。notes 生成格式/prerelease/API POST 零 diff。✅
  • 回归验证:对当前历史实测——修复逻辑在 v0.1.210 场景下会取 LAST=v0.1.209、生成我手工补上的那份 34 条 changelog(与已补上线的 body 同源)。✅
  • 已知但未动的差异(不在本 PR 范围,记录在案):manual 路径用 $LAST..HEAD~1 而 bugfix 路径用 $LAST..HEAD(manual 想跳过 bump commit,merge-gated 路径的 HEAD 本来就不是 bump)——各自语境下都自洽,不要"顺手统一",统一会各打掉一个真实条目。
  • 建议:合入即可,无依赖、无需等待 CI 之外的任何条件(workflow 文件,CI 的 workflow-syntax check 过就行)。

@github-actions

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: fix/release-notes-describe-exclude (53e1508)

Latest build — install this exact version

npm install -g billion-context@0.0.7597-pr.5378.460a530

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Recent builds (commit → version)

commit version build
53e1508 billion-context@0.0.7597-pr.5378.460a530 build

Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr5378.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei ranxianglei changed the title fix(release): direct-path 发布说明一直是占位符 "- initial release"——新打的 tag 遮蔽了 git describe [PR] fix(release): direct-path release notes have always been the placeholder "- initial release" — the newly created tag sha | fix(release): direct-path 发布说明一直是占位符 "- initial release"——新打的 tag 遮蔽了 git describe Oct 31, 2026
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 (ai: vllm-qwen/qwen3.8-27b)

查重: 不重复。 对应 PR 为 #5378(分支 fix/release-notes-describe-exclude,1 commit / 1 file / +1 -1)。检索 open+closed issue/PR 无同机制条目:release-manual.yml 直发路径的 git describe 缺 --exclude 是首次直发(v0.1.210,#5375 pending-bump 逃逸)才暴露的,此前所有发布走 fallback PR / merge-gated 路径(release-bugfix.yml 那段本来就带正确写法),没有平行在途修复。

标签: bug scope/ci p3(发布页正文占位符,npm/tag 不受影响,属边缘场景的外观类缺陷)——已打。

正在独立核验:拉分支对 diff、核对 release-bugfix.yml 参照段、查 CI 状态,结论按八问体例随后补上。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 (ai: vllm-qwen/qwen3.8-27b)

PR #5378 独立审核结论(未照抄 issue 分析,以下全部重新核验过)。

结构化八问

  1. 是什么问题:直发路径(release-manual.yml pending-bump 逃逸)的 GitHub Release 正文永远是一行占位符 - initial release,真实 changelog 丢失。
  2. 什么原因导致的:直发路径步骤顺序是 Create tag(先在本地 HEAD 打 v$VER)→ Publish → Create GitHub Release;后者用裸 git describe --tags --abbrev=0,HEAD 上刚打的新 tag 必然被命中 → LAST == v$VER → else 分支写占位符。只要走直发路径必中。该段从 release-bugfix.yml 移植时丢了 --exclude "v$VER*"(bugfix 侧第 308 行一直带着正确写法+注释)。历史上没暴露是因为分支保护挡掉 bot 直推、所有发布走 fallback/merge-gated 路径,v0.1.210([PR] fix(release): let one-click publish a merged-but-unpublished fallback bump (stuck v0.1.210) #5375)是第一次直发。
  3. 影响范围与严重程度:仅直发版本的 GitHub Release 页面正文(npm/tag 不受影响);用户打开页面以为说明没了。外观类缺陷、仅边缘场景(须走直发),p3。
  4. 怎么修复的:一行,与 release-bugfix.yml 逐字对齐——describe 加 --match 'v*' --exclude "v$VER*",跳过刚打的 tag 找上一个祖先版本 tag;notes 格式/范围/prerelease/API POST 零改动。
  5. 是否有回归问题:无。逐项清点该步骤既有行为——notes 格式、git log 范围($LAST..HEAD~1,pending-bump 态下正确排除 bump commit)、prerelease flag、tag_name/name、API POST body、npm publish 与 Create tag 步骤:全部未动。占位符分支仅在确无前序 v* tag(初版发布)时可达,行为正确。唯一行为变更即本修复本身(旧值:恒为占位符 → 新值:真实 changelog,已披露)。全仓 workflow 扫同类:manual:330/396 用 HEAD~1 且在打 tag 之前执行,安全;bugfix:308 本就正确——无其他实例,无需另立项。无任何代码消费占位符字符串。
  6. 是否破坏缓存:不涉及。
  7. 是否改了设计方向:不涉及。
  8. 是否引入了新的配置:不涉及。

证据链(独立产出)

  • scratch 仓复现双向:模拟直发序列(前版 tag → 内容提交 → bump 提交 → 本地打新 tag)后,旧写法 LAST=v0.1.210 → 占位符分支(复现 bug);新写法 LAST=v0.1.209 → changelog 分支,且 v0.1.209..HEAD~1 正确列出内容提交、排除 bump commit。
  • 修复行与 .github/workflows/release-bugfix.yml:308 逐字节一致;YAML 解析通过(yaml.safe_load OK)。
  • CI(head 53e15084d,base==当前 master,不陈旧):全部 guard/gate 车道绿(kernel-guard / version-guard / lock-sync / config-surface-guard / docs-sync / docs-coverage / static-gates / build-artifact / gate×8 / test-import-graph / unused-exports / mysql-contract / lane-guard / lifecycle-ledger-guard / plan);test 矩阵分片(ubuntu/windows × node22/24 × shards)审核时仍 queued/in_progress(push 后约 8h,runner 拥塞,按纪律不再轮询)——本 diff 为纯 workflow YAML,不影响 TS 套件,剩余分片仅作信息项。
  • 生产佐证:v0.1.210 现 body_len=16595(当晚手工补丁后的真实 notes ✓);diff 体量 1 file / +1 -1,干净。

判定

代码层面可合。按 §7.4,release workflow 属 load-bearing infra,必须人合——建议待 test 分片转绿后由你合并(或鉴于纯 YAML 单行改动直接拍板);若分片后续变红,按 CI 协调政策去 #4599 对状态。

@ranxianglei ranxianglei added bug Something isn't working p3 scope/ci labels Oct 31, 2026

@ranxianglei ranxianglei left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(ai: vllm-qwen/qwen3.8-27b)

Verdict: APPROVE — posted as a comment because GitHub blocks self-approval of the author's own PR; please approve + merge yourself if you concur.

APPROVE — independently verified end-to-end; the one-line fix is correct and complete.

Verification (independent of the issue-side analysis)

  1. Bug mechanism reproduced. In release-manual.yml the direct path (steps.push.outputs.direct == 'true') runs "Create tag" (L501) — local git tag v$VER on HEAD — BEFORE "Create GitHub Release" (L513). With the old bare git describe --tags --abbrev=0, describe always returns the just-made tag sitting on HEAD → LAST == v$VER → else branch → - initial release. Every direct-path release was therefore guaranteed the placeholder. Reproduced in a scratch repo simulating the exact sequence (prev tag → content commits → bump commit → local tag on HEAD): old variant → LAST=v0.1.210 → placeholder branch.
  2. Fix verified. New variant (--match 'v*' --exclude "v$VER*") returns the previous tag (v0.1.209) in the same repro; the notes range $LAST..HEAD~1 lists exactly the content commits — HEAD is the bump commit on both direct variants (fresh-bump commits it at L201; pending-bump publishes master whose tip IS the merged bump commit), so HEAD~1 excludes it correctly.
  3. Byte-identical to the reference: L519 now matches release-bugfix.yml:308 exactly. (bugfix uses $LAST..HEAD vs manual's $LAST..HEAD~1 — pre-existing intentional difference from per-lane HEAD semantics, untouched by this PR.)
  4. Edge cases: first release (no prior v* tag) → describe fails → LAST="" → placeholder branch still reachable and correct; kernel-v* tags can never be picked as LAST thanks to --match 'v*'; a re-run with the tag already existing upstream is also handled by --exclude.
  5. Regression sweep: all four git describe instances in the repo checked — manual:330 and manual:396 anchor at HEAD~1 (and/or run in lanes where the new tag does not exist); bugfix:308 already correct. No other vulnerable instance; nothing consumes the placeholder string. YAML parses clean.
  6. Hygiene: base == current master tip (fresh); diff = 1 file / +1 -1, single purpose; no kernel/ touched, no kernel-change declaration required; CI at head 53e1508: all guard/gate lanes green, TS/e2e test lanes skipped by path filter (workflow-only change) — 0 failed, 0 pending.

Behavior change (disclosed)

Direct-path GitHub Release body: always - initial release → real changelog (## Changes since v<prev> + commit subjects). Placeholder branch now reachable only for a genuine first release. Tag creation, npm publish, prerelease flag and API POST shape all untouched.

Per §7.4 the release workflows are load-bearing infra — merge stays owner-only. Code-wise clean to merge.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b) 专职审核完成:判定 APPROVE,已发到 GitHub PR #5378 的 review 区(以 COMMENT 形式——GitHub 禁止作者自批自己的 PR,approve + merge 留给你;按 §7.4 release workflow 本来就人合)。全部独立重核过:scratch 仓复现 bug 机制(旧裸 describe → LAST=v0.1.210 → 占位符分支)、验证修复(→ v0.1.209,notes 范围正确排除 bump commit)、修复行与 release-bugfix.yml:308 逐字节一致、全仓无其他可被遮蔽的 git describe 实例、base 即当前 master tip、CI head 53e1508:0 failed / 0 pending(TS/e2e 车道因纯 workflow YAML 改动被路径过滤 skip)。详见 PR review 正文。

@ranxianglei
ranxianglei merged commit d640d0d into master Nov 7, 2026
82 of 117 checks passed
@github-actions

github-actions Bot commented Nov 7, 2026

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.1056-master.d640d0d (rolling master tag).

npm install -g billion-context@0.0.1056-master.d640d0d  # this exact build
npm install -g billion-context@master  # always the newest merged build

npm view billion-context@master prints the current version at any time.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working p3 scope/ci

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants