Awesome 列表贡献指南：从首次提交到 Pull Request 合并的完整实战流程

这份指南以 Awesome 精选列表项目（仓库根目录 readme.md 及其配套文档体系）为背景，面向所有希望参与优质技术资源精选的开发者，系统讲解三种贡献路径：向已有列表添加条目、提交全新 Awesome 列表、以及在维护者反馈下更新 Pull Request（PR）。读完本文，你将掌握从编辑 Markdown 文件、发起 PR、通过模板清单自查，到配合审核修改的全流程实操能力，并理解这套流程背后"精选而非堆砌"的社区准则。

贡献前的必读文档：先理解项目规则体系

参与本仓库的贡献，前提是理解其文档分工。项目根目录下有一套相互引用的文档，共同构成贡献流程的完整闭环：

文档	作用
readme.md	项目主列表，按 Platforms、Programming Languages、Front-End Development 等 20 多个分类收录数百个 Awesome 子列表
awesome.md	Awesome 宣言，定义"什么是 awesome"的价值观与列表内容规范
contributing.md	本文主题，说明贡献者如何提交内容、创建列表与更新 PR
pull_request_template.md	提交新列表时的 PR 模板，内含完整的硬性要求自查清单
create-list.md	创建个人 Awesome 列表前的准备步骤
code-of-conduct.md	贡献者行为准则（基于 Contributor Covenant 1.4）

需要特别强调的是，项目以 code-of-conduct.md 作为参与前提：文档开篇即声明"本仓库在发布时附带贡献者行为准则，参与即表示同意遵守其条款"。这意味着任何形式的贡献——无论是添加条目还是提交列表——都默认接受该准则约束，包括使用包容性语言、尊重不同观点、建设性接受批评、以社区利益为先，以及维护者对违规内容进行移除、编辑或拒绝的权利。

三种贡献路径概览：先定位你的目标

contributing.md 将贡献划分为三条互不重叠的路径，适用于不同场景：

1. 向已有列表添加内容：这是绝大多数贡献者最常走的路径，直接在目标 Awesome 列表的 readme.md 上编辑并提交 PR；
2. 创建你自己的 Awesome 列表：当某个主题尚无优质列表，或现有列表质量不佳时，创建新列表并提交收录申请；
3. 添加一个全新的 Awesome 列表：与路径 2 相似但强调"被收录进本仓库"，PR 必须严格遵守 pull_request_template.md 中的要求清单。

下文按实操流程逐一展开。

路径一：向已有 Awesome 列表添加内容（分步实操）

这是 contributing.md 中描述最详细的部分，核心思路是在 GitHub 网页端完成"编辑—提案—提交"三步操作，全程无需克隆仓库到本地。

前置条件：注册 GitHub 账号

首先你需要一个 GitHub 账号；如果对 GitHub 协作尚不熟悉，建议先了解基本的 Pull Request 概念与 Git 基础操作，再进入正式流程。

六步完整操作流程

1. 进入目标 Awesome 列表的 GitHub 仓库页面。以主仓库为例，即 https://github.com/sindresorhus/awesome（此处仅作流程示意，实际操作时替换为你选定的列表仓库）。

2. 点击仓库文件列表中的 readme.md 文件，进入该文件的查看视图。Awesome 列表的内容全部组织在 readme.md 中，这也是后续所有编辑发生的位置。

3. 点击文件查看页右上角的编辑图标（铅笔形状），进入 GitHub 网页端的内置编辑器。GitHub 会为没有写权限的访客自动创建仓库分支（Fork），你的修改不会直接影响原仓库。

4. 在浏览器内编辑文件内容。需要强调的是，编辑时必须遵循前文提到的规则体系：

   • 遵循 awesome.md 中关于列表内容的原则（详见下文"创建自己的列表"一节）；
   • 遵循 pull_request_template.md 中关于条目格式的具体要求，例如条目格式为 - 名称 - 描述，描述以大写字母开头并以句号结尾，且是客观描述而非营销文案；
   • 使用 GitHub Flavored Markdown（GFM）语法编写，包括表格、任务列表、代码块等扩展语法。

5. 填写提案说明并点击 "Propose file change" 按钮。该按钮位于编辑器底部的 "Commit changes" 区域，这里需要简要说明你提出此次修改的原因（例如"新增某工具，用于解决 XX 场景"），提交信息会写入本次修改的 commit。

