San CLI 的前端工程能力建设
#595
Replies: 0 comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
{{ message }}
-
摘要：如何维护在 GitHub 上开源的前端项目？（发文章时把这句从正文中删除）
前言
我所在的团队需要负责许多前端开源项目，比如命令行工具
san-cli、调试工具san-devtools、组件库santd、单文件组件 loadersan-loader、热更新 loadersan-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 模板，这些资料或许会有帮助：
代码规范
接下来是第二块砖头，代码规范。
我们都知道代码规范很重要，这不用多说，但是光靠书面约定和 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 只是有代码规范问题，但是在我们提交代码时，我们会发现我们等了好长一段时间的单元测试的成功执行之后，才看到检查代码规范报错了，然后我们去修改代码规范，再提交，又得先等好长一段时间的单元测试才能看到我们是不是修改好了代码规范。
这个速度快的任务优先执行的思路放在别的地方也适用，可以举一反三。
commit message 规范
至此，我们就在 commit 时检查了代码规范又检查了单元测试，检查上瘾了，让我们看看还有没有什么可以让我们在 commit 时检查检查的。
一看，果然还有，commit message 规范也可以让我们检查检查。
当然，我们也不是真的因为检查上瘾了才检查 commit message 规范的，我们也是因为检查它有重大意义才检查的。
如果不检查，当多人开发一个项目时，我们可以想象一下，当我们在提交记录里看到风格迥异的 commit message 时会是什么感受，尤其是过了一段时间回头来看的时候。
这样的提交记录是不利于代码的维护的，另外，之后会讲到的、也很重要的 CHANGELOG 是强依赖有规范的 commit message 的。
所以，确实有必要检查 commit message 规范。
那怎么检查呢？
答案是用 commitlint。
commitlint 是什么？
commitlint 是一个检查 commit message 的工具，包括一系列 npm 包，其中核心的 npm 包是 @commitlint/cli。
commitlint 怎么用？
先把 commitlint 的核心 npm 包 @commitlint/cli 装上，再装个定义 commit message 规范的 npm 包。
装好包之后就该去 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 上的持续集成，有两种方式：
San CLI 一开始用的是 Travis CI，确实能解决问题，但是后面换成了 GitHub Action。为什么要折腾呢？是因为 Travis CI 有一些问题：
但是！虽然我们说了一些 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 的注意事项，希望能帮助后人省点心：
git log --format=%B -n 2，这条命令在本地执行会输出最近的 2 条 commit message，而在 Github Action 里执行只会输出最近的 1 条 commit message。GitHub 徽章
持续集成这个大杀器讲完了，接下来讲个轻松一点的，GitHub 徽章。
GitHub 徽章 是什么？
虽然大家可能听这个名字不知道是什么，但是大家肯定都见过 GitHub 徽章：
图中红框中的部分就是 GitHub 徽章。
GitHub 徽章有什么用？
一是给别人提供我们的开源项目的相关信息，比如用了什么工具、现在有几个 Issues、开源证书类型等等。
二是给人一种高大上的感觉，同时让人感觉我们的开源项目靠谱。
另外，这个 GitHub Action 徽章可以是动态的，比如上图中的 Issues 数量徽章，是会随着 Issues 的真实数量的变化而变化的。
GitHub 徽章怎么弄？
其实 GitHub 徽章就是一个图片链接，把这个链接放在项目的 README.md 文件里就可以了。
至于这个图片链接该怎么获取，主要应该是两种获取方式：
监控 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 掉了，是因为：
所以，用 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 文件里写贡献指南就可以了。
贡献指南的扩展资料
贡献指南的内容具体怎么写呢？这里提供两个参考资料：
总结
终于到了振奋人心的总结了！
回顾下今天的 9 块砖头，它们分别是：
想提高自己的项目（尤其是开源项目）的前端工程能力的同学，可以结合自己的项目的情况，试试这些实践。假一赔十。
另外，就像文章开头所说，我受限于自身水平和经验，这文章如果能起到抛砖引玉的作用，我就心满意足了，所以，想必大家在落地这些实践的过程中，一定会产生出更优秀的实践。
最后
感谢你阅读到了这里，以上便是《San CLI 的前端工程能力建设》的全部内容。
我相信我所在团队的开源项目有一天终会：
走出百度，走向中国！
走出中国，走向地球！
走出地球，走向宇宙！
Beta Was this translation helpful? Give feedback.
All reactions