San CLI 的前端工程能力建设

前言

作者：刘胡粤
2021 年 3 月 5 日

我所在的团队需要负责许多前端开源项目，比如命令行工具 san-cli、调试工具 san-devtools、组件库 santd、单文件组件 loader san-loader、热更新 loader san-hot-loader、eslint 插件 eslint-plugin-san、单测工具库 san-test-utils……

随着参与这些开源项目的人越来越多，我们将不得不面对开源维护的问题，比如，负责 san-devtools 的同事最近就问了我自定义 Issues 模板的相关问题，想必是有人通过提 Issues 报了 bug，但是提的 Issues 的质量不高，bug 没描述清楚，让人不好修。

类似这些开源维护的问题，如果我们没有处理好，不仅会影响我们的工作效率，更重要的是，还会影响我们的开源项目发扬光大。

怎么办？

San CLI 开源有一段时间了，而我做过一些关于 San CLI 的开源维护方案的工作，所以接下来，我将分享我积累的浅薄经验，希望对大家能起到抛砖引玉的作用。

大家准备好啊，我要开始抛砖头了。

今天一共会抛 9 块砖头：Issues 模板、代码规范、单元测试、commit message 规范、持续集成（CI）、GitHub 徽章、监控 npm 包、CHANGELOG、贡献指南。在开源维护方面，我们可以做的事情有很多，其中的这 9 个是我在维护 San CLI 的过程中涉及到的，应该基本是开源维护最常用的部分了，希望能对大家有启发。

Issues 模板

我们就从最近被同事问到的 Issues 模板开始讲起。

Issues 模板是什么？为什么要用 Issues 模板？

Issues 模板是什么？就是提 Issues 时用的模板。

我们先随便找个没有设置 Issues 模板的代码库，然后新建一个 Issues ，是这样的：

可以看到，标题和内容都是什么都没有。

接下来我们看下在 San CLI 里新建 Issues 是怎样的：

可以看到，首先会让我们选择 Issues 模板，这是是因为我们给 San CLI 设置了 2 个模板，bug 模板和 feature 模板，提 bug 就用 bug 模板，提 feature 就用 feature 模板。

最经常被提的 Issues 当然是 bug 了，所以我们看下 bug 模板：

可以看到，和之前没设置 Issues 模板的代码库的情况完全不一样了，标题打上了 bug 标签，内容里告诉了提 Issues 的人该写什么东西，包括 san-cli 的版本，bug 是什么，以及 bug 复现步骤等等。

看到这里，我们应该就明白了为什么要用 Issues 模板了 —— 如果提 Issues 的人都能这么清晰、全面、详细地描述 bug，必然能极大地提高我们修 bug 的效率呀。

怎么设置 Issues 模板？
那怎么设置 Issues 模板呢？很简单。首先，我们打开在 GitHub 上的项目代码库的首页，可以看到有个 Settings：

如果我们没看到，那说明我们没有这个代码库的设置的权限，可以让有权限的人帮我们加权限。

然后，我们点击这个 Settings 进入设置页面，滑到页面下边，能看到 Issues 设置这里有个大大的绿色按钮，Set up templates：

点它，然后按照指引一步步操作就搞定了，确实很简单吧？

其实原理也很简单，原理是这样的：我们按照指引操作完后，本质上就是在项目根目录的 .github 文件夹下新建了一个名为 ISSUE_TEMPLATE 的文件夹，这个文件夹下就是 Issues 模板的 Markdown 文件。所以，以后如果我们想要修改 Issues 模板的内容，直接在这改就行。如下图所示：

Issues 模板的扩展资料
如果想进一步了解 Issues 模板，这些资料或许会有帮助：

1. Issues 模板的 GitHub
   官方文档：https://docs.github.com/en/free-pro-team@latest/github/building-a-strong-community/configuring-issue-templates-for-your-repository
2. GitHub 官方推荐的编写模板的指南：https://www.talater.com/open-source-templates/#/

代码规范

接下来是第二块砖头，代码规范。