6. 提交 Pull Request。Propose 之后 GitHub 会引导你进入 "Open a pull request" 页面，填写 PR 标题与说明后正式提交。若目标是向本仓库（主列表）添加条目而非修改子列表，则 PR 直接提交到本仓库；若是修改其他子列表，则提交到对应列表的仓库。

向主列表添加条目的额外要求

如果你向本仓库主列表 readme.md 添加条目，除了上述六步流程，还需严格遵守该仓库的 PR 模板要求（详见下一节）：标题格式、条目描述规范、分类归属、#readme 结尾等，任何一个环节不达标都可能被要求修改。

路径二：添加新的 Awesome 列表——PR 模板清单全解析

contributing.md 明确指出：提交新列表的 Pull Request 必须符合 pull_request_template.md 中的要求清单。这份模板远非简单占位，而是按"PR 本身要求"与"列表本身要求"两个维度列出数十条硬性指标，是审核的实质依据。拆解如下。

对 Pull Request 本身的要求

• 拒绝完全由 AI 生成的 PR：模板明确声明 "Fully AI-generated pull requests are not accepted"，要求人工创作与实质投入；
• 禁止草稿态提交：PR 必须是 100% 就绪状态，不能以 Draft/WIP 形式提交占位；如需孵化期可见性，应先在指定 issue 中讨论；
• 必须评审至少 4 个其他 PR：这是让项目自我维持的关键机制。评审时须真正指出错误或改进建议，仅评论"看起来不错"或直接 approve 不计入评审，指出 lint 违规可加分但不计入；
• PR 标题格式：必须为 Add 列表名 的格式，且标题中不得包含 "Awesome" 一词。模板给出正反示例：Add Swift、Add Software Architecture 合规；Update readme.md、Add Awesome Swift、add Swift、Adding Swift 均不合规；
• 条目描述规范：描述应客观说明列表的主题（而非描述列表本身），首字符大写、以句号结尾，且不得包含列表名称。正例 - iOS - Mobile operating system for Apple phones and tablets.；反例 - iOS - Resources and tools for iOS development.（描述列表本身）、缺少描述、小写开头等。

对 Awesome 列表本身的要求

• 至少存在 30 天：从首个真实提交或开源之日起算（取较晚者），目的是让列表有成熟机会；
• 必须通过 awesome-lint 检查并修复报告的问题；
• 默认分支应为 main 而非 master；
• 仓库命名规范：小写 slug 格式 awesome-name-of-list，例如 awesome-swift；awesome-Swift、AwesomeWebTypography 均不合规；
• 标题使用 Title Case：# Awesome Swift 而非 # awesome-swift 或 # AwesomeSwift；
• GitHub topics 需设置 awesome-list 与 awesome，鼓励追加更多相关 topic；
• 不得重复：提交前必须搜索确认无重复列表；
• 只收录精选内容：列表是"最优秀内容的策展（curation）"而非"全量收集（collection）"，只收录维护中、未归档、未弃用且有文档的项目；若确需收录此类项目，应单独放在独立的 Markdown 文件中；
• 尽量包含 Logo/插画：置于 readme 顶部居中、通栏或右上角，图片须链接到项目官网，且须为高 DPI（宽度不超过原图一半）；
• 必须包含 Awesome 徽章：放在 readme 标题右侧（居中图形头部的列表可居中放置），并链接回本仓库；
• 必须有 Table of Contents：命名为 Contents（而非 "Table of Contents"），必须是列表第一个区块，最多允许一层嵌套（最好没有），且不得包含 Contributing 或 Footnotes 小节；
• 许可证要求：强烈推荐 CC0（任何 Creative Commons 许可证均可），代码类许可证（MIT、BSD、Apache、GPL 等）以及 WTFPL、Unlicense 均不被接受；许可证文本放在仓库根目录的 license 或 LICENSE 文件中，不得在 readme 中重复许可证名称或添加 Licence 小节（GitHub 会在仓库顶部自动展示）；为证明已通读全部要求，模板要求在你的 PR 评论中仅回复单词 unicorn；
• 必须包含贡献指南：文件命名为 contributing.md（大小写不限），readme 中可设名为 Contributing 的独立小节链接到它，位于正文顶部或底部，且该小节不出现在 Table of Contents 中；
• 非必要但必要的补充内容（版权声明、来源链接等）应归入 readme 底部的 Footnotes 小节，同样不出现在目录中；
• 格式与拼写：链接与描述之间用破折号分隔，描述首字母大写且以句号结尾；命名保持一致（如 Node.js 而非 NodeJS/node.js）；不使用硬换行（hard-wrapping）；
• 不得在 readme 中放 CI 徽章（可仍用 CI 做 lint，但徽章无价值）；
• 不得在 readme 顶部出现 "Inspired by awesome-foo" 类链接，Awesome 徽章已足够。

