docs: 贡献规范落地 —— CONTRIBUTING + Docs Gate 门禁 + PR 模板（Refs #137） - #138
docs: 贡献规范落地 —— CONTRIBUTING + Docs Gate 门禁 + PR 模板（Refs #137）#138johnnyzhang-eng wants to merge 1 commit into
Conversation
「工程文档不入仓」此前只写在营规范原文和群消息里,仓库内没有落点, 也没有任何机械约束。1024XEngineer#128 刚删掉 docs/module-split.md,1024XEngineer#126 又把它改回来 并新增 6 份工程文档——改动一大,md 就藏在两百多个文件里没人看见。 - CONTRIBUTING.md:规范全文,按「CI 自动拦 / 只能靠自觉 / 需要人判断」三层组织 - .github/workflows/docs-gate.yml:把这条变成 CI 门禁。刻意保守,只管 docs/** 与根目录新增 md;删除、子目录 README/MODULES.md、允许清单一律放行, 打 user-doc label 可豁免 - .github/pull_request_template.md:自检清单,各项指向 CONTRIBUTING 小节 - .claude/skills/windup-contrib/:让 Claude Code 自动指到 CONTRIBUTING,不含规则 门禁拿全部 15 个 open PR 的真实文件清单实测过:10 个放行零误伤, 1024XEngineer#126 拦下 8 项,另发现两个 PR 把 _PR说明.md 提进了仓库根目录。 Refs 1024XEngineer#137 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub. |
|
回填「待对齐」第 3 条：新加的 workflow 在本 PR 上确实触发了，而且通过。 所以 顺带这也是门禁的第一个真实样本：它对一个新增 |
![fennoai[bot]](https://avatars.githubusercontent.com/in/1924301?s=60&v=4){kind=small}
|
|
||
| ### 2.3 分支落后 base → 会夹带、会重复报同一个 bug | ||
|
|
||
| **判据**：`git fetch origin && git log --oneline HEAD..origin/main | head` 有输出 = 落后。 |
There was a problem hiding this comment.
This freshness check conflicts with the fork workflow described just above. Section 2.2 says contributors should work from their own fork and treats pushing to 1024XEngineer/Windup as wrong; in that setup origin/main is normally the contributor fork's main, not the upstream base branch. If the fork's main is stale, this command can report no lag and git rebase origin/main will not update against the real base, which is exactly the stale-base problem this section is trying to prevent. Please either define the expected remotes explicitly or use the upstream remote consistently here, matching the later gate message that tells users to rebase on upstream/main.
There was a problem hiding this comment.
CONTRIBUTING.md 一般放的是给人看的贡献文档，这里明显的混乱了。
agent相关的文档放到如 .agents, .claude 或者 CLAUDE.md, AGENTS.md 中。
There was a problem hiding this comment.
这里看起来只是给 claude 添加了 skill，缺少其他 agents 的专属目录；
常用的做法是添加一个 .agents 目录（因为绝大多数的 agents 遵循该规范），其余的特殊情况比如 claude 可以通过软连接的方式实现。
|
四条意见都成立，关闭本 PR。
@fennoai 指出的矛盾属实：§2.3 用 后续如重做： |
DoneClosing PR #138 per request. |
2 participants
变更内容
把「工程文档不入仓」这条规范落进仓库，并给它一个机器兜底。四个新增文件，不改任何已有文件、不碰代码：
CONTRIBUTING.md.github/workflows/docs-gate.yml.github/pull_request_template.md.claude/skills/windup-contrib/SKILL.md配套已建好 label
user-doc（门禁豁免开关）。关联
Refs #137
为什么这么做
规范此前只存在于营规范原文和群消息里，仓库内没有落点。没有落点的规范只能靠记性，新加入的人和各种 AI agent 都读不到。
它已经在真实失效：#128 于 08-06 02:35 删掉
docs/module-split.md（说明「内容已迁到 Issue」），#126 又把它改了回来并新增 6 份工程文档。这不是谁不小心——改动一大，md 就藏在两百多个文件里没人会专门去看。几个决策点的取舍
规范放
CONTRIBUTING.md而不是 Issue。 备选是放 Issue（符合「工程文档进 Issue」的字面）。选前者的理由：那条规则针对的是会分叉的设计描述——文档进仓后代码继续演进而 md 不动。贡献规范正相反，它必须和 CI 配置、目录结构一起演进；改了naming.yml的正则却没同步规范，这个不一致应该在同一个 PR 的 diff 里被看见。放 Issue 反而制造分叉。另外它是 GitHub 原生识别的文件，开 PR 时会自动提示。门禁宁可漏拦不可误拦。 备选是严格拦所有新增 md。选保守版的理由很直接：误伤别人正常工作的门禁会被直接关掉，那还不如没有。所以它只管
docs/**和根目录新增 md；删除、子目录 README/MODULES.md、允许清单、打了user-doc的 PR 一律放行。豁免 label 用新建的
user-doc，不复用Documented。 后者是打在 Issue 上的生命周期状态（用户文档已提供），借来当 PR 门禁开关会把两套语义搅在一起。先不设 required check。 建议跑两周看误伤率再谈——现在设 required，下面那类陈旧 base 的 PR 会被直接卡死。
本地验证
pyyaml.safe_load，jobs:['check-docs']）run:脚本抽出跑bash -n）4246389切出）.py/.ts/ 依赖与 lock 改动，不受影响act本地跑 workflow门禁逻辑拿全部 15 个 open PR 的真实文件清单实测过（从 API 取
status + filename，喂给复刻的判定逻辑）：_PR说明.md加到了仓库根目录另跑了 label 豁免、
docs/user/放行、删除放行、目录内重命名等边界用例。#74 / #72 是假警报，机制值得说明：它们「新增」
frontend-architecture-v3.md，而那文件 main 上早就有——是分支落后让 merge-base 把老文件算成了新增，rebase 后自动消失。门禁的报错信息里已写明这一点并给出 rebase 命令，把假警报转成「你该 rebase 了」的有用信号。本 PR 自身过门禁：PASS（
CONTRIBUTING.md与.github/**、.claude/**都在允许清单内，不需要豁免 label）。待对齐 / 已知未决
CONTRIBUTING.md2.1 把当前口径写成「记录结论可以入仓（一两行 + Issue 链接），记录论证过程进 Issue」，门禁据此故意不拦子目录 md。请评审时确认或修正这个口径，我按结论改。frontend-architecture-v3.md属同类问题，处理它要单独开 PR。feat(generation): add validated SSE task adapter #110 / feat(media): add validated upload adapter #111 的_PR说明.md请各自作者决定。pull_request事件应当从 merge ref 生效，但我没有在真实 runner 上验证过。如果它这次没触发，合并后在下一个 PR 上才会生效——不影响本 PR 的评审。