generative-ai-for-beginners 贡献指南全解PR 规范、链接追踪规则与 Markdown 自动化校验工作流【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners本文基于 CONTRIBUTING.md 系统讲解 generative-ai-for-beginners21 课生成式 AI 入门课程仓库的社区贡献规范从 CLA 签署、翻译政策、Pull Request 拆分原则到文档撰写的链接与图片硬性规则并结合 .github/workflows/validate-markdown.yml 的源码实现逐条解析四个实际配置了五个Markdown 自动校验工作流的触发条件、判定逻辑与修复方法帮助你在提交 PR 前就能让检查一次通过。一、贡献前的准入要求CLA 与翻译政策1. 贡献者许可协议CLACONTRIBUTING.md 开篇说明本项目欢迎各类贡献与建议但大多数贡献要求签署贡献者许可协议Contributor License AgreementCLA以声明你有权、并且确实愿意授予项目方使用你贡献的权利。其核心流程是提交 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不要开 IssueIssue 列表只用于功能请求与 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_idURL 不得包含国家地区语言码链接中不能出现/en-us/、/en/等区域性 locale 路径段图片统一存放与命名所有图片必须放在./images文件夹内且文件名只使用英文字符、数字和连字符dash例如vscode-follow-link.png。从仓库现状看这些规则并非纸面要求README.md 首行封面图即写作./images/repo-thumbnailv4-fixed.png?WT.mc_idacademic-105485-koreyst各课程 README 中的图片引用也普遍携带WT.mc_idacademic-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 页面失败时机器人评论会引导贡献者回到本规范查阅修复方法。值得注意的是从源码结构看该文件实际还配置了第五个 jobcheck-broken-urls.github/workflows/validate-markdown.yml#L92-L106用于检测失效的外部 URL但它不与 CONTRIBUTING.md 列出的四个检查构成串行链属于补充性的独立检查。4.1 Check Broken Relative Paths相对路径不能是死链该检查确保文件中的相对路径真实可达。文档解释其动机仓库部署在 GitHub Pages 上错误的链接会把读者带到错误位置。实现调用john0isaac/action-check-markdownv1.3.1command取值为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-filterACMR 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 Dont Have LocaleURL 不得包含地区语言码该检查确保 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.ymlPR 创建时自动加needs-review标签、发送感谢评论并通过pozil/auto-assign-issuev4自动指派评审人stale.yml每天定时扫描issue/PR 30 天无活动打 stale 标签、再过 7 天关闭可随时重开长期无人跟进的 PR 需注意及时响应评审lock.ymlissue 关闭后自动上锁防止已关闭讨论继续被回复code-quality.yml当 PR 触及**.py、**.ts、**.js时触发对shared/共享工具模块执行强制性的 ruff black 检查与 pytestPython 3.11 环境对教学示例代码则是建议性的 lint不会让构建失败security.yml与dependabot.ymlCodeQL 静态分析javascript-typescript 与 python 两个矩阵加每周定时扫描PR 上运行 Dependency Reviewdependabot 对 pip/npm/github-actions 三个生态做每周依赖更新。六、提交前自查清单综合 CONTRIBUTING.md 与工作流源码提交 PR 前可按以下顺序自查是否已完成 CLA首次贡献者翻译是否全部完成且非机翻PR 是否单一主题无合并冲突本地 main 与上游同步所有链接格式是否为text且括号内外无空格相对路径是否以./或../开头、末尾带wt.mc_id/WT.mc_id并已在 VS Code 中 CtrlClick 验证可达github.com 等五个域名的 URL 末尾是否带追踪参数URL 中是否已剔除/en-us/、/en/等地区语言码新增图片是否位于./images且文件名仅含英文、数字与连字符若改动代码文件确认shared/模块通过 ruff/black/pytest 约束。满足以上条件validate-markdown 工作流的四项检查外加 broken URLs 检查即可顺利放行你的贡献将进入人工评审环节。【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
generative-ai-for-beginners 贡献指南全解PR 规范、链接追踪规则与 Markdown 自动化校验工作流【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners本文基于 CONTRIBUTING.md 系统讲解 generative-ai-for-beginners21 课生成式 AI 入门课程仓库的社区贡献规范从 CLA 签署、翻译政策、Pull Request 拆分原则到文档撰写的链接与图片硬性规则并结合 .github/workflows/validate-markdown.yml 的源码实现逐条解析四个实际配置了五个Markdown 自动校验工作流的触发条件、判定逻辑与修复方法帮助你在提交 PR 前就能让检查一次通过。一、贡献前的准入要求CLA 与翻译政策1. 贡献者许可协议CLACONTRIBUTING.md 开篇说明本项目欢迎各类贡献与建议但大多数贡献要求签署贡献者许可协议Contributor License AgreementCLA以声明你有权、并且确实愿意授予项目方使用你贡献的权利。其核心流程是提交 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不要开 IssueIssue 列表只用于功能请求与 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_idURL 不得包含国家地区语言码链接中不能出现/en-us/、/en/等区域性 locale 路径段图片统一存放与命名所有图片必须放在./images文件夹内且文件名只使用英文字符、数字和连字符dash例如vscode-follow-link.png。从仓库现状看这些规则并非纸面要求README.md 首行封面图即写作./images/repo-thumbnailv4-fixed.png?WT.mc_idacademic-105485-koreyst各课程 README 中的图片引用也普遍携带WT.mc_idacademic-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 页面失败时机器人评论会引导贡献者回到本规范查阅修复方法。值得注意的是从源码结构看该文件实际还配置了第五个 jobcheck-broken-urls.github/workflows/validate-markdown.yml#L92-L106用于检测失效的外部 URL但它不与 CONTRIBUTING.md 列出的四个检查构成串行链属于补充性的独立检查。4.1 Check Broken Relative Paths相对路径不能是死链该检查确保文件中的相对路径真实可达。文档解释其动机仓库部署在 GitHub Pages 上错误的链接会把读者带到错误位置。实现调用john0isaac/action-check-markdownv1.3.1command取值为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-filterACMR 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 Dont Have LocaleURL 不得包含地区语言码该检查确保 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.ymlPR 创建时自动加needs-review标签、发送感谢评论并通过pozil/auto-assign-issuev4自动指派评审人stale.yml每天定时扫描issue/PR 30 天无活动打 stale 标签、再过 7 天关闭可随时重开长期无人跟进的 PR 需注意及时响应评审lock.ymlissue 关闭后自动上锁防止已关闭讨论继续被回复code-quality.yml当 PR 触及**.py、**.ts、**.js时触发对shared/共享工具模块执行强制性的 ruff black 检查与 pytestPython 3.11 环境对教学示例代码则是建议性的 lint不会让构建失败security.yml与dependabot.ymlCodeQL 静态分析javascript-typescript 与 python 两个矩阵加每周定时扫描PR 上运行 Dependency Reviewdependabot 对 pip/npm/github-actions 三个生态做每周依赖更新。六、提交前自查清单综合 CONTRIBUTING.md 与工作流源码提交 PR 前可按以下顺序自查是否已完成 CLA首次贡献者翻译是否全部完成且非机翻PR 是否单一主题无合并冲突本地 main 与上游同步所有链接格式是否为text且括号内外无空格相对路径是否以./或../开头、末尾带wt.mc_id/WT.mc_id并已在 VS Code 中 CtrlClick 验证可达github.com 等五个域名的 URL 末尾是否带追踪参数URL 中是否已剔除/en-us/、/en/等地区语言码新增图片是否位于./images且文件名仅含英文、数字与连字符若改动代码文件确认shared/模块通过 ruff/black/pytest 约束。满足以上条件validate-markdown 工作流的四项检查外加 broken URLs 检查即可顺利放行你的贡献将进入人工评审环节。【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
