generative-ai-for-beginners 贡献指南全解：PR 规范、链接追踪规则与 Markdown 自动化校验工作流

2026-09-04 10:54:15作者：柏廷章Berta

本文基于 CONTRIBUTING.md 系统讲解 generative-ai-for-beginners（21 课生成式 AI 入门课程）仓库的社区贡献规范：从 CLA 签署、翻译政策、Pull Request 拆分原则，到文档撰写的链接与图片硬性规则，并结合 .github/workflows/validate-markdown.yml 的源码实现，逐条解析四个（实际配置了五个）Markdown 自动校验工作流的触发条件、判定逻辑与修复方法，帮助你在提交 PR 前就能让检查一次通过。

一、贡献前的准入要求：CLA 与翻译政策

1. 贡献者许可协议（CLA）

CONTRIBUTING.md 开篇说明：本项目欢迎各类贡献与建议，但大多数贡献要求签署贡献者许可协议（Contributor License Agreement，CLA），以声明你有权、并且确实愿意授予项目方使用你贡献的权利。其核心流程是：

提交 Pull Request 时，CLA-bot 会自动判断你是否需要签署 CLA，并给 PR 打上相应的标签或评论（decorate the PR appropriately）；
只需按机器人给出的提示操作即可，且该 CLA 在采用同一 CLA 的所有仓库间只需签署一次，后续提交无需重复。

因此新贡献者的第一步通常是：发起任意 PR，等待 CLA-bot 的评论指引，完成签署后再等待正式评审。

2. 翻译的硬性政策

文档用醒目引用块强调了一条翻译红线：

翻译本仓库内容时，禁止使用机器翻译。翻译质量会经由社区核验，因此请只在你熟练掌握的语言上认领翻译任务。

这与仓库中 translations/ 下 40 余种语言的目录结构相互印证——多语言版本的内容完整性与质量直接决定该语言版本的可用性。

二、Pull Request 提交规范

CONTRIBUTING.md 中“Typos, Issues, Bugs and contributions”一节给出了五条可操作的 PR 规则，逐条说明如下：

规则	说明
先 fork 再修改	修改前必须先把仓库 fork 到自己的账号下，避免直接对上游 main 分支产生冲突历史
一个 PR 只做一类变更	例如 bug 修复与文档更新必须拆成两个独立 PR，便于评审与回滚
合并冲突先同步 main	若 PR 出现 merge conflict，需先把本地 main 更新为上游 main 的镜像，再叠加自己的修改
翻译整包提交	翻译类 PR 必须一次性包含该语言的全部翻译文件，不接受内容部分翻译的 PR
小修可合并	错别字或纯文档修正，适合时可合并进同一个 PR

此外，文档还明确了 Issue 的使用边界：通用支持类问题（Question）不要开 Issue，Issue 列表只用于功能请求与 bug 报告，以便把“代码真实缺陷”和“一般性讨论”分开追踪。仓库也为此提供了现成模板：.github/ISSUE_TEMPLATE/bug_report.md 要求给出 bug 描述、复现步骤、期望行为与截图；.github/ISSUE_TEMPLATE/feature_request.md 则要求说明问题背景、期望方案与已考虑的替代方案。

三、文档撰写规范：链接与图片的六条硬性规则

CONTRIBUTING.md 的“General Guidance for writing”部分列出了六条会被工作流机器检查的写作规则，是本文最重要的实战要点：

URL 格式：所有 URL 必须包裹在方括号加圆括号中，且括号内外不得有多余空格，形如 text；
相对路径写法：指向仓库内其他文件/文件夹的相对链接，必须以 ./（当前工作目录）或 ../（父级目录）开头；
相对路径必须带追踪参数：相对链接末尾必须附加追踪 ID，即 ? 或 & 之后跟 wt.mc_id= 或 WT.mc_id=；
指定域名的外部 URL 必须带追踪参数：来自 github.com、microsoft.com、visualstudio.com、aka.ms、azure.com 五个域名的 URL，末尾同样要追加 wt.mc_id= 或 WT.mc_id=；
URL 不得包含国家地区语言码：链接中不能出现 /en-us/、/en/ 等区域性 locale 路径段；
图片统一存放与命名：所有图片必须放在 ./images 文件夹内，且文件名只使用英文字符、数字和连字符（dash），例如 vscode-follow-link.png。

从仓库现状看，这些规则并非纸面要求：README.md 首行封面图即写作 ./images/repo-thumbnailv4-fixed.png?WT.mc_id=academic-105485-koreyst，各课程 README 中的图片引用也普遍携带 WT.mc_id=academic-105485-koreyst 追踪参数，正是上述规则在真实内容中的落地形态。追踪参数的作用在于：该仓库通过 GitHub Pages 对全球读者开放，需要在页面间跳转与外部流量来源上留下可统计的路径标记。

四、四个 Markdown 校验工作流的源码级解析

CONTRIBUTING.md 声明：每次提交 PR 会触发四个工作流来校验上述规则。对应实现全部集中在 .github/workflows/validate-markdown.yml 中。

4.0 触发条件、权限与任务编排

从工作流配置看（.github/workflows/validate-markdown.yml#L3-L16）：

