• 文档
• 教程
• 知识库

这是一篇面向开源贡献者的实操指南，围绕当前仓库 CONTRIBUTING.md 展开，讲解如何以 Pull Request（PR）形式向这份“程序员必逛网站精选清单”提交新链接。读完本文，你将掌握完整的贡献流程、逐条规则的含义与边界、标准链接格式的正确写法，以及如何借助仓库内置的自动化校验和 PR 模板提升通过率。

贡献前的项目背景：这是一份什么样的清单

Best-websites-a-programmer-should-visit 是一个持续维护的程序员资源导航仓库：它把学习 CS 时值得访问的站点按主题整理成非穷举式清单，涵盖“遇到问题时去哪问”“新闻资讯”“初学者编码练习”“加密货币”“面试准备”“MOOC 课程”“Bash/Shell 脚本”“编译器/解释器入门”“求职招聘”等 30 余个分区（详见 README.md 的索引）。

这份清单的核心内容全部集中在 README.md 一个文件中，每个条目都是形如- 站点名 : 一句简介的 Markdown 列表项。因此，任何对清单内容的增改都必须直接落在 README.md 上——这正是 CONTRIBUTING 指南存在的前提：它定义了一套可审核、可回滚、低噪声的链接入库流程，避免清单因随意提交而失控。

核心入口：PR 是链接入库的唯一通道

指南开篇即声明：被批准的贡献必须通过 Pull Request 提交，且 PR 应对应 README.md 文件的变化。

也就是说，本仓库不接收通过邮件、评论区留言或零散修改来添加链接的方式。一次合法的贡献 = 一个 PR + 对 README.md 的一处修改。这套“单一文件、单一改动”的设计让维护者可以快速 diff、逐条 review，也让贡献历史与清单内容一一对应、便于追溯。

五条硬性规则逐条解析

每个 PR 必须同时满足以下规则，缺一不可：

需要特别强调的是第三条：YouTube 链接被整体排除，理由是“这些内容会随时间变化，变得难以审核”。这意味着即使某个 YouTube 频道质量很高，也不符合本清单的收录标准——贡献者不应以“这个频道很棒”为由绕过该规则，规则本身不接受例外。

标准链接格式：一行搞定站点名、URL 与简介

规则给出了唯一合法的写入 pattern：

Site name OR A simple description : a simple description of the site or slogan of the site.

拆解成三个组成部分：

1. [Site name OR A simple description]—— Markdown 链接文本，放站点名或一句简单描述；
2. (url)—— 站点真实地址；
3. : 简介—— 冒号加空格后跟一句对站点的描述或站点口号。

对照 README.md 中的真实条目可看到完全一致的落盘样式：

