dsa.js 贡献指南：从 PR 流程到 Commit 规范的完整实战手册
【免费下载链接】dsa.js-data-structures-algorithms-javascript
🥞Data Structures and Algorithms explained and implemented in JavaScript + eBook
导读
本文基于 CONTRIBUTING.md 展开，系统讲解如何为 dsa.js（Data Structures & Algorithms in JavaScript，一个以源码 + 电子书形式实现的算法与数据结构开源仓库）提交高质量贡献：涵盖 Issue 提交、Pull Request 全流程、基于 Conventional Commits 的提交信息规范，以及由 ESLint 与 Jest 驱动的测试/CI 机制。读完本文，你将掌握一套可直接复用的开源协作流程，并理解仓库中 package.json、.eslintrc.js、jest.config.js 等配置文件是如何支撑这些规则的。
说明：仓库当前为只读镜像，本文只介绍查看、安装、运行与配置方式，不涉及对仓库内容的修改操作。
贡献方式总览
dsa.js 欢迎任何形式的贡献，包括 Issue、评论与 Pull Request。文档给出的三条核心原则是协作的基石：
- 写测试（如果适用）：仓库尽量接近 100% 代码覆盖率，任何新代码都应配套测试。
- 遵循 Linter：项目使用 ESLint 并采用 Airbnb JavaScript Styleguide，CI 构建（Travis/CircleCI）中会执行
npm run lint。 - 不确定就提问：实现修复或功能时如有疑问，可以创建 Issue 询问维护者。
这三条原则并非空话，仓库的配置文件给出了具体落地证据：
- 代码风格由 .eslintrc.js 定义，它
extends: 'airbnb-base'，并启用了jest插件，在env中声明jest: true； - 测试框架与覆盖率在 package.json 的脚本中体现：
test运行jest --verbose，ci运行npm run lint:base && jest --coverage； - 代码提交前的质量门禁由 husky 提供：
pre-push: npm run ci（见 package.json 的husky.hooks），也就是说每次git push都会先自动跑完 lint + 测试 + 覆盖率，不合格则推送被阻止。
提交 Issue 的指南
在提交 Issue 之前，请先搜索 issue 跟踪器：也许你的问题已有人提出，相关讨论可能直接给出了可用的 workaround，避免重复劳动。这条前置检查与提交 PR 前的"先搜索、再动手"原则一脉相承，是高效协作的第一步。
提交 Pull Request（PR）的完整流程
提交前的准备
在动手写代码前，文档要求依次确认以下事项：
- 先搜索已有的 open 或 closed PR，确认没有重复工作；
- 确保有一个 Issue 描述了你要修复的问题，或记录了你要实现的功能设计——先讨论设计，再提交代码，这样维护者更容易接受你的工作；
- 将
amejiarosario/dsa.js仓库 fork 到自己名下； - 基于 master 新建一个功能分支：
git checkout -b my-fix-branch master
- 创建你的补丁，务必包含相应的测试用例；
- 运行完整测试套件，确保全部通过；
- 用描述性的提交信息提交变更（必须遵循本文下半部分的提交信息规范，因为 release notes 是由这些提交信息自动生成的）：
git commit -a
注：
git commit -a可选的-a选项会自动对已修改（add）和已删除（rm）的文件执行暂存。
- 推送分支到 GitHub：
git push origin my-fix-branch
- 在 GitHub 上向
dsa.js:master发送 Pull Request。
根据反馈修改
如果维护者建议修改，你需要：
- 完成要求更新；
- 重新运行测试套件确认仍然通过；
- Rebase 分支并强制推送以更新 PR：
git rebase master -i
git push -f
PR 合并之后的清理
PR 合并后即可安全地删除分支并同步上游：
# 删除远程分支（可通过 GitHub Web UI，或在本地 shell 执行）
git push origin --delete my-fix-branch
# 切回 master
git checkout master -f
# 删除本地分支
git branch -D my-fix-branch
# 用最新上游版本更新你的 master
git pull --ff upstream master
Commit Message 规范：为什么它如此重要
dsa.js 的提交信息之所以有严格格式，文档明确说明了两点：一是让项目历史更易读、易追溯；二是项目用提交信息自动生成 change log。仓库的 package.json 证实了这一点：release 配置使用 semantic-release，其插件链包含 @semantic-release/commit-analyzer、@semantic-release/release-notes-generator、@semantic-release/changelog 等；devDependencies 中还有 commitizen 与 cz-conventional-changelog，用于交互式生成符合规范的提交信息。也就是说，一条不合规的 commit message 会直接影响版本号决策与 CHANGELOG 的质量。
仓库根目录的 CHANGELOG.md 就是这套机制的直接产物，例如：
## 2.7.6 (2021-11-30)
### Bug Fixes
* **graph:** minor typo in bfs code documentation (...), closes #110
## 2.7.5 (2021-05-24)
### Bug Fixes
* **bst:** on duplicates values the same node is returned (...), closes #99
可见每个变更都带上了 type（Bug Fixes）、scope（graph/bst）与 closes 引用，这正是下面格式规范的成果。
提交信息格式
每条提交信息由 header、body 和 footer 组成，header 又包含 type、scope 与 subject：
<type>(<scope>): <subject>
<空行>
<body>
<空行>
<footer>
一个包含 header、body、footer 的完整示例：
fix(linked-list): insert in the middle bug
One reference was not updated when inserting an item in the middle of a linked list.
Fixes: #8
硬性约束包括：
- header 是必填的，其中的 scope 可选；
- 提交信息每一行不能超过 100 个字符，以保证在 GitHub 和各种 git 工具中易读；
- footer 中应包含 issue 的关闭引用（如
Fixes: #8、Closes #234），如果存在的话。
更多示例：
feat(heap): add error handling for heaps
BREAKING CHANGE: size is now an attribute rather than a method. Similar to the built-in Map.size and Set.size
fix(book/solutions): fix missing solutions
Revert（回滚提交）
如果某次提交是对先前提交的回滚，信息应以 revert: 开头并紧跟被回滚提交的 header；body 中应写明 This reverts commit <hash>.，其中 hash 是被回滚提交的 SHA。
Type：三种必选类型
- fix：Bug 修复；
- feat：新功能；
- chore：CI 配置文件与脚本的变更（示例 scope：Circle、BrowserStack、SauceLabs）。
仓库的 package.json config.commitizen.types 也印证了这三类，并为它们定义了 CHANGELOG 分组标题（Features ✨ / Bug Fixes 🐛 / Chores 🔩），同时还补充了各自的适用语义：feat 是"在代码和/或书上引入新功能"，fix 是"修复代码或书上的 bug"，chore 是"不修改代码或书文件的其他变更"。
Scope：以主目录名为准
scope 应使用主目录名，推荐的示例包括：
- list
- map
- tree
- graph
- sorting
- book
- 等等
这些 scope 与仓库实际目录一一对应：src/data-structures 下的 linked-lists、maps、trees、graphs、stacks、queues、heaps、sets、arrays，src/algorithms 下的 sorting 目录，以及 book 目录。CHANGELOG 中的 graph、bst、book、linkedlist、hashmap、test 等 scope 都是这一约定的实际应用。
Subject：简洁描述
- 使用祈使句、一般现在时：写 "change"，而不是 "changed" 或 "changes"；
- 首字母不要大写；
- 结尾不要加句号。
Body：动机与对比
body 与 subject 一样使用祈使句、一般现在时；应包含变更的动机，并与先前行为作对比。
Footer：Breaking Changes 与 Issue 引用
footer 用于记录 BREAKING CHANGES 信息，也是引用本次提交所 Closes 的 GitHub issue 的位置：
Closes #234
Breaking Changes 应以 BREAKING CHANGE: 开头（后跟空格或两个换行），其余内容接着书写。破坏性变更的常见示例包括：
- 删除或重新定义现有 API 参数；
- 改变返回值；
- 删除或修改 options 参数对象上的现有属性；
- 添加或移除错误；
- 改变某个事件的预期触发时机；
- 改变使用特定 API 的副作用。
仓库中的测试与 CI 落地：规则如何被执行
贡献指南要求的"写测试 + 100% 覆盖率 + 过 lint"，在仓库中有完整的工具链支撑，新贡献者可以在提交前用以下命令本地自检（见 package.json 的 scripts）：
npm run lint # npm run lint:base -- --format codeframe，对 src 与 book/interview-questions 下的 js 执行 ESLint（带修复）
npm test # jest --verbose
npm run ci # npm run lint:base && jest --coverage，与 husky pre-push 挂钩
npm run coverage # jest --coverage 并打开 lcov 覆盖率报告
几个值得注意的实现细节：
- Lint 范围：
lint:base为npx eslint --fix '{src,book/interview-questions}/**/*.js'，即只检查src目录和 book/interview-questions 目录（该目录存放电子书附带的面试题实现与.spec.js测试）； - ESLint 规则：.eslintrc.js 基于
airbnb-base，并针对算法/数据结构代码做了三处定制——no-param-reassign允许给对象参数添加属性、no-plusplus允许 for 循环更新表达式中的++/--、no-restricted-syntax允许for..of，同时通过 jest 插件把jest/no-focused-tests设为 error（禁止把.only留在测试中）； - 测试范围：jest.config.js 通过
testPathIgnorePatterns排除了/node_modules/、/dist/、/lab/、/benchmarks/、/coverage/，即正式测试聚焦于src与book/interview-questions，而lab（练习）与benchmarks（基准）不纳入常规测试； - 测试风格：仓库测试统一从 src/index.js 导出入口引入被测结构，例如 stack.spec.js 中
const { Stack } = require('../../index')，然后按describe → beforeEach → it组织用例，覆盖边界行为（如空栈pop()返回null）。提交新功能时，参照同目录下已有*.spec.js的写法即可保持一致； - 版本发布：
semantic-release按 tag 格式${version}发布，@semantic-release/git会自动生成chore(release)提交，进一步印证了"commit message 决定 changelog"的机制。
贡献自检清单
提交 PR 前，对照以下清单逐项确认，可大幅提高被合并的概率：
- 已搜索 issue / PR，确认无重复工作；
- 已有对应 Issue 描述问题或功能设计；
- 基于新分支开发（
git checkout -b my-fix-branch master）； - 新代码附带了完整的
*.spec.js测试用例，并覆盖边界情况； - 本地
npm run ci全部通过（lint + 测试 + 覆盖率）； - 提交信息遵循
<type>(<scope>): <subject>格式，行宽 ≤ 100 字符，必要时包含 body 与 footer； - 如需破坏性变更，已在 footer 中标注
BREAKING CHANGE:； - PR 被要求修改后，执行
git rebase master -i与git push -f更新分支。
遵循这些约定，你的贡献不仅能顺利合并，还会自动成为 CHANGELOG.md 与 npm 版本发布记录的一部分——这正是"用规范换取自动化"的开源协作精髓。
【免费下载链接】dsa.js-data-structures-algorithms-javascript
🥞Data Structures and Algorithms explained and implemented in JavaScript + eBook
火山引擎视频云技术社区，是面向 AI 音视频开发者的技术交流平台。这里汇聚源自抖音、豆包等亿级 DAU 产品的 RTC、直播、点播、AI 媒体处理、音视频互动技术，提供接入指南、最佳实践、性能调优、场景案例、Demo 代码、开源项目、白皮书和 API 文档。社区汇聚官方工程师与一线开发者，为 AI 视频通话、数字人、AI 视频处理等应用的开发与落地提供技术支持。
更多推荐
3
0- 0
已为社区贡献2条内容
所有评论(0)