我们都知道代码规范很重要，这不用多说，但是光靠书面约定和 code review 来保证开源项目的代码规范是效率低下的且不靠谱的，得充分利用一些工具，包括 eslint、husky、lint-staged。

eslint
eslint 是什么？
eslint 是一个 npm 包，可以用来检查代码规范。

eslint 怎么用？
首先我们得安装它，安装好后再在项目的 package.json 文件的脚本字段 scripts 里加上这么一行：

lint 是脚本的名字，可以随便取，但也不能太随便，最好让人看得懂。

eslint ./ 就是脚本本身了，其中，eslint 的意思是去调用我们安装的 eslint，./ 是传给 eslint 的参数，意思是检查当前目录下所有的文件的代码规范。

然后，去命令行里执行 yarn lint 或 npm run lint ，eslint 就会根据它内置的代码规范来检查我们的代码了，检查出来的代码规范问题会输出在命令行里，如下图所示，我们就可以根据提示去修改代码了。

细心的同学这时可能会发现这样的问题：如果不想用 eslint 内置的代码规范，想用自己的代码规范怎么办？

好问题，其实百度也有自己的代码规范，所以我也得按照公司的代码规范来检查 San CLI 的代码，接下来就以此为例来看下怎么用自己的代码规范。

我为了按照公司的代码规范来检查，得再安装个名为 @ecomfe/eslint-config 的 npm 包，这是公司写的专门给 eslint 用的配置，里面就是公司的代码规范。

安装好后，就给 eslint 配置上它：

至此，eslint 检查代码规范时就会按照公司的代码规范来检查了。

另外，可以看到，我除了给 eslint 配置了公司的代码规范外，还配置了个别的东西，就是上图中 rules 字段下的那个东西。那个东西的意思是：关闭对逗号悬垂的检查。

逗号悬垂是 comma dangle 的直译。什么叫逗号悬垂？举个例子，我们有一个对象，这个对象有两个属性，第一个属性和第二个属性之间我们是用逗号隔开的，如果第二个属性的后面也加了逗号，就叫逗号悬垂。

公司的代码规范是要求逗号悬垂的，而具体到我所在的团队的情况，又是禁止逗号悬垂的，所以我就在这里特殊处理了下，把逗号悬垂的检查规则单独给关了。

husky
虽然我们知道怎么检查代码规范了，但是那是手动执行，并不能保证每个人在提交代码前都记得执行。所以，我们得想办法让检查代码规范自动执行，这就轮到 husky 登场了。

husky 是什么？
husky 听起来是不是有点耳熟？没错，husky 的中文翻译就是哈士奇，我也不知道为什么这个 npm 包取了个狗名。

通过这个 npm 包，我们可以在 commit 的时候自动执行一些操作，比如执行检查代码规范的脚本。

husky 怎么用？
husky 的用法也很简单。我们安装好 husky 后，在 package.json 文件里这么配置一下就可以了：

hooks 字段的意思是 “钩子”，在 hooks 字段下的 pre-commit 字段的意思是 “commit 之前”，我们给 “commit 之前” 配置了 yarn lint，这样，每一次在本地 commit 的时候就都会检查代码规范了。

我们看下效果：

这里我们执行了 git commit -m ‘test’，于是就开始检查代码规范了，如果检查出错误，那此次 commit 就不会成功了，就像这样：

lint-staged
eslint 加 husky 可以说是已经把本地代码规范的检查问题解决了，不过还可以做得更好一点。

eslint 加 husky，每次检查都是全量检查，而不是只检查我们改动的文件，这样其实有一些问题，首先能想到的是全量检查比只检查改动的文件要花的时间多得多，其次，我们假设一个场景，某个代码库有成百上千个代码规范问题，这些问题分布在多个文件中，我们把这个代码库拉到本地，只改动了其中一个文件，然后想提交代码，结果提示我们要把所有文件的这成百上千个代码规范问题都解决，像这个样子：

这合理吗？

那怎么办呢？怎样才能只检查改动的文件呢？

