Skip to content

[PR] fix: pin docs Markdown to LF in .gitattributes - #6693

Closed
OMSociety wants to merge 1 commit into
ranxianglei:masterfrom
OMSociety:2026-11-14_docs-eol
Closed

OMSociety wants to merge 1 commit into
ranxianglei:masterfrom
OMSociety:2026-11-14_docs-eol

Conversation

@OMSociety

Copy link
Copy Markdown
Contributor

Closes #6692

.gitattributes 原来只为字节精确的 golden / fixture 路径钉了 eol=lf,docs/ 下的 Markdown 没有规则;在 Windows 侧(core.autocrlf=true)编辑后提交会把整份文件写成 CRLF——#6592 只加 18 行却产生 +1509/-1489 的 raw diff,最后要靠一次 revert 提交才把净 diff 收回。

本次加一条:

docs/**/*.md text eol=lf

** 覆盖 docs/architecture/ 等子目录。核验:

  • git check-attr text eol -- docs/clients.md docs/index.md docs/architecture.md docs/architecture/agent.md 逐项得 text: set / eol: lf;CLAUDE.md 等 docs/ 之外的 Markdown 仍是 unspecified,不受影响。
  • 索引中 docs/ 现有文件已是 LF(git ls-files --eol docs 无 i/crlf),因此加规则不产生重写 diff:本 PR 的 diff 只有 .gitattributes 一个文件、+5 行。
  • 顺带证实了前提:加规则后 git 提示工作区里 docs/configuration.md、docs/configuration.zh-CN.md 现为 CRLF、将在下次触碰时归一为 LF——正是这条规则要挡的那类漂移。

@ranxianglei ranxianglei changed the title fix: pin docs Markdown to LF in .gitattributes [PR] fix: pin docs Markdown to LF in .gitattributes Nov 14, 2026
@ranxianglei

Copy link
Copy Markdown
Owner

🤖 Powered by ework · qwen3.8-27b

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

查重: 不重复 — 这是 issue #6692 的唯一在途 PR;历史上有过同族工作 #2624/#2632/#2634,但对象是 dsh.bundle.patch.yml(Windows CI 字节精确匹配),不是 docs/*.md,机制相同(eol=lf 钉死)但文件域与触发场景不同,不构成重复。

已接单,正在按 PR review 规范做独立审核:核对 diff、验证 issue 前提(Windows core.autocrlf=true 下 CRLF 漂移)、检查既有行为影响与 CI 状态。结论稍后按结构化八问给出。

@ranxianglei

Copy link
Copy Markdown
Owner

🤖 Powered by ework · qwen3.8-27b

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

独立审核完成(未照抄 PR 描述,以下证据均为本会话实测):