- [Codementor](https://www.codementor.io) : A mentorship community to learn from fellow developers via live 1:1 help and more. - [Stack Overflow](https://stackoverflow.com) : subscribe to their weekly newsletter and any other topic which you find interesting - [Coderanch](https://coderanch.com/) : A friendly place for programming greenhorns. Jump straight into any of our topics and light hearted discussions. Ranging from Java, Databases, Android, Programmer certification, Programming jobs and much more...

注意三个细节：行首是-（无序列表符号）；(与:之间有一个空格；描述以句号结尾。如果链接文本本身就是站点名，直接写；如果站点名不够直观，可以在链接文本里给出功能性描述，让读者不点开 URL 也能知道这个站是干什么的。

分区选择与字母排序：让新条目落在“正确的位置”

指南要求：链接必须放入正确的分区，且目前不允许新建分区。因此提交前需要对照 README.md 的 Index 决定归属，常见分区示例包括：

• When you get stuck（遇到问题去哪求助）
• News（新闻聚合）
• Coding practice for beginners（初学者编码练习）
• General Tools（通用工具）
• Interview Preparation（面试准备）
• Competitive programming（竞赛编程）
• Online Compiler and Sharing Code snippets（在线编译器与代码片段分享）
• Open Source Websites、Internships、Jobs等

判定归属时以站点的主要用途为准，而不是以站点的自我宣传为准。例如一个同时提供教程和面试题的网站，应依据其最核心的定位选择分区。

排序要求：在可能的情况下，新链接应按字母序插入所在分区的列表中。README 中各分区当前即为字母序排列（可参考 README.md 中 Codementor、devRant、Google、Learn Anything、Quora、Stack Overflow 的排列顺序），保持这一约定能大幅降低维护者的 diff 阅读成本。注意这是“尽可能”（whenever possible）的软性要求，但遵守它更利于 PR 被快速批准。

非链接类贡献：先走 Issue 再谈 PR

如果你的贡献不是“新增一个链接”而是其他类型（例如：修正现有条目的 URL、调整分区归属、改进 README 的排版、质疑某条收录是否合规），指南明确要求：先创建 Issue 说明情况，得到支持后再行动（仓库根目录的 issues 页）。

这是因为非链接改动可能涉及格式约定、收录口径甚至历史决策，直接提交 PR 容易与维护者预期不一致。先发 Issue 能把讨论前置、减少无效 PR。相应地，pull_request_template.md 中也预留了 “Summary of your changes / Description” 栏位，并提示如果改动关闭了某个 issue 应写成Fixes #<number>。

用 PR 模板自查：提交前对照这份 Checklist

仓库提供了 pull_request_template.md，PR 描述中会自动出现以下自查清单，提交前请逐项勾选：

- [ ] My change follows the Contributing Guidelines - [ ] I have added only one new link to the list. - [ ] I have checked that the link that I added does NOT exist in the project already. - [ ] I have sorted the link alphabetically under the related section.

可以看到，模板的三条核心勾选项恰好对应指南中的“只加一个链接”“确认无重复”“按字母序排序”三条规则，而第一条则要求贡献者声明自己已阅读并遵守 CONTRIBUTING.md。把模板当成“提交前最后一遍检查表”是最不容易出错的做法。

仓库侧的质量保障：awesome-lint 自动校验

除了人工 review，仓库还提供了自动化校验入口。package.json 中定义了：

{ "scripts": { "test": "awesome-lint" }, "devDependencies": { "awesome-lint": "*" } }

也就是说，这是一个遵循 awesome-lint 规范的清单仓库。贡献者可以在本地运行npm test（依赖awesome-lint）对 README.md 的格式、链接可访问性、条目排序等维度做静态检查，在提交 PR 前提前发现格式类问题。这解释了为什么指南对链接格式、分区归属、字母排序如此严格——它们不仅是人工约定，也是机器可校验的规则。

此外，仓库根目录的 white_listed_sites.txt 记录了若干站点域名清单，可与校验流程配合使用。作为贡献者，理解这一点有助于你：先按 CONTRIBUTING 规则手动自查，再用npm test跑一遍自动校验，最后按 PR 模板提交，这是通过率最高的标准路径。

行为底线：必须遵守 Contributor Covenant

指南最后一条要求：任何 PR 必须遵守 Contributor Covenant Code of Conduct。该文件声明了社区的正面行为标准（使用包容性语言、尊重不同观点、建设性地接受批评、专注于社区利益、对他人保持共情），并说明维护者对不合规行为有权采取移除、编辑、拒绝提交乃至临时/永久封禁等措施（见 CODE_OF_CONDUCT.md）。这条规则不针对具体链接内容，而是约束贡献者之间的协作方式——它同样属于“批准 PR”的前置条件。

一份可直接照做的贡献步骤清单

综合以上全部要点，一次完整、合规的贡献流程如下：

1. 检索去重：全量搜索 README.md，确认你要提交的链接不存在；
2. 确认类型：链接指向的站点不是 YouTube 频道/播放列表；
3. 确定分区：对照 README.md 的 Index，选中最匹配的现有分区，不新建分区；
4. 编写条目：按标准 pattern 生成一行内容：

   Site name OR A simple description : a simple description of the site or slogan of the site.

5. 定位插入：将该行以字母序插入所在分区的列表中；
6. 本地校验：如环境允许，运行npm test（awesome-lint）做静态检查（见 package.json）；
7. 提交 PR：PR 只包含这一个链接改动，按 pull_request_template.md 填写描述并勾选全部自查项；
8. 声明合规：确认遵守 CONTRIBUTING.md 与 CODE_OF_CONDUCT.md；
9. 其他改动走 Issue：若你的贡献不是新增链接，先到 issues 创建 Issue 获得支持后再操作。

遵循这套流程，你的 PR 将同时满足人工约定与机器校验双重标准，从而以最高效率通过维护者的审核，为这份程序员资源清单添上高质量的一笔。

• 文档
• 教程
• 知识库