答案是用 lint-staged。

lint-staged 是什么？
lint-staged 也是一个 npm 包。husky 让我们能在 commit 时自动执行一些操作，而 husky 配合 lint-staged 一起使用的话，就能让我们在 commit 时自动对改动的文件执行一些操作。

lint-staged 怎么用？
用法也很简单，安装好 lint-staged 后，在 package.json 文件里配置一下就完事了：

把 pre-commit 字段原来的值 yarn lint 换成了 lint-staged，然后在和 husky 字段同级的位置新增一个 lint-staged 字段并配置上 eslint，图中的 * 的意思是针对所有有改动的文件执行操作。

看看效果：

比起原来上百个报错，清爽多了。

这下我们的本地代码规范检查就完美了。

单元测试

代码规范能自动检查了，那单元测试是不是也得自动执行下？嗯，是应该也自动执行下，因为单元测试也很重要，现在在百度不会写单元测试都不能成为 Good Coder（一种荣誉）。

有了之前的自动检查代码规范的基础，自动执行单元测试就很简单了：

给 pre-commit 字段的值加多一个执行单元测试的操作就行了，如果我们是用 jest 写的单测，那这里就加个 jest，然后就会在提交代码时自动执行单元测试了，执行不通过就提交不了代码。

这里有两点要注意下：

一个是顺序问题，建议把执行时间短的操作放在前面，目的是让我们在提交代码时尽早地得知不让提交，比如这里我们把检查改动文件的代码规范放在了执行单元测试之前。

这样做有什么好处呢？举个例子，如果把执行单元测试放在检查代码规范之前，那么假设我们改动的代码没有 bug 只是有代码规范问题，但是在我们提交代码时，我们会发现我们等了好长一段时间的单元测试的成功执行之后，才看到检查代码规范报错了，然后我们去修改代码规范，再提交，又得先等好长一段时间的单元测试才能看到我们是不是修改好了代码规范。

这个速度快的任务优先执行的思路放在别的地方也适用，可以举一反三。

另一个要注意的是，在 pre-commit 这个钩子里执行多个操作时是用 && 连接多个操作，这一点在 husky 的文档里没有写，而且我当时网上搜也没搜到，是自己反复试，试出来的。

commit message 规范

至此，我们就在 commit 时检查了代码规范又检查了单元测试，检查上瘾了，让我们看看还有没有什么可以让我们在 commit 时检查检查的。

一看，果然还有，commit message 规范也可以让我们检查检查。

当然，我们也不是真的因为检查上瘾了才检查 commit message 规范的，我们也是因为检查它有重大意义才检查的。

如果不检查，当多人开发一个项目时，我们可以想象一下，当我们在提交记录里看到风格迥异的 commit message 时会是什么感受，尤其是过了一段时间回头来看的时候。

这样的提交记录是不利于代码的维护的，另外，之后会讲到的、也很重要的 CHANGELOG 是强依赖有规范的 commit message 的。

所以，确实有必要检查 commit message 规范。

那怎么检查呢？

答案是用 commitlint。

commitlint 是什么？
commitlint 是一个检查 commit message 的工具，包括一系列 npm 包，其中的核心是 @commitlint/cli。

commitlint 怎么用？
先把 commitlint 的核心 npm 包 @commitlint/cli 装上，再装个定义 commit message 规范的 npm 包。

这用法和 eslint 类似，都是安装个检查工具再安装个规范定义，有一点稍微不同的是，eslint
的检查工具有内置的规范，可以不另外装规范定义，而 commitlint 的检查工具没有内置的规范，必须另外装规范定义。

装好包之后就该去 package.json 文件里配置了：

我们也是把 commitlint 配合 husky 一起使用。husky 提供了名叫 commit-msg 的钩子，在这个钩子中执行的操作可以获取到 commit message。像上图中那样配置就可以了，各个参数的具体含义在这里就不详细说啦，如果感兴趣，可以去看看 commitlint 的官方文档：https://commitlint.js.org/#/guides-local-setup