模板末尾还有一句自我审查提示："Go to the top and read it again."——提醒提交者在正式提交前把整份清单再读一遍。这份模板同时是审核者的核对依据：当你被要求去评审其他 PR 时，逐项对照上述清单指出问题即可。

路径三：创建你自己的 Awesome 列表

如果现有列表中找不到合适主题，可参考 create-list.md 创建全新列表。其核心步骤有四：

1. 通读 awesome.md 宣言与 pull_request_template.md 列表指南，确保你的列表设计从一开始就合规；
2. 提交前先搜索现有列表，确认你的主题并非重复；若已有最佳列表存在，优先贡献到那个列表而不是另起炉灶；
3. 创建后等待至少 30 天再提交，让列表有时间沉淀内容与真实使用反馈；
4. 提交收录 PR 前再次通读列表指南，确保万无一失。

Awesome 宣言：定义"什么是 awesome"

awesome.md 为列表内容提供了价值判断标准，是创建列表时的内容指导纲领：

• 只有 awesome 才够格上榜：收录前先调研条目是否真正优秀，只收录你或其他贡献者可以亲自推荐的条目，宁缺毋滥（"You should rather leave stuff out than include too much"）；
• 解释为什么上榜：除条目本身外，还应说明它为何值得收录、读者能获得什么收益；
• 明确列表主题：readme 顶部要有简洁描述，列表覆盖明确范围而非漫无边际，主题已被其他列表覆盖时链接到它们即可；
• 注意语法与格式：列表必须语法正确、无拼写错误、无 Markdown 格式错误，PR 同样适用；
• 选择合适许可证：未选择许可证意味着他人不得复制、分发或创建衍生作品；推荐 CC0；
• 包含贡献指南：贡献者应清楚如何参与，可直接以本仓库的 contributing.md 为模板修改使用；
• 样式规范：创建目录、按分类组织内容、适当使用图片，并保证条目格式一致（如所有条目描述都以句号结尾）；
• 尊重他人意见：作为列表所有者，要尊重不同观点；当大量用户不同意你的决定时，应重新考虑。

更新你的 Pull Request：如何应对维护者反馈

contributing.md 特别强调：列表维护者有时会要求你在合并前修改 PR，原因通常是拼写错误，或 PR 未完全符合 awesome-* 系列列表的指南。这是流程的正常一环，而非失败信号。

处理此类反馈的关键点：

• 逐条对照模板清单自查：多数被拒原因都能在 pull_request_template.md 中找到对应条款，例如条目描述以句号结尾、标题不含 "Awesome"、描述不含列表名等；
• 了解 Git 修改提交的方式：针对修改内容，常见做法是补充提交（follow-up commit）或修改既有提交（amend），具体方式取决于维护者的偏好与 PR 历史整洁度要求；
• 保持响应及时：模板中明确要求贡献者 "be responsive"——及时回应用户与维护者的意见，能显著提升合并效率；
• 态度务实：若对某条要求有异议，可在 PR 讨论中说明理由，但默认应遵循社区既有的、经过大量贡献者验证的规则。

从维护者视角看，这份更新流程也是质量闸门：它在合并前兜底修正拼写、格式与规范问题，保证主列表 readme.md 的长期可维护性——这正与 readme 中"条目描述一致、格式统一"的呈现风格（如所有子列表条目 - 名称 - 描述 统一格式）一脉相承。

总结：贡献流程的完整闭环

回顾本仓库的贡献体系，可以发现一条清晰的闭环：行为准则（code-of-conduct.md）设定参与底线 → 贡献指南（contributing.md）指明操作路径 → 创建指南（create-list.md）与列表宣言（awesome.md）指导内容创作 → PR 模板（pull_request_template.md）充当提交与审核的双向检查清单 → 维护者反馈驱动的 PR 更新完成质量兜底 → 最终合并进主列表 readme.md 供全球开发者检索使用。

对贡献者而言，最省力的策略是：先读宣言理解精神，再读模板逐项对照，提交前用 awesome-lint 自检，提交后积极响应用户反馈。这套流程同时保证了"策展而非收集"的定位——正如 awesome.md 所言，列表是精选，而不是仓库。