awesome-cryptography 贡献指南实战:链接条目规范、remark-lint 风格校验与 CI 测试全流程

原创2026-10-14 12:22:011,335 阅读
文章标签:文档密码学

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),但必须完成两件事:

  1. 添加该章节的描述(Add the section description)
  2. 把章节标题加入目录(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 中也必然失败,因此本地测试通过是提交的硬门槛。

本地自测的推荐顺序:

  1. 修改条目(严格按 2.2 的格式);
  2. 确认描述不超过 350 字符、无行尾空白、拼写无误;
  3. 运行 yarn install(首次或依赖变更后);
  4. 运行 yarn test,根据输出逐条修正,直到零告警退出。

五、CI 链路:测试如何在 PR 中被强制执行

仅靠贡献者自觉是不够的,仓库通过 GitHub Actions 工作流 .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 规则更严"的情况,属于正常现象。

六、一份可复制的贡献检查清单

综合以上全部规范,一次合格的贡献应依次满足:

  1. 查重:在 README.md 全文与历史 PR 中搜索,确认无重复条目;
  2. 格式:- project-name - 以句号结尾的简短英文描述。;
  3. 长度:描述 ≤ 350 字符;
  4. 归类:放入正确的章节;确需新章节时,补章节描述并同步 README.md 目录;
  5. 排序:若所在章节为字母序列表(受 remark-lint-alphabetize-lists 约束),将条目插入正确位置;
  6. 卫生:无行尾空白、拼写与语法正确;
  7. 提交粒度:一个链接 = 一次提交 = 一个 PR;
  8. 本地验证:yarn install && yarn test 零告警通过;
  9. PR 说明:写明该库为何值得收录(why awesome)。

七、总结

向 awesome-cryptography 贡献链接并非简单的"贴一个 URL",而是一套由人工规则 + remark-lint 自动化校验 + GitHub Actions CI 三层保障的质量流程。本文梳理的格式模板、350 字符上限、字母序约束、lint 插件配置与本地/CI 测试命令,全部可直接对照 CONTRIBUTING.md、package.json 与 .github/workflows/test.yml 复现验证。遵循这份指南提交,你的链接既能通过机器检查,也能让维护者快速确认其价值。

登录后查看全文
awesome-cryptography