上面是配置了 commit 时要检查 commit message，然后还得配置 commit message 的规范：

都配置好后，效果是这样的：

commit 时，commit message 不符合我们配置的规范，就报错了，于是 commit 不成功。

持续集成（CI）

目前为止，关于检查，我们讲完了代码规范、单元测试、commit message 的检查，有没有发现它们有一个共同点？

都是在本地提交代码时检查的。

这样有问题吗？

嗯，有问题。

大家可能都知道，在 commit 时可以通过加上 -n 或者 --no-verify 来跳过检查。另外，有时候会因为一些未知力量，本地检查挂了，仿佛不存在一样。

这两种情况都会导致代码没经过检查就提交上去了，于是乎，可能就会在不知情的情况下，一个代码不规范、有 bug、commit message 也不规范的提交进了代码库。

哦豁，那怎么办？

没关系，不用怕，因为我们有持续集成这个大杀器！

持续集成是什么？
这个牛皮哄哄的持续集成到底是什么？

这里抄一下百度百科的定义：

一种软件开发实践，即团队开发成员经常集成他们的工作，通常每个成员每天至少集成一次，也就意味着每天可能会发生多次集成。
每次集成都通过自动化的构建（包括编译，发布，自动化测试）来验证，从而尽早地发现集成错误。

有点抽象，没关系，我们可以先非常不准确地把持续集成简单理解成代码提交上去后的检查。

这个就是解决刚才说的代码没有经过本地检查就提交上去了的问题的关键。如果我们把代码提交到 GitHub 上后，也能触发持续集成，然后我们在持续集成里再次检查代码规范、单元测试、commit message 规范，问题就解决了。

GitHub 上的持续集成是这样的：

这是我给 San CLI 提的一个 pull request（PR），可以看到有 6 个 checks，这 6 个 checks 就是 6 个持续集成任务了。

Travis CI VS GitHub Action
为了实现在 GitHub 上的持续集成，有两种方式：

1. 使用第三方工具，其中市场份额最大的是 Travis CI；
2. 使用 GitHub 自己搞的持续集成工具 GitHub Action。

San CLI 一开始用的是 Travis CI，确实能解决问题，但是后面换成了 GitHub Action。为什么要折腾呢？是因为 Travis CI 有一些问题：

1. 运行耗时：在 San CLI 的场景下，Travis CI 耗时是 GitHub Action 耗时的差不多 2 倍；
2. 查看日志：可能是我的公司网络的问题，Travis CI 的查看日志的页面不仅慢还有时会挂。比如我发起了个 PR，Travis CI 的持续集成没通过，于是我点进去 Travis CI 的页面看日志，看看具体是因为什么而没通过，然后我好去改，但是这个查看日志的页面等半天了还在 loading。
3. 是否官方：同等条件下，一般都是优先考虑官方的嘛，更何况对于 San CLI 来说，Travis CI 好像还不如 GitHub Action 呢。

但是！虽然我们说了一些 GitHub Action 的优点，但是！Travis CI 历史悠久，而 GitHub Action 是最近两年才出来的新东西，在功能方面，Travis CI 目前绝对比 GitHub Action 强大，而且更完善，只不过对于 San CLI 来说意义不是很大，因为 San CLI 的场景目前还比较简单。

GitHub Action 怎么用？
既然决定了用 GitHub Action 了，我们今天就不管 Travis CI 的用法，只看 GitHub Action 怎么用：

它的原理和 Issues 模板的原理类似，在上图中的第一个红框中，可以看到，也是和 Issues 模板一样，要在项目的 .github 文件夹下新建一个文件夹，只不过这个文件夹叫 workflows 了，就是工作流的意思，然后在这个 workflows 文件夹下新建 yml 类型的文件并按照 GitHub Action 的要求定义持续集成就可以了。

我们这里以在持续集成中执行单元测试为例简单看下怎么定义。

上图中第二个红框中的内容的意思是，当往 master 分支上 push 或者发起 pr 时，会触发持续集成。