前提复核 — issue #6692 的指控成立,且数字精确:

  • PR [PR] docs(clients): dsh-go host | docs(clients): dsh-go 宿主 #6592 首个提交 a1fc6eb1 的 raw diff 实测:docs/clients.md +1133/-1115 + docs/clients.zh-CN.md +376/-374 = +1509/-1489,与描述一致;第二提交 08ed4191("revert accidental CRLF line-ending conversion")确为收尾 revert。
  • 当前 master 的 .gitattributes 只有 5 条 eol=lf 规则,全部针对字节精确路径(golden/fixture/dsh.bundle.patch.yml),docs/ 确无覆盖。
  • 索引状态实测:git ls-files --eol docs 共 107 个文件,86 个 i/lf、21 个 i/-text(SVG 等),无 i/crlf → 加规则不产生重写 diff。PR diff 实测就是 1 文件 +5/-0,无夹带。
  • git check-attr 实测(在 PR 分支的 .gitattributes 上):docs/foo.md、docs/a/b/c.md(任意嵌套)、docs/index.zh-CN.md 全部 text: set / eol: lf;docs/architecture/assets/*.svg、CLAUDE.md、README.md、AGENTS.md、CHANGELOG.md、kernel/README.md、pi-subagents/README.md 全部 unspecified → 作用域精确,不外溢。
  • 新鲜度:PR 分支 base = 当前 master head(9495c764d3),master 侧自 base 以来 .gitattributes 零变更,无需 rebase。
  • 回归面清点:tests/ 内对 docs/*.md 的引用全部是注释或字符串字面量(文档指引),无字节级读取;读 docs 的脚本(lifecycle-ledger-guard / config-surface-guard / gen-config-docs)做的是模式匹配,LF 归一对匹配只会更一致;CI 的 e2e 车道对本文件不触发(skipped 5 项属预期)。

CI 实况(镜像缓存,10:26 UTC 快照):27 项检查,0 红,20 排队中,2 绿,5 跳过;mergeable_state: blocked 是检查未跑完的常态,非代码问题。CI 全绿后我会跟评一句。

一个观察(不拦合并):docs/ 之外的 Markdown(根目录 README.md/AGENTS.md/CHANGELOG.md、kernel/README.md、pi-subagents/README.md)同样处于 unspecified,Windows 侧编辑有同类 CRLF 漂移暴露面。本 issue 范围钉在 docs/,PR 按 issue 范围做是对的;是否把规则扩到全仓 *.md 属于另一个决策,这里只留记录,不扩本 PR 范围。


结构化八问

  1. 是什么问题:docs/ 下的 Markdown 没有 eol 钉死,Windows 侧(core.autocrlf=true)一次普通编辑提交就把整份文件翻成 CRLF,真实改动被全文件 diff 淹没,还得靠 revert 提交收网。
  2. 什么原因导致的:Git 对无 eol 规则的路径在 Windows 默认 autocrlf=true 下提交时做 CRLF 归一;.gitattributes 此前只为字节精确的 golden/fixture 路径钉了 eol=lf,散文类文档路径漏了——是规则覆盖缺口,不是 Git 行为异常。
  3. 影响范围与严重程度:仅 Windows 侧编辑 docs/*.md 的人/会话;触发条件=Windows + autocrlf=true + 触碰 docs 文档;严重度=体验/审查质量瑕疵(diff 淹没、误判改动面),不影响任何运行时功能,无数据损坏。
  4. 怎么修复的:在源头(版本库属性)钉死 docs/**/*.md text eol=lf,让 Windows 侧提交/签出都归一到 LF——修的是"产生 CRLF 的机制"(属性缺失),不是事后过滤;** 覆盖任意子目录,作用域与 issue 一致。
  5. 是否有回归问题:无。既有 5 条 eol 规则逐字未动;索引内容零变化(无重写 diff);非 md 文件与 docs 外 md 文件实测不受影响;Linux/macOS 侧行为不变(本来就是 LF)。唯一行为变化=Windows 工作区的 docs md 文件在下次签出/触碰时从 CRLF 归一为 LF——这正是修复目标,且 PR 描述已披露。
  6. 是否破坏缓存:不涉及(无缓存/游标/去重键)。
  7. 是否改了设计方向:不涉及;沿用仓库既有的 eol 钉死惯例(test: wire-contract anti-regression system — parity fakes, goldens, unified ledger #1305/Windows CI 全红:#2610 新增的 bundle-patch 测试对 CRLF 签出的 yml 做字节级精确匹配(.gitattributes 未覆盖) #2631/feat(web): add zoom-to-selection (brush) to the session context-trajectory chart #2489/Cache hit-rate line chart: per session and global | [Feature] 缓存命中率折线图:单会话 + 全局 #3484 同一失败类,同一解法)。
  8. 是否引入了新的配置:不涉及(无新 env/config/默认值)。

判定:代码审核通过,diff 干净、范围精确、修法打在根因上;待 CI 全绿即可由 owner 合并。

@ranxianglei

Copy link
Copy Markdown
Owner

🤖 Powered by ework · qwen3.8-27b

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

CI 状态更新(11:03 UTC 实测):检查仍在跑,目前 0 红;代码侧审核结论不变——通过,等 CI 全绿后由 owner 合并即可。

@ranxianglei

Copy link
Copy Markdown
Owner

🤖 Powered by ework · qwen3.8-27b

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

收工小结(本会话全部工作已完成,结论汇总如下):

@ranxianglei

Copy link
Copy Markdown
Owner

Closes pair #6692 was auto-closed by the batch merge.

Superseded by #6765 (merged to master as e488b7e).

Your commit dd1bd81 is in master verbatim — same content, same authorship, only the object ID changed (the batch used a real git merge, no rebase or cherry-pick rewrite). Merged under a different branch name, so GitHub does not flip this PR by itself.

Thanks for the fix — it is live in master from e488b7e onward.

ranxianglei added a commit to NewbieXvwu/billion-context that referenced this pull request Nov 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

2 participants