★ FEATURED ARTICLE 文档教程【免费下载链接】project-based-learningCurated list of project-based tutorials项目地址https://gitcode.com/GitHub_Trending/pr/project-based-learning点击查看免费下载CONTRIBUTING.md 是 project-based-learning 仓库唯一的贡献入口文档它定义了向这份项目制教程清单提交内容的全套规则提交前必须逐条核对的质量清单、README 条目的标准格式、多部分系列的组织方式以及提交 PR 前必须在本地跑通的校验命令。本文以该文档为主线结合仓库内 scripts/check_readme.py约 1178 行的 README 解析器与链接巡检器的源码实现逐条解读每条规则背后的自动化逻辑、错误码含义与 CI 行为帮助你写出的每个 Pull Request 都能一次通过校验并理解某些链接显示 could not verify为何是预期现象而非构建失败。仓库定位与贡献入口project-based-learning 的核心载体是根目录下的 README.md一份按主语言分节组织的编程教程清单收录标准是读者跟随教程从零构建出一个完整、可运行的应用README 原文a list of programming tutorials in which aspiring software developers learn how to build an application from scratch, divided into different primary programming languages。因此它的代码资产本质上就是 README 这份数据文件而 CONTRIBUTING.md 就是维护这份数据的操作手册。贡献流程的第一步是 fork 仓库README.md 明确要求To get started, simply fork this repo随后所有改动以 Pull Request 形式提交并严格遵循 CONTRIBUTING.md 中的约定。提交 PR 前的质量清单十四条规则全解读CONTRIBUTING.md 在Before making a pull request下列出了一整套检查项。这些规则可以分为五组查重与定位、内容准入、作者与 PR 管理、条目格式、文字与链接卫生。查重与定位规则 1–2先查重想要添加的教程不能已经存在——需要在 README.md 中同时搜索其URL和标题。这条规则在源码层面有对应的自动化实现详见下文重复 URL 的判定与白名单机制解析器会对每个条目的 URL 做归一化去重命中重复会触发 E005 错误但标题查重属于人工核对项因为解析器只能解析结构无法判断语义重复。归位正确教程必须放在合适的语言/技术章节下。README.md 以##二级标题划分主语言C#、C/C、Clojure、Dart、Elixir、Erlang、F#、Go、Haskell、HTML/CSS、Java、JavaScript、Kotlin、Lua、OCaml、PHP、Python、R、Ruby、Rust、Scala、Swift外加 Additional Resources部分语言内部还有###三级子节如 C/C 下的 Network programming、OpenGLJavaScript 下的 React、Next.js、Angular、Node、Vue 等。解析器会记录每条条目所属的 section链接巡检报告也会按 section 汇总归位错误会直接造成后续巡检报告的可读性下降。内容准入标准规则 3–4免费开放教程必须免费且开放——不能有付费墙paywall、登录墙login wall或强制订阅 newsletter。这是一条人工评审项自动化工具无法探测页面背后的付费逻辑这正是 CI 中某些站点显示 could not verify 而不是构建失败的背景详见下文 CI 链接巡检一节。项目制教程必须是 project-based 的——读者跟随教程能构建出完整、可运行的作品而非单纯的概念讲解。这是本清单的收录哲学也是 README.md 对整份清单的定义性标准。是否构建出完整作品需要人工判断机器只负责校验条目结构。作者披露与 PR 管理规则 5–8作者披露如果你是教程作者、或与作者/网站有关联必须在 PR 中明示。这是社区透明度要求避免清单被变相用于推广。描述性标题PR 必须有一个能描述改动内容的标题descriptive title。新语言可开新章节如果教程的语言/技术栈在清单中尚不存在可以在目录Table of Contents中新建条目。注意这条与 ToC 锚点校验直接相关——新增##章节后必须同步在 ToC 中登记否则校验器会报 E003/E004详见下文。一个 PR 只放一个教程每个教程单独一个 Pull Request。从源码结构看这一约定与 check-diff 子命令 的设计互相呼应——CI 的 diff 检查只针对本次新增的行做语法与 URL 校验粒度越小评审和自动检查就越聚焦。条目格式与多部分系列规则 9–10单条教程使用以下精确格式- Title如果教程是多部分系列multi-part series必须使用缩进嵌套格式- Title - Part 1 - Part 2这两个格式不是随便约定的——它们是 check_readme.py 中正则文法的一部分详见下一节。系列标题行本身没有链接但必须有比它更深一级缩进的子条目否则会触发 E002 错误。文字与链接卫生规则 11–13检查拼写与语法人工检查项校验器不检查英文拼写。去除行尾空白样式约定解析器的正则在语法上容忍行尾空白例如HEADER_RE的\s*$但清单要求保持文件整洁。链接直指教程本体禁用短链链接必须直接指向教程页面禁止使用 URL 缩短服务。这一条在源码中有强校验URL_SHORTENER_DOMAINS集合check_readme.py列出了 bit.ly、tinyurl.com、goo.gl、t.co、ow.ly、buff.ly、is.gd、rebrand.ly、cutt.ly、shorturl.at、tiny.cc、rb.gy、lnkd.in、t.ly、bitly.com、po.st、adf.ly、tr.im、x.co 等二十余个短链域名任何条目命中该集合都会触发 E102 错误lint 和 check-diff 两个场景都会检查。README 条目语法解析器眼中的合法行理解格式规则最可靠的方式是看解析器如何逐行分类。classify_linecheck_readme.py把 README 的每一行归入以下类型行类型触发条件说明blank空行被跳过header^(#{2,4})\s...标题行##级确定章节归属entry- title缩进 0/2/4 空格教程条目缩进空格数 ÷ 2 嵌套深度series- 标题无链接缩进 0/2 空格系列标题行toc- [label](#anchor)且位于 ToC 块内目录条目malformed形似- [但 URL/括号不完整会被判为 E001/E103 错误绝不落入 seriesunparseable以上都不匹配触发 E001 错误注意malformed的巧思一个写坏的链接条目缺 scheme、括号未闭合等如果落入series分支就会悄悄从所有检查中消失因此解析器强制把形如- [的行单独归类宁可报错也不静默吞掉。条目 URL 提取自ENTRY_RE正则check_readme.py它还会从条目行内剩余文本tail中提取额外 URL 一并计入检查。多部分系列的合法性由 E002 保证parse_readme在解析到 series 标题行时向前看若紧随其后没有更深缩进的 entry/series 子项就报series title has no deeper child entry错误check_readme.py。本地校验python3 scripts/check_readme.py lintCONTRIBUTING.md 要求在打开 PR 之前在仓库根目录本地运行校验器且必须以状态码 0 退出python3 scripts/check_readme.py lint这是整个贡献指南中最具操作性的部分。lint子命令check_readme.py做三件事语法检查用上文介绍的逐行文法解析整个 README任何不符合 entry/series/header/toc 语法的行都会报错目录检查校验 ToC 条目与##章节锚点的双向一致性E003/E004重复与短链检查归一化 URL 去重E005、http/https 变体警告W102、短链域名拦截E102以及历史遗留的http://链接统计E101info 级。出错时退出码为 1全部通过时为 0。非 JSON 模式下输出按行号与严重级别排序的诊断信息格式为行号:错误码:严重级别 消息末尾打印统计行stats: entries... urls... http... sections... errors... warnings... info...如果需要结构化结果供脚本或 CI 消费可以追加--json参数输出按 errors/warnings/info 分桶的 JSON 及统计信息。lint 的错误码全景E001–E005 与警告 W101/W102把 CONTRIBUTING.md 中checks the grammar above, the Table of Contents, and for duplicate/shortened URLs一句话落实到源码得到如下错误码清单错误码严重级别含义触发场景E001error行无法解析 / ToC 块内出现非法行 / ToC 风格行出现在正文格式错误、漏了]或)、ToC 块外出现- [label](#anchor)E002error系列标题没有更深层子条目- Title后没有缩进子项E003errorToC 锚点没有对应的##标题ToC 写了#go但正文没有## Go:标题E004error##标题没有登记进 ToC新增语言章节后忘了更新目录E005error归一化后 URL 重复同一 URL 出现两次以上白名单除外E101infolint/ errorcheck-diff使用http://链接lint 中属历史遗留仅提示新增行中属错误E102error命中短链域名URL 主机在URL_SHORTENER_DOMAINS中E103error新增行不符合 entry/series/header 文法仅 check-diff 场景W101warning新增youtu.be链接建议改用完整 youtube.com URL仅 check-diffW102warning同一 URL 存在 http/https 变体两个条目仅 scheme 不同这里有一个值得注意的设计E101 在整库 lint 中是 info 级别历史遗留的http://链接被grandfathered保留但在 check-diff 校验新增行时升级为 error——存量可以容忍增量必须合规。重复 URL 的判定与白名单机制规则 1先查重的自动化实现是 E005。normalize_urlcheck_readme.py会把 URL 拆分为(scheme, netloc, path, query)四元组并去掉尾部/和空 path因此https://a.com/x/与https://a.com/x会被判为同一个 URL。同一归一化 key 出现多次且不在白名单内就触发 E005。少数合法重复通过 scripts/lint-allow-duplicates.txt 放行该文件是 E005 的显式例外清单每行一个归一化 URL 并附注释说明原因仓库里目前有两个典型场景craftinginterpreters.com教程的第 1–13 章用 Java 编写、第 14 章起用 C 编写因此有意同时收录在 C/C 与 Java 两个章节下llvm.org/docs/tutorial/的 Kaleidoscope 教程有 C 与 OCaml 两个语言变体同一物理页面、不同#fragment去重逻辑会剥离 fragment因此需要 path 级白名单。这说明重复检查是默认从严、例外开白的模型任何绕过 E005 的需求都要有说得通的理由。ToC 与章节锚点新增语言章节的正确姿势规则 7 允许为不存在的语言新建目录条目但这绝不意味着可以只加一个##标题了事。parse_readme在解析完成后会做双向交叉校验check_readme.py每个 ToC 锚点必须能匹配一个##标题否则 E003每个##标题必须出现在 ToC 中否则 E004。锚点匹配依赖github_slugcheck_readme.py它把标题转小写、去掉非字母数字字符、空白转连字符——所以 README 中的## C/C:对应 ToC 锚点#cc## HTML/CSS:对应#html-and-css。新增语言章节时必须同时完成三件事写## 语言:标题、在 ToC 中登记- [语言](#slug)、在正文中按- Title格式填入教程条目三者缺一都会让 lint 失败。CI 链接巡检可验证性、域名策略与 2-strike 机制CONTRIBUTING.md 最后一段说明了 CI 的另一项职责检查你添加的每个链接是否可达。这对应check-links子命令check_readme.py它默认用 8 个 worker 并发检查 URL并针对每个注册域名做限速每个域名最多 2 个并发、最小间隔 1 秒见DomainLimitercheck_readme.py。每个链接的检查结果是四分类之一_classify_resultcheck_readme.py分类含义典型触发OK可达HTTP 2xx且页面标题不含软 404 特征HARD_DEAD确证失效HTTP 404/410、DNS 解析失败、TLS 证书不匹配、连接被拒SUSPECT可疑需人工确认页面标题含软 404 短语如 page not found、video unavailable、重定向到站点根目录、意外状态码BLOCKED无法验证不算失效命中域名策略、HTTP 401/403/429、网络错误重试后仍失败软 404 检测值得一提有些站点对失效页面仍返回 200但title中含有 404、page not found、no longer available、video unavailable 等短语SOFT_404_PHRASEScheck_readme.py这类结果会被标记为SUSPECT而不是OK。重定向处理上最多跟随 5 次跳转对 429/500/502/503/504 会按Retry-After上限 30 秒退避重试HEAD 请求遇到 400/403/405/501 时会自动降级为 GET。could not verify为什么是预期行为这是 CONTRIBUTING.md 明确说明的边界——Medium、Reddit、LinkedIn、Udemy 等站点会拦截自动化 User-Agent。仓库用 scripts/linkcheck-domains.txt 维护了一份域名策略这些域名的检查失败一律被归为BLOCKED永远不会误报为失效链接。该文件目前收录了 medium.com、*.medium.com、towardsdatascience.com、reddit.com、twitter.com、x.com、linkedin.com、udemy.com、quora.com并注明*.前缀可匹配任意子域名。所以如果你的链接指向这些站点而 CI 显示 could not verify请直接忽略——这是设计行为不是构建失败也不需要修复。从 2-strike 状态机到自动修复 PR链接巡检还配套了完整的状态机与修复流水线2-strike 规则每次巡检结果写入状态文件默认.github/link-rot-state.json。一个 URL 需要连续两次被判定为HARD_DEAD或SUSPECT才会进入周报的 Dead/Suspect 列表consecutive_failures 2BLOCKED不影响计数。周报生成report子命令check_readme.py把巡检结果渲染成 Markdown 问题模板分为 Dead links、Moved links、Suspect links、Blocked/unverifiable 四部分。README 顶部的 Link rot sweep 徽章以及报告落款Regenerated weekly by.github/workflows/link-rot.yml都指向这条每周自动流水线。安全自动修复prune子命令check_readme.py只做两类无歧义修改——删除连续 2 周确证死亡且无重定向的条目、把发生同站重定向的条目标题为新 URL原地更新而不是换成 archive.org 链接同时自动清理因此变成孤儿的多部分系列标题。任何SUSPECT、非主 URL 的次要链接、或一个 URL 匹配多个条目的情况都留给人工处理且该命令的产物以 PR 形式落地、绝不会无人评审直接合入。校验器的安全边界设计check_readme.py 的模块文档明确了一条安全不变量这也是理解整个工具链设计的关键README 内容与 PR diff 都是不可信输入该校验器会运行在 fork 出的 PR 上。因此它只允许urllib/http.client网络调用与纯字符串/正则解析绝不对 README 数据执行eval/exec、不传给 shell、不用它拼命令行。这一原则在细节处处处体现例如escape_md_cellcheck_readme.py在把页面title由第三方站点控制的内容嵌入周报表格时会转义|和\并用零宽空格打断的解析防止恶意页面内容破坏表格结构或触发 GitHub 的 mention 通知。贡献者理解这层设计后也能明白为何条目格式必须严格、为何 URL 必须直接指向教程本体——整个数据管道都建立在对 README 文本的可解析假设之上。结语CONTRIBUTING.md 看似只有三十余行但它定义的每一条规则都能在仓库的 scripts/check_readme.py 中找到对应实现条目与系列格式对应ENTRY_RE/SERIES_RE文法查重与短链禁令对应 E005/E102ToC 规则对应 E003/E004CI 链接检查对应 check-links 的四分类与 scripts/linkcheck-domains.txt 域名策略。提交贡献前只需在仓库根目录跑通python3 scripts/check_readme.py lint退出码 0再核对一遍十四条人工检查项你的 PR 就具备了一次通过的坚实基础。若对规则本身有改进建议可通过 CONTRIBUTING.md 中给出的维护者邮箱 tuvtran97gmail.com 联系。赞分享文档教程【免费下载链接】project-based-learningCurated list of project-based tutorials项目地址https://gitcode.com/GitHub_Trending/pr/project-based-learning点击查看免费下载相关推荐minikube 文档贡献指南make site 本地构建、markdownlint 校验与 Hugo ref/relref 链接规范minikube 文档贡献指南 make site 本地构建、markdownlint 校验与 Hugo ref/relref 链接规范 minikube 的云原生容器编排CLI开发工具SciPy 文档贡献指南从本地 Sphinx 渲染到写作规范与 CI 校验全解析SciPy 文档贡献指南从本地 Sphinx 渲染到写作规范与 CI 校验全解析 本文面向希望向 SciPy 仓库提交文档修改修复 docstring 错误科学计算数据科学高性能计算godot-rustgdext贡献指南从 PR 规范到本地开发与 CI 工具链全解析godot rustgdext贡献指南从 PR 规范到本地开发与 CI 工具链全解析 godot rust仓库 gdext 是 Rust 语言与 Go游戏开发创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
)
)