上图中第三个红框中的内容的意思是，触发持续集成后，先执行 yarn，也就是安装 npm 包，安装完了就执行 yarn test，也就是执行单元测试。

没了，是不是 GitHub Action 还挺简单的。代码规范和 commit message 规范的检查也是类似的，这里就不啰嗦了。

当我们配置好持续集成后，以后我们的每次提交的旁边，就都会有个绿色的勾或者红色的叉了（下图中第二个红框）：

勾就是持续集成通过了，叉就是持续集成不通过，点开来就能看到持续集成的任务都有哪些（上图中第三个红框），再点击 Details 就能看到持续集成的日志了。

上图中的上部的 tab 栏有一个名叫 Actions 的 tab，从那里点进去也能看到所有的持续集成的日志。

点进去后，可以看到日志是这个样子的，我们感受下：

如果持续集成不通过，我们还会收到邮件提醒：

所以不用一直盯着持续集成等运行结果，很方便。

GitHub Action 注意事项

虽然前面对 GitHub Action 的介绍让人感觉岁月静好，但是当初我为了把 San CLI 的 Travis CI 完美换成 Github Action，差点怀疑人生了，因为有的地方还是挺坑的。

以下列一下我整理的 GitHub Action 的注意事项，希望能帮助后人省点心：

1. 尽量只实现常规操作：用 GitHub Action实现常规操作很容易，比如执行单元测试，但是如果要实现骚操作可能就要掉进大坑里了，而且爬不出来。比如想要在提 PR 后，拿到 PR 里所 有 commit 的 commit message，然后检查它们。其实这操作应该也不算很骚，可能 Github Action 还是太年轻了，还在不断完善中。
2. Action Marketplace：GitHub Action 有个 Action Marketplace 的概念，意思是 action 集市，它的作用就像它的名字一样，里面有很多现成的 Github Action 实现，甚至是官方的实现，我们可以直接拿来用，也正是因为这点，用 Github Action 实现常规操作还是很友好的。
   缓存依赖：在 San CLI 的应用场景中，持续集成中耗时最长的部分是安装依赖，所以如果我们能在持续集成中把安装的依赖缓存起来，不用每次持续集成都重新安装，那可以极大地缩短总耗时。幸运的是，Github Action 也是支持缓存依赖的，而且在 Action Marketplace 里面有现成的可用。
3. 了解 Shell：如果我们真的想实现一些骚操作，我就建议先把 shell 的语法好好看一看，因为写 GitHub Action 时最难和最主要的部分，我觉得就是写 shell。不好好看 shell 文档可能比较容易掉坑里，比如 shell 在定义变量时，变量名和等号之间是不能有空格的，这可能和我们熟悉的所有编程语言都不一样，我就掉这坑里了，而且当时因此报的错，我没记错的话，还挺莫名其妙的，反正没让我意识到是空格问题，导致花了我不少时间。
4. 有的 Git 命令在本地执行的效果和在 GitHub Action 执行的效果不一样：比如 git log --format=%B -n2，这条命令在本地执行会输出最近的 2 条 commit message，而在 Github Action 里执行只会输出最近的 1 条commit message。

GitHub 徽章

持续集成这个大杀器讲完了，接下来讲个轻松一点的，GitHub 徽章。

GitHub 徽章 是什么？
虽然大家可能听这个名字不知道是什么，但是大家肯定都见过 GitHub 徽章：

图中红框中的部分就是 GitHub 徽章。

GitHub 徽章有什么用？
一是给别人提供我们的开源项目的相关信息，比如用了什么工具、现在有几个 Issues、开源证书类型等等。

二是给人一种高大上的感觉，同时让人感觉我们的开源项目靠谱。

另外，这个 GitHub Action 徽章可以是动态的，比如上图中的 Issues 数量徽章，是会随着 Issues 的真实数量的变化而变化的。

GitHub 徽章怎么弄？
其实 GitHub 徽章就是一个图片链接，把这个链接放在项目的 README.md 文件里就可以了。

至于这个图片链接该怎么获取，主要应该是两种获取方式：

