Generative AI for Beginners 贡献指南CLA、PR 规范与四条 Markdown 校验工作流的完整实践【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners本文基于本仓库的 translations/ar/CONTRIBUTING.md根目录 CONTRIBUTING.md 的阿拉伯语译文展开系统讲解向 generative-ai-for-beginners 仓库提交贡献的完整流程从 CLA 协议、Issue 使用边界、PR 拆分约定到 Markdown 链接的 7 条写作规则和 4 条自动化校验工作流。读完本文你将掌握如何一次性通过本仓库的 CI 检查并理解每条规则背后在 .github/workflows/validate-markdown.yml 中的真实实现。一、提交贡献前的三件事CLA、行为准则与 Issue 边界1.1 签署贡献者许可协议CLA本项目欢迎一切贡献与建议。按照文档说明大多数贡献要求你同意贡献者许可协议Contributor License Agreement, CLA声明你有权、并且实际上确实授权项目方使用你的贡献。CLA 的官方页面是 cla.microsoft.com纯文本域名请在浏览器中自行访问。提交流程上有两个关键行为值得注意当你提交 Pull Request 时CLA-bot 会自动判断你是否需要提供 CLA并相应地装饰你的 PR例如添加标签、发表评论只需按机器人给出的说明操作即可CLA 只需签署一次且对所有使用同一份 CLA 的仓库生效。1.2 行为准则本项目采用微软开源行为准则Microsoft Open Source Code of Conduct。仓库根目录的 CODE_OF_CONDUCT.md 列出了准则原文、FAQ 入口以及联系邮箱 opencodemicrosoft.com任何额外的问题或反馈都可以通过该渠道提出。1.3 关于翻译的重要警示文档中有一条加粗提示翻译本仓库内容时请勿使用机器翻译。项目方会通过社区验证译文质量因此只建议你在自己精通的语言上志愿参与翻译。这一点在 translations/ar/CONTRIBUTING.md 文档末尾的免责声明中得到了呼应该阿拉伯语文档本身即由机器翻译服务 Co-op TranslatorAzure 开源的协同翻译工具生成文档明确声明“应以其原始语言版本作为权威来源重要信息建议采用人工专业翻译”。也就是说本仓库 40 余个语言目录translations/下 40 多个子目录每个目录 40 个 Markdown 文件加 28 个 Notebook中的译文均需经过社区人工校对才能算数。1.4 Issue 不是问答区文档明确不要用 GitHub Issue 提出一般性的支持问题因为 Issue 列表只应用于功能请求feature requests和缺陷报告bug reports。这样维护者才能更轻松地追踪代码中真实存在的问题并把泛泛的讨论与实际代码工作分开。仓库中的 .github/ISSUE_TEMPLATE/bug_report.md 与 .github/ISSUE_TEMPLATE/feature_request.md 就是这两类提交的固定入口。二、PR 提交约定五条硬性规则文档“Typos, Issues, Bugs and contributions”一节给出了提交任何更改前必须遵守的五条建议完整继承如下先 fork 再改在进行任何修改之前始终先把仓库 fork 到你自己的账号下一个 PR 只含一类变更不要把多个变更合并进同一个 PR。例如缺陷修复和文档更新应分别提交独立的 PR合并冲突先同步主干如果你的 PR 显示合并冲突在动手修改前务必先把本地 main 分支更新为主仓库 main 的镜像mirror翻译必须整包提交如果你提交的是翻译请把所有翻译文件放在同一个 PR 中——项目方不接受内容的部分翻译partial translations拼写与文档修正可以合并如果你提交的是拼写错误或文档修正在合适的情况下可以把多处修改合并进同一个 PR。从源码结构看PR 提交后会触发 .github/workflows/welcome-pr.yml该工作流在 PR 打开时自动添加needs-review标签、回复一条感谢评论并将 PR 自动指派给维护者。因此按上述规则提交规范 PR能显著降低后续人工沟通成本。三、Markdown 写作规则7 条链接与图片硬性要求文档“General Guidance for writing”一节定义了本仓库的写作规范。由于仓库整体部署为 GitHub Pages 站点链接的准确性与可追踪性被当作硬性约束。以下 7 条规则需逐条满足#规则具体写法1URL 必须使用标准 Markdown 链接语法方括号后紧跟圆括号中间和内部都不能有多余空格[](../..)2相对链接必须以./或../开头./指当前工作目录下的文件/文件夹../指父级工作目录下的文件/文件夹3相对链接末尾必须带追踪 ID以?或开头后接wt.mc_id或WT.mc_id4特定域名的 URL 必须带追踪 ID域名属于 github.com、microsoft.com、visualstudio.com、aka.ms、azure.com 之一时URL 末尾同样需追加?wt.mc_id或WT.mc_id5链接中不得包含国家/地区语言设置例如不能出现/en-us/或/en/这类路径段6图片统一存放于./images目录不允许散落在各课程目录之外7图片命名必须描述性且仅用英文字符名称中使用英文字母、数字和连字符dash例如vscode-follow-link第 24 条实际上回答了“为什么要这么写”仓库作为静态页面发布后相对路径拼错会把读者导向错误位置而追踪 IDwt.mc_id用于统计流量来源。这两点也正是下面四条 CI 工作流要校验的内容。一个值得注意的细节阿拉伯语版 translations/ar/CONTRIBUTING.md 第 4851 行的四个目录链接被翻译成了占位符../..属于典型的“断链”。不过按 validate-markdown.yml 的触发配置见 4.5 节translations/**目录被整体排除在校验之外因此这类问题不会触发 CI 报错仍需人工校对时发现。四、四条 Markdown 校验工作流检查规则、报错形态与修复方法当你提交 PR 时文档承诺会触发四条工作流来校验上述规则。下面逐条给出文档中的检查目的、快速自检方法和标准修复动作并配仓库内的真实报错截图阿拉伯语本地化版本。4.1 Check Broken Relative Paths相对路径断链检查目的确保文件中的任何相对路径都能真正跳转成功。仓库部署在 GitHub Pages 上把各页“粘”在一起的链接一旦写错就会把读者带到错误的地方。自检方法文档推荐直接用 VS Code 验证——把鼠标悬停在文件中的任意链接上按Ctrl Click跟随链接如果某个链接在本地都点不通那么它一定会让工作流失败上线后同样不可用。修复方法让 VS Code 帮你补全路径。当你输入./或../时VS Code 会弹出一个按前缀过滤的候选列表点击目标文件或文件夹即可保证路径完整有效。修改完成、保存并推送后工作流会再次运行验证你的改动通过检查即可继续。4.2 Check Paths Have Tracking相对路径追踪 ID 检查目的确保任何相对路径都带有追踪 ID因为仓库部署在 GitHub Pages 上需要统计文件与文件夹之间的跳转行为。自检方法检查相对路径末尾是否存在?wt.mc_id文本。存在则通过否则可能收到如下错误修复方法打开工作流标出的文件路径把追踪 ID 追加到相对路径末尾保存并推送。工作流会重新运行通过即可继续。4.3 Check URLs Have TrackingURL 追踪 ID 检查目的确保任何 Web URL 都带追踪 ID。本仓库面向全球所有人开放需要通过追踪了解流量来源。自检方法检查 URL 末尾是否存在?wt.mc_id对应写作规则第 4 条列出的 github.com、microsoft.com、visualstudio.com、aka.ms、azure.com 五个域名。缺失时会看到类似下面的报错修复方法打开工作流标出的文件把追踪 ID 追加到 URL 末尾保存并推送等待工作流复检通过。4.4 Check URLs Dont Have LocaleURL 语言设置检查目的确保任何 Web URL 都不包含国家/地区语言设置。仓库面向全球读者你的链接不应把读者锁定在你的国家语言版本上。自检方法检查 URL 的任何位置是否出现/en-us/、/en/或其他语言 locale 路径段。不存在则通过检查存在则工作流会给出标注 locale 的报错评论。修复方法打开工作流标出的文件从 URL 中删掉国家 locale 路径段保存并推送等待复检通过。文档在四条检查之后写道“恭喜我们会尽快就你的贡献给出反馈。”4.5 源码印证这些检查在 validate-markdown.yml 中如何落地对照 .github/workflows/validate-markdown.yml 可以确认上述流程的真实实现并发现几个文档未展开的细节触发条件第 112 行仅在向main分支提交pull_request且改动路径匹配**.md或**.ipynb时触发并且用负向 path 过滤显式排除了translations/**与translated_images/**两个目录——这解释了为何阿拉伯语等 40 余个译本的 Markdown 不参与这四条检查。权限声明为contents: read与pull-requests: write后者用于工作流向 PR 回写评论。任务链与执行器任务名文档对应章节执行器源码确认check-broken-paths4.1john0isaac/action-check-markdownv1.3.1命令check_broken_pathscheck-paths-tracking4.2同上命令check_paths_trackingcheck-urls-tracking4.3Python 包markdown-checker命令markdown-checker -f check_urls_tracking且仅对本次 PR 中git diff出的已变更 Markdown/Notebook 文件执行第 4975 行check-urls-locale4.4action-check-markdown命令check_urls_localecheck-broken-urls文档未单列并行运行的第五个任务命令check_broken_urls第 92106 行从源码结构看四个主任务通过needs形成串行依赖链check-broken-paths → check-paths-tracking → check-urls-tracking → check-urls-locale每一环都带有if: ${{ always() }}即前序任务失败后仍会继续执行后续检查从而一次推送就能收集齐所有违规点check-broken-urls 则不带needs与前序任务并行。此外每个任务都通过guide-url参数指向 CONTRIBUTING.md 的仓库页面因此工作流在 PR 上留下的失败评论会直接附带上文写作规范链接供贡献者对照自查——这与文档“请按这里的说明通过检查”的表述完全吻合。五、提交代码时还会触发什么如果你提交的不只是文档而是课程配套代码Python / JavaScript / TypeScript还会触发 .github/workflows/code-quality.yml。从该文件可见shared/共享工具模块是强制保持整洁的Ruff lint 加 Black 格式检查失败即阻断并对全仓库运行 advisory 级 Rufftests/下的 pytest 用例pytest openai requests python-dotenvPython 3.11 环境必须通过而全仓库 ESLint 检查以 advisory 模式运行continue-on-error: true注释说明教学示例代码不强制严格 lint。结合第二节的“一个 PR 只含一类变更”约定文档改动走 Markdown 校验链代码改动叠加代码质量与测试两者互不干扰。六、快速核对表提交 PR 前可以按这张表做最后一遍自查检查项检查对象自检方法修复动作Broken Relative Paths相对路径可达性VS Code 中 CtrlClick 逐个跟随输入./、../用补全列表选择用 VS Code 补全后重新推送Paths Have Tracking相对路径末尾是否存在?wt.mc_id追加追踪 ID 后重新推送URLs Have Tracking五大域名 URL 末尾是否存在?wt.mc_id/WT.mc_id追加追踪 ID 后重新推送URLs Dont Have LocaleURL 任意位置是否含/en-us/、/en/等 locale 段删除 locale 段后重新推送拼写与文档修正合并进单个 PR—按 PR 约定提交翻译全部文件同一 PR、无机器翻译—补全文件后重新推送按 CONTRIBUTING.md或其各语言译文完成以上准备后提交 PRCLA-bot 会处理协议状态welcome 工作流会打上needs-review标签并自动指派维护者Markdown 校验链会给出可直接对照修复的评论。规则虽多但每一条都对应一条明确的自检方法照做即可一次通过。【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考