触发条件：pull_request 事件且目标分支为 main，路径限定为 **.md 与 **.ipynb，同时用 !translations/** 与 !translated_images/** 排除翻译目录——这意味着只有英文源内容的 Markdown 与 Notebook 变更会触发校验，各语言译文不参与；
权限：contents: read 与 pull-requests: write（写权限用于把检查结果以评论形式贴回 PR）；
任务链：check-broken-paths → check-paths-tracking → check-urls-tracking → check-urls-locale 四个 job 通过 needs 串行依赖、并用 if: ${{ always() }} 保证即使前序失败也会继续输出诊断信息；
引导文档：每个 job 都通过 guide-url 参数指向 CONTRIBUTING.md 的 blob 页面，失败时机器人评论会引导贡献者回到本规范查阅修复方法。

值得注意的是，从源码结构看该文件实际还配置了第五个 job check-broken-urls（.github/workflows/validate-markdown.yml#L92-L106），用于检测失效的外部 URL，但它不与 CONTRIBUTING.md 列出的四个检查构成串行链，属于补充性的独立检查。

4.1 Check Broken Relative Paths：相对路径不能是死链

该检查确保文件中的相对路径真实可达。文档解释其动机：仓库部署在 GitHub Pages 上，错误的链接会把读者带到错误位置。

实现：调用 john0isaac/action-check-markdown@v1.3.1，command 取值为 check_broken_paths，对根目录做全量扫描（.github/workflows/validate-markdown.yml#L23-L32）。

文档给出的修复方法（可直接照做）：

在 VS Code 中悬停任意链接，按 Ctrl + Click 尝试跟随；如果本地都打不开，工作流必然失败；
让编辑器帮你补全路径：输入 ./ 或 ../ 时，VS Code 会按已输入内容弹出可选文件/文件夹列表，从候选项中点选目标即可保证路径正确；
修正后保存并推送，工作流会重新触发验证。

4.2 Check Paths Have Tracking：相对路径必须携带追踪参数

该检查确保每个相对路径末尾带有 ?wt.mc_id=（或 WT.mc_id=）追踪参数，动机同样是页面部署后的路径间移动统计。

实现：同一 action 的 check_paths_tracking 命令（.github/workflows/validate-markdown.yml#L41-L48）。

修复方法：打开工作流高亮指出的文件，在对应相对路径末尾补上追踪参数，例如把指向同级文件的链接写成带 ?wt.mc_id= 的形式，然后保存、推送，等待工作流复检通过。

4.3 Check URLs Have Tracking：外部 URL 必须携带追踪参数

该检查面向仓库公开给所有人的流量溯源需求：github.com、microsoft.com 等指定域名的 URL 末尾必须追加 ?wt.mc_id= 或 WT.mc_id=。

实现上有两处源码细节值得注意（.github/workflows/validate-markdown.yml#L59-L75）：

该 job 使用 fetch-depth: 0 拉取完整历史，再用 git diff --name-only --diff-filter=ACMR <base>...<head> 计算本 PR 相对基线分支新增/修改的 **.md、**.ipynb 文件（排除 translations/** 与 translated_images/**）；
随后 pip install markdown-checker 并对变更文件清单逐一执行 markdown-checker -f check_urls_tracking——也就是说 URL 追踪检查只针对你本次改动的文件，而非全仓库。

修复方法与 4.2 相同：定位工作流高亮的文件，在对应 URL 末尾补上追踪参数后重新推送。

4.4 Check URLs Don't Have Locale：URL 不得包含地区语言码

该检查确保 URL 中不出现 /en-us/、/en/ 等任何国家/地区语言码，保证全球读者访问到的是无地域绑定的页面。

实现：同一 action 的 check_urls_locale 命令（.github/workflows/validate-markdown.yml#L81-L91）。

修复方法：打开被高亮的文件，从 URL 中删除 locale 路径段后重新推送即可。

四个检查全部通过、且 check-broken-urls 无失效外链，即完成了 CONTRIBUTING.md 所说的全部自动化校验；随后仓库维护者会尽快回复评审反馈。

五、配套的仓库治理工作流（补充上下文）

理解 CONTRIBUTING.md 之外，仓库 .github/workflows/ 下还有一组与贡献流程直接相关的自动化，可帮助贡献者预知 PR 提交后的完整经历：

welcome-pr.yml：PR 创建时自动加 needs-review 标签、发送感谢评论，并通过 pozil/auto-assign-issue@v4 自动指派评审人；
stale.yml：每天定时扫描，issue/PR 30 天无活动打 stale 标签、再过 7 天关闭（可随时重开），长期无人跟进的 PR 需注意及时响应评审；
lock.yml：issue 关闭后自动上锁，防止已关闭讨论继续被回复；
code-quality.yml：当 PR 触及 **.py、**.ts、**.js 时触发，对 shared/ 共享工具模块执行强制性的 ruff + black 检查与 pytest（Python 3.11 环境），对教学示例代码则是建议性的 lint，不会让构建失败；
security.yml 与 dependabot.yml：CodeQL 静态分析（javascript-typescript 与 python 两个矩阵）加每周定时扫描，PR 上运行 Dependency Review，dependabot 对 pip/npm/github-actions 三个生态做每周依赖更新。

六、提交前自查清单

综合 CONTRIBUTING.md 与工作流源码，提交 PR 前可按以下顺序自查：

是否已完成 CLA（首次贡献者）；翻译是否全部完成且非机翻；
PR 是否单一主题，无合并冲突，本地 main 与上游同步；
所有链接格式是否为 text 且括号内外无空格；
相对路径是否以 ./ 或 ../ 开头、末尾带 wt.mc_id=/WT.mc_id=，并已在 VS Code 中 Ctrl+Click 验证可达；
github.com 等五个域名的 URL 末尾是否带追踪参数；
URL 中是否已剔除 /en-us/、/en/ 等地区语言码；
新增图片是否位于 ./images 且文件名仅含英文、数字与连字符；
若改动代码文件，确认 shared/ 模块通过 ruff/black/pytest 约束。