1. 官方方式：比如我们想搞个 Github Action 的徽章，像上图中的第一个徽章那样，就可以先去看看 Github Action
   的官方文档里有没有提供徽章；
2. shields.io：如果官方没有提供，就得用到这一种获取方式了，这是个第三方网站，它提供了各种各样的 Github 徽章。

监控 npm 包

这是倒数第三块砖头了，就要全部抛完了，胜利在望。

监控 npm 包是什么意思？
监控 npm 包的意思其实是监控我们的开源项目依赖的 npm 包，当依赖的某个版本的 npm 包有 bug 时，就提示我们升级到解决了 bug 的版本。

为什么要监控 npm 包？
而之所以要监控 npm 包，是为了在潜在的风险变为现实之前，把它扼杀在摇篮里。

怎么监控 npm 包？
答案是使用 Snyk。

Snyk 是什么？
Snyk 是一个第三方工具，就是监控 npm 包用的，可以友好地集成进 GitHub：

每当我们往 GitHub 上提交了代码，就会触发 Snyk，Snyk 就会检查 package.json 文件，看看各个 npm 包用的版本有没有问题。

除了提交代码时的检查，Snyk 也会进行日常检查，当检查出问题了，就会给我们发邮件：

这个邮件提醒我们该把 webpack 从 4 升级到 5 了，在提醒的同时，Snyk 还会自动创建 PR 来解决升级问题：

不过 Snyk 只是帮我们把版本号改了，像是版本升级带来的 API 的调用方式的变化这些，Snyk 不会帮我们改，我们要自己改。

Snyk 怎么用？
其实，我觉得，一般没必要用 Snyk。

San CLI 引入 Snyk 也有大半年了，在此期间，Snyk 也发起了一些 PR，但是基本都被直接 close 掉了，所以 Snyk 貌似没有发挥它应有的提前修复 npm 包潜在的风险的作用。

之所以 Snyk 发起的 PR 基本都被直接 close 掉了，是因为：

1. 我们可以试想一下，一个 npm 包的某个版本，我们用得好好的，突然要我们升级，会不会升出了 bug 呢？倒不是一定就是升级后的 npm 包本身有 bug，还可能是我们没有做好升级后的适配。
2. 另一方面，即使没有升出 bug，那也不能说明不升级就一定会出 bug，可能我们不升级也不出 bug 呢，那不是浪费时间升级吗？而且有时候升级会是 break change（即不向下兼容的升级），为此我们必须修改我们的代码才能适配升级，这工作量不一定小，而且修改完还得测试。

所以，用 Snyk 这东西，感觉哦，好像就是给自己找麻烦的。

出于节省人力、为公司省钱的目的，从投入产出比的角度考虑，在开源项目的用户量不是那么大的情况下，大家其实应该不会想要用 Snyk。

当然，Snyk 也不是一无是处，引入它至少好歹也能让我们的开源项目显得高级了些。所以，如果真的想引入 Snyk，那照着 Snyk 官网的友好的指引做就行了，这里就不详细介绍了。

CHANGELOG

到倒数第二块砖头了，CHANGELOG。

CHANGELOG 是什么？
CHANGELOG 就是版本更新日志。

更新日志是一个以时间为倒序的列表，以记录一个项目中所有版本的显著变动。—— 忘了从哪抄来的了。

我们先直观感受下 CHANGELOG 是怎样的，这是 San SSR 的 CHANGELOG：

为什么要有 CHANGELOG？

为了让用户和开发人员更简单明确地知晓项目在不同版本之间有哪些显著变动。
人人需要更新日志，无论是用户还是开发人员，都会关心软件包含什么。当软件有所变动时，大家希望知道改动是为什么、以及怎么进行的。 ——
来源于网络。

所以 CHANGELOG 很重要。

CHANGELOG 怎么弄？
人工编辑吗？也不是不行，但是费劲嘛，像上图中 San SSR 那样的 CHANGELOG 是可以自动生成的。

