awesome-cryptography 贡献指南实战:链接条目规范、remark-lint 风格校验与 CI 测试全流程
awesome-cryptography 贡献指南实战:链接条目规范、remark-lint 风格校验与 CI 测试全流程
awesome-cryptography 是一份精心挑选的密码学资源清单(项目自述见 README.md),覆盖对称/非对称加密、哈希算法、工具、框架库与学习资源等数百条链接。本文以仓库内官方贡献文档 CONTRIBUTING.md 为核心,结合 package.json、.github/workflows/test.yml 等仓库源码,系统讲解向该项目提交新链接的完整流程:从一条链接的格式要求、描述字数上限,到 remark-lint 自动化风格校验的规则来源,再到本地与 CI 环境的测试验证。读完本文,你将能够独立完成一次"规范、可一次通过"的贡献提交。
一、贡献指南定位:为什么链接清单也需要硬性规范
作为一个维护数十年积累、横跨 20 余种编程语言框架的精选列表,awesome-cryptography 的质量主要依赖两点:人工审核与自动化校验。
- 人工层面:贡献文档明确要求"每条链接单独一次提交"、"每个 Pull Request 只含一次提交"(见 CONTRIBUTING.md),这保证了每次变更可被独立审阅与回滚。
- 自动化层面:文档规定使用 remark-lint 对
README.md与CONTRIBUTING.md本身进行风格校验(见 CONTRIBUTING.md),并由 GitHub Actions 在每次 push / PR 时强制执行。
换句话说,贡献者遵守的不是"建议",而是会被 CI 机器直接判分的形式化规则。理解这些规则从哪来、由什么实现,是顺利通过评审的前提。
二、贡献基本流程(Guidelines 逐条拆解)
2.1 提交粒度:一个链接一次提交
原文档的核心要求非常明确(CONTRIBUTING.md):
- Add one link per commit.(每条链接单独一次提交)
- Add one commit per Pull Request.(每个 Pull Request 只含一次提交)
这意味着一次 PR 不要夹带多条链接、重构或其他改动,审阅者可以精准定位每一条新增条目;一旦某条链接有问题,也只需回滚对应的一次提交。
2.2 链接条目的标准格式与字数上限
新链接必须严格遵循如下格式(CONTRIBUTING.md):
- [project-name](http://example.com/) - A short description ends with a period.
逐段解析该格式:
| 组成 | 要求 |
|---|---|
| 列表符号 | 行首必须是 - (连字符 + 空格) |
| 项目名 | 用 [ ] 包裹,即列表显示文本 |
| 链接 | 紧跟项目名,用 ( ) 包裹完整 URL |
| 分隔 | ) - (右括号 + 空格 + 连字符 + 空格) |
| 描述 | 一句以句号结尾的简短英文描述 |
| 字数上限 | 描述部分最多 350 个字符(CONTRIBUTING.md) |
对照仓库实际条目验证格式,例如 README.md 中的 Rust 条目:
- [xxHash](https://github.com/Cyan4973/xxHash) - Extremely fast hash algorithm.
关于 350 字符上限的落地:项目使用 remark-lint-alphabetize-lists 等插件做列表级校验(见下文第四节),同时通过 remark-preset-lint-recommended 的推荐规则集约束列表项标点、换行等细节;贡献者提交前自行数清描述长度,是最稳妥的做法。
2.3 需要新增章节时的配套动作
当现有目录无法容纳新资源时,文档允许新增章节(CONTRIBUTING.md),但必须完成两件事:
- 添加该章节的描述(Add the section description)
- 把章节标题加入目录(Table of Contents)(Add the section title to Table of Contents)
README 的目录结构在 README.md,新增章节后必须同步更新这一索引,否则读者无法从目录跳转,CI 也会因目录与正文不一致产生问题。
2.4 去重、校对与卫生要求
文档列出的其余硬性要求(CONTRIBUTING.md):
- 提交前先搜索旧条目,避免重复(Search previous suggestions before making a new one, as yours may be a duplicate);
- 检查拼写与语法(Check your spelling and grammar);
- 删除行尾空白(Remove any trailing whitespace)——这一点同样会被 lint 规则检查,
remark-lint的 recommended 规则集中包含对空格/行尾的处理; - 在 Pull Request 中说明"为什么这个库很 awesome"(Send a Pull Request with the reason why the library is awesome);
- 确保测试通过(Make sure the tests are passing)。
最后一条"测试通过"不是客套话:它直接对应仓库 package.json 中的 test 脚本与 CI 工作流,详见下文第四、五节。
三、Styleguide:remark-lint 到底在检查什么
贡献指南的 Styleguide 一节(CONTRIBUTING.md)声明:项目强制所有提交使用同一风格,并使用 remark-lint 校验 README.md 与 CONTRIBUTING.md 两个文件。
从仓库 package.json 的 remarkConfig 可以看到实际生效的规则配置:
"remarkConfig": {
"plugins": [
"remark-preset-lint-recommended",
["remark-lint-list-item-indent", "space"],
"remark-lint-alphabetize-lists",
"remark-lint-are-links-valid-duplicate"
],
"settings": {
"commonmark": true
}
}
逐条解读这些插件与设置:
| 配置项 | 校验内容(结合仓库实际推断) |
|---|---|
remark-preset-lint-recommended |
remark-lint 官方推荐规则集,涵盖标题层级、列表项标点、空白、链接文本等基础 Markdown 规范 |
remark-lint-list-item-indent: "space" |
列表项内容须以空格对齐/缩进,统一列表写法 |
remark-lint-alphabetize-lists |
要求列表条目按字母顺序排列——这解释了为何 README 各章节内条目近似按字母序组织 |
remark-lint-are-links-valid-duplicate |
校验链接是否有效且不允许重复链接,直接支撑文档"先搜索旧条目防重复"的要求 |
settings.commonmark: true |
按 CommonMark 规范解析 Markdown,保证不同渲染器行为一致 |
还有一个容易被忽略的细节:仓库内的两个 Markdown 文件开头都写了 lint 控制注释,例如 CONTRIBUTING.md 的 <!--lint disable alphabetize-lists-->,以及 README.md 的 <!--lint disable no-missing-blank-lines alphabetize-lists list-item-punctuation-->。这说明项目对个别确需保留原顺序的场景(如目录锚点、版本化列表)允许显式豁免规则;但普通新增链接不得滥用该豁免,必须保持列表整体有序。
四、本地测试:yarn install 与 yarn test 的执行原理
贡献文档的 Testing 一节(CONTRIBUTING.md)给出了本地测试两步命令:
$ yarn install
$ yarn test
这两条命令对应仓库的真实实现:
yarn install安装 package.json 声明的依赖:remark、remark-cli、remark-lint、remark-lint-alphabetize-lists、remark-lint-are-links-valid-duplicate、remark-preset-lint-recommended等;锁文件为仓库根目录的 yarn.lock。yarn test实际执行的是 package.json 中定义的:
"test": "remark README.md CONTRIBUTING.md -f"
即用 remark 同时检查 README.md 与 CONTRIBUTING.md 两个文件,-f(frail)参数使 remark 在发现任何 lint 问题时以非零状态退出。结合 CI 的用法(见第五节)可以推断:一旦本地 yarn test 报错,PR 在 CI 中也必然失败,因此本地测试通过是提交的硬门槛。
本地自测的推荐顺序:
- 修改条目(严格按 2.2 的格式);
- 确认描述不超过 350 字符、无行尾空白、拼写无误;
- 运行
yarn install(首次或依赖变更后); - 运行
yarn test,根据输出逐条修正,直到零告警退出。
五、CI 链路:测试如何在 PR 中被强制执行
仅靠贡献者自觉是不够的,仓库通过 GitHub Actions 工作流 .github/workflows/test.yml 把测试固化到了每次提交:
- 触发时机:
push到master分支、任意pull_request、以及手动触发workflow_dispatch(.github/workflows/test.yml); - 运行环境:
ubuntu-latest,Node.js 18(.github/workflows/test.yml); - 依赖缓存:以
yarn.lock的内容哈希作为缓存 key 缓存node_modules,加速重复构建(.github/workflows/test.yml); - 核心步骤:
yarn install安装依赖,然后yarn test执行 remark lint(.github/workflows/test.yml)。
也就是说,贡献者每提交一个 PR,CI 都会在干净的 Ubuntu 环境里重跑一遍安装与 lint;任何格式违规都会让构建标记为失败,Pull Request 页面会直接显示红色状态。这也是 CONTRIBUTING.md 顶部 test badge 所反映的持续结果。
此外,依赖的日常维护由 .github/dependabot.yml 负责:npm 依赖与 GitHub Actions 各自每天 02:00 检查更新,最多同时打开 10 个依赖升级 PR。这意味着 remark-lint 及其插件会持续升级,贡献者偶尔会遇到"新版本 lint 规则更严"的情况,属于正常现象。
六、一份可复制的贡献检查清单
综合以上全部规范,一次合格的贡献应依次满足:
- 查重:在 README.md 全文与历史 PR 中搜索,确认无重复条目;
- 格式:
- project-name - 以句号结尾的简短英文描述。; - 长度:描述 ≤ 350 字符;
- 归类:放入正确的章节;确需新章节时,补章节描述并同步 README.md 目录;
- 排序:若所在章节为字母序列表(受
remark-lint-alphabetize-lists约束),将条目插入正确位置; - 卫生:无行尾空白、拼写与语法正确;
- 提交粒度:一个链接 = 一次提交 = 一个 PR;
- 本地验证:
yarn install && yarn test零告警通过; - PR 说明:写明该库为何值得收录(why awesome)。
七、总结
向 awesome-cryptography 贡献链接并非简单的"贴一个 URL",而是一套由人工规则 + remark-lint 自动化校验 + GitHub Actions CI 三层保障的质量流程。本文梳理的格式模板、350 字符上限、字母序约束、lint 插件配置与本地/CI 测试命令,全部可直接对照 CONTRIBUTING.md、package.json 与 .github/workflows/test.yml 复现验证。遵循这份指南提交,你的链接既能通过机器检查,也能让维护者快速确认其价值。