dsa.js 贡献指南：从 PR 流程到 Commit 规范的完整实战手册-育师

开发工具

【免费下载链接】dsa.js-data-structures-algorithms-javascript

🥞Data Structures and Algorithms explained and implemented in JavaScript + eBook

项目地址：https://gitcode.com/gh_mirrors/ds/dsa.js-data-structures-algorithms-javascript

导读

本文基于 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.jsonconfig.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"的机制。