自动生成 CHANGELOG 可以使用 semantic-release，这是个 npm 包。semantic 的意思是 “语义的”，而 release 的意思是 “发布”。顾名思义，semantic-release 是用来自动地、语义地发布 npm 包的。

semantic-release 的文档里有一张图我觉得很搞笑：

这张图的内容是：一个面目狰狞的机器人，举着一个牌子，牌子上写着 “杀掉所有人类”。我猜这张图是想表达 semantic-release 的目标是想让发布 npm 包完全自动化，不需要人参与。挺有意思的。

semantic-release 会根据 commit message 自动确定版本号，这个功能是它主要的、而且是必选的功能，而自动生成 CHANGELOG 的功能倒是可选的。

如果我们想要用 semantic-release 自动生成 CHANGELOG 的功能，有一个前提，就是我们的 commit message 要符合 semantic-release 支持的业内流行的规范，因为 semantic-release 是根据 commit message 来生成 CHANGELOG 的。semantic-release 支持的业内流行的规范有这些

得用这些 commit message 规范才能用 semantic-release 自动生成 CHANGELOG。

CHANGELOG 的扩展资料
《如何维护更新日志》：https://keepachangelog.com/zh-CN/1.0.0/

贡献指南

啊，最后一块砖头了 —— 贡献指南。

贡献指南是什么？
贡献指南的作用是可以告诉别人如果想给我们的开源项目做贡献，比如提 PR 和 Issues，该怎么做，比如怎么在本地运行我们的项目、怎么开发调试等等。

如果我们配置了贡献指南，那当别人想给我们提 PR 或 Issues、然后在 Github 上进入我们项目的 PR 页面或 Issues 页面时，就会看到关于我们的项目的贡献指南的提示：

别人点进去，就能看到具体该怎么给我们做贡献了。

怎么设置贡献指南？
贡献指南的设置，和 Issues 模板的设置一样，也是在项目的 .github 文件夹下新建一个文件。文件名是 CONTRIBUTING.md，然后在这个 Markdown 文件里写贡献指南就可以了。

贡献指南的扩展资料
贡献指南的内容具体怎么写呢？这里提供两个参考资料：

1. GitHub 官方文档：https://docs.github.com/en/free-pro-team@latest/github/building-a-strong-community/setting-guidelines-for-repository-contributors
2. 《开源软件指南》的贡献指南部分：https://opensource.guide/starting-a-project/#writing-your-contributing-guidelines 整个《开源软件指南》都写得挺好的，所以除了贡献指南部分，别的部分也可以看看。

总结

终于到了振奋人心的总结了！

回顾下今天的 9 块砖头，它们分别是：

1. Issues 模板
2. 代码规范
3. 单元测试
4. commit message 规范
5. 持续集成（CI）
6. GitHub 徽章
7. 监控 npm 包
8. CHANGELOG
9. 贡献指南

想提高自己的项目（尤其是开源项目）的前端工程能力的同学，可以结合自己的项目的情况，试试这些实践。假一赔十。

另外，就像文章开头所说，我受限于自身水平和经验，这文章如果能起到抛砖引玉的作用，我就心满意足了，所以，想必大家在落地这些实践的过程中，一定会产生出更优秀的实践。

最后

感谢你阅读到了这里，以上便是《San CLI 的前端工程能力建设》的全部内容。

我相信我所在团队的开源项目有一天终会：

走出百度，走向中国！
走出中国，走向地球！
走出地球，走向宇宙！

San 是百度自研的高性能 MVVM 框架，目前已落地百度 APP 核心业务，服务于亿级用户，开源社区已有 37 位贡献者，Star 数量超过 4.4K。开源维护不易，如果你看到这行小字，求给我们一个 Star

San: https://github.com/baidu/san
San CLI: https://github.com/ecomfe/san-cli
San DevTools: https://github.com/baidu/san-devtools

期待你的加入

百度开发者中心已开启征稿模式，欢迎开发者登录developer.baidu.com进行投稿，优质文章将获得丰厚奖励和推广资源。