如何打造规范的开源项目workflow

[eJayYoung]

前言

一般开源项目正常的开发流程是：

• 初始阶段
  • 创建仓库
  • git clone repository 到本地
  • 添加修改代码
  • 提交commit message
  • push到 github 仓库
• 迭代阶段
  • 切换开发分支
  • 开发新功能
  • 完善测试用例
  • 日常修复bug
  • 文档的完善
• 发布阶段
  • 打tag
  • npm publish

表面看起来没有什么毛病，但是要做一个规范的、多人协作的、可维护的开源项目，开发流程上还是有不少细节的点需要我们来打磨。

那在多人协作的开发过程中到底会碰到哪些无法统一的行为？我们该如何解决这些问题？

• 代码检查
• 提交信息和修改日志
• 版本迭代
• 执行落地

代码检查

问题

这是一个老生常谈的问题，语句结尾要不要分号？缩进是空格还是tab？是2个还是4个？

解决步骤

目前业界比较统一的做法是使用eslint

作为项目owner，建议全局安装eslint：

npm install eslint -g

之后就可以在本地的项目仓库中，执行命令：

eslint --init

可以有三种选择：

• 选择一个流行的样式规范
  • Airbnb
  • Standard
  • Google
• 自定义的代码习惯
• 检查你项目之前的代码样式

常规的前端项目建议选用Standard规范（虽然不是真正的规范，但是属于业内默认的规范吧），初始化如下：

｛
   "devDependencies": {
        "eslint": "^4.19.1",
        "eslint-plugin-import": "^2.13.0",
        "eslint-config-standard": "^11.0.0",
        "eslint-plugin-standard": "^3.1.0",
        "eslint-plugin-promise": "^3.8.0",
    }
｝

React项目建议选用Airbnb规范，初始化后的package.json如下：

{
    "devDependencies": {
        "eslint": "^4.19.1",
        "eslint-config-airbnb": "^17.0.0",
        "eslint-plugin-import": "^2.13.0",
        "eslint-plugin-react": "^7.10.0",
        "eslint-plugin-jsx-a11y": "^6.1.1"
    }
}

如果需要单独定义一些规则，可以在根目录下新建一个.eslintrc文件，见具体配置。

如果需要忽略一些文件，可以在根目录下新建一个.eslintignore文件，见具体配置。

最后在package.json中加上命令

{
    "scripts": {
        "lint": "eslint --ext .jsx,.js ."
    }
}

这样项目成员只需要操作以下步骤

• vscode中安装eslint扩展（以后使用vscode打开项目都会检测项目中的.eslintrc文件进行实时lint提示）
• cd project && npm install

衍生问题1

如果是之前的老项目接入了eslint，同时加入了git hook来强制执行，会导致之前的错误没修复完无法提交，那有没有办法只检测当前修改的文件呢？

解决方案

目前社区比较成熟的方案是lint-staged

首先在项目中安装lint-staged和husky

husky是用来实现绑定git hooks的一个库，后面会提到

npm install -D lint-staged husky

然后在项目中的package.json中添加

{
  "scripts": {
    "precommit": "lint-staged"
  },
  "lint-staged": {
    "*.js": ["eslint --fix", "git add"]
  }
}

以上操作在我们正常的开发流程中做了什么呢？

在git add .之后，git commit之前，会触发precommit钩子，执行lint-staged，然后lint-staged会只检查经过暂存区的文件，根据它的配置项执行命令。

例如上面的配置，就是针对所有修改过的以js为后缀的文件，依次执行eslint --fix,git add两个命令，帮你自动修复掉eslint的错误，再将修改添加到暂存区，然后一起commit到工作区。

衍生问题2

eslint只是作为代码检测的工具，并没有规范开发时的行为，那可不可以在编辑器上进行规范呢？

解决方案

主流方案是使用EditorConfig

首先在项目根目录新建一个.editorconfig文件，根据EditorConfig支持的大部分属性自行定义

然后再给编辑器安装EditorConfig的插件，就可以使用了，插件安装可见官方下载

提交信息和修改日志

问题

• commit message

  在实际开发的过程中，其实大家对自己的修改内容并没有很好的界定，也没有统一的格式化，导致了很多时候我们无法根据commit message来快速定位修改内容。

• changelog

  其实一个项目新增功能，修复bug等信息都需要记录下来，便于区别不同版本的新特性，然后手动维护记录通常容易忘记，导致这一部分经常没有持续的更新。

解决步骤

目前社区使用最广的方案是Commitizen和conventional-changelog配合使用。

顾名思义

• commitizen就是用来规范commit message
• conventional-changelog可以根据格式化的commit message来自动生成CHANGLOG.md

commitizen

有两种开发方式：

• 全局安装（墙裂推荐）：

  npm install commitizen -g
  

  然后安装commitizen的adpater，比如cz-conventional-changelog(AngularJS的提交惯例)

  npm install -g cz-conventional-changelog
  

  然后你就可以使用git cz来替换git commit命令来进行代码提交了。

  

• 项目安装：

  让你的项目让别人更友好的接入commit规范，你不可能强制要求别人全局安装一个工具，就只能在开发依赖里添加

  作为项目owner，默认已经全局安装了commitizen，然后执行：

  commitizen init cz-conventional-changelog --save-dev --save-exact
  

  以上命令做了三件事：

  • 在本地安装cz-conventional-changelog模块

  • 保存到package.json的devDependencies中

  • 在package.json的根层级添加了config.commitizen

    "config": {
      "commitizen": {
      	"path": "cz-conventional-changelog"
      }
    }
    

  为了保证其他贡献者的仓库中也能使用同一版本的commitizen，最好在仓库安装开发依赖

  npm install -D commitizen
  

  然后在项目的package.json中的scripts里加上

  {
    "scripts": {
      "cz": "git-cz"
    }
  }
  

  这里需要注意一点，如果你在scripts脚本中定义了{"commit": "git-cz"}的话，precommit钩子会在真正commit之前执行两次，见husky issue，所以自定义另外一个名称就好了。

  然后项目contributors就可以通过npm run cz来愉快的提交格式化的commit message了。

changelog

还是国际惯例，全局安装

npm install -g conventional-changelog-cli

切换到项目目录后，执行

conventional-changelog -p angular -i CHANGELOG.md -s -r 0

就可以根据commit message 自动生成一份CHANGELOG.md文件

再配合上package.json里的scripts

{
    "scripts": {
        "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0"
    }
}

只需要执行npm run changelog就行了，是不是很简单？

但是该在什么时机执行上面这条命令呢？

根据文档推荐的工作流，在修改package.json中的版本之后执行最合适。

不过在下面的版本控制会将工作流改成用npm version来实现。

{
    "scripts": {
        "version": "npm run changelog && git add CHANGELOG.md"
    }
}

版本迭代

问题

传统版本迭代步骤

• package.json中修改递增version

• git add -A

• git commit -m "update version"

• git push

• git tag <tag version>

• git push --tag

• npm publish

流程过于繁冗，很容易遗漏打tag那一步。

解决步骤

使用npm version命令，从文档上我们可以看到其依据semver支持了大部分alias：

npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease | from-git]

例：初始版本为1.0.0

npm version prepatch //预备补丁版本号 v1.0.1-0

npm version prerelease //预发布版本号 v1.0.1-1

npm version patch //补丁版本号 v1.0.2

npm version preminor //预备次版本号 v1.1.0-0

npm version minor //次版本号 v1.1.0

npm version premajor //预备主版本号 v2.0.0-0

npm version major //主版本号 v2.0.0

当在仓库中执行npm version时，会自动提交git commit并打上git tag。

当使用-m参数时，就可以自定义发布版本的信息，其中%s可以用来代替当前版本号

npm version patch -m "upgrade to %s for reasons"

这样以后版本迭代只需要以下步骤

• npm version patch | minor | major | ...etc
• git push
• git push --tag
• npm publish

衍生问题

如何发布beta，rc，alpha版本呢？如果发布了，应该如何安装？

解决方案

首先我们要理解这些版本的含义

• alpha：内部测试版本
• beta： 公开测试版本
• rc： 候选版本（Release Candidate）

然后将package.json的version改成x.x.x-beta

配合npm publish --tag <tag>，我们可以发布对应的dist-tag

举个例子：

使用npm publish --tag beta发布后，然后就可以使用npm install <pkg>@beta安装对应版本的包。

我们可以通过npm dist-tag ls <pkg> 来查看包的dist-tag

{
    latest: 1.0.1, // 这就是npm publish默认发布的tag
    beta: 1.0.1-beta
}

当我们的beta版本稳定后，可以使用npm dist-tag add x.x.x-beta latest设置为稳定版本。

执行落地

问题

正常工作流我们分为两块：

• 开发流程

  在开发流程中，我们需要保障：

  • 代码lint通过
  • 单元测试通过
  • 规范的提交信息（optional）

• 发布流程

  在发布流程中，我们需要保障：

  • 打包通过
  • 生成CHANGELOG
  • 规范的版本号迭代

解决方案

根据上述两种流程，我们可以使用git hook和npm hook

开发流程

在上面已经介绍过，我们选用husky作为git hook的实现工具

npm install -D husky

代码lint和单元测试，我们可以放到precommit中执行，修改钩子执行的命令

{
    "scripts": {
    	"test": "jest",
        "precommit": "lint-staged && npm run test"
    }
}

commit message lint的解决方案：commitlint

npm install -D @commitlint/config-conventional @commitlint/cli

然后在package.json中配置钩子

{
    "scripts": {
        "commitmsg": "commitlint -E GIT_PARAMS"
    },
    "commitlint": {
        "extends": ["@commitlint/config-conventional"],
        "rules": {
            "subject-case": [0]
        }
    }
}

这样我们在git commit执行之前验证了eslint是否通过，测试用例是否通过，commit message是否符合规范。

当然也可以在commit后面添加参数--no-verify来跳过commit message lint

发布流程

• bump version

  修改package.json

  {
      "scripts": {
          "version": "npm run changelog && git add CHANGELOG.md",
          "postversion": "git push && git push --tags"
      }
  }
  

  然后执行npm version patch | minor | major

• npm publish

  添加prepublishOnly hook

  {
      "scripts": {
          "prepublishOnly ": "npm run build"
      }
  }
  

  然后执行npm publish

执行npm version命令时会依次执行npm script中的preversion，version，postversion三个钩子，具体详情见文档

prepublishOnly只会在npm publish之前执行，prepare和prepublish都会在npm publish和不带参数的npm install时执行，见npm script文档

结尾

至此，我们已经基本打造了一个比较完善的开源项目workflow。

对于项目开发者来说，只需要做以下几点改变：

• 编辑器安装eslint和editorconifg插件
• 使用git cz提交信息
• 使用npm version patch | minor | patch来进行版本迭代

是不是更简单方便了呢？

欢迎大家拍砖，广纳良言！

参考文献

• eslint中文官网
• Commitizen
• conventional-changelog
• Commit message 和 Change log 编写指南
• npm version
• npm publish
• npm dist-tag
• husky
• commitlint
• npm scripts 使用指南

[yukap6]

666

[CurtisTong]

666

[caiyongmin]

为大佬打 call

[youngBrain1893]

感觉 EditorConfig 的约束都能使用 prettier 和 vscode 的配置实现

[eJayYoung]

@youngBrain1893 其实是类似功能的插件，editorConfig也要依赖vscode的插件，prettier是支持一键格式化吧

[Adherentman]

感觉eslint + prettier 在pre-commit 的时候也把格式化做掉。。

[eJayYoung]

感觉eslint + prettier 在pre-commit 的时候也把格式化做掉。。
感谢大佬谏言，之前写这篇文章时，只做了eslint的调研，prettier只是在vscode中本地使用，确实在precommit中加上会更好些

[Adherentman]

有个问题。。在eui里自己去写generate而不用webpack有什么优点吗？

[eJayYoung]

有个问题。。在eui里自己去写generate而不用webpack有什么优点吗？

😅，目前eui不是我在开发。
不过从代码看思路，现在eui也只做了一个copy file的事儿，可能是用于规划整包里子包的文件名吧。本来我之前是计划用webpack打包就行的。
不过子包发布的时候都已经用webpack+babel打过包了，所以整包这块要做的事情最多就是整合入口。

[Adherentman]

😅，目前eui不是我在开发。
不过从代码看思路，现在eui也只做了一个copy file的事儿，可能是用于规划整包里子包的文件名吧。本来我之前是计划用webpack打包就行的。
不过子包发布的时候都已经用webpack+babel打过包了，所以整包这块要做的事情最多就是整合入口。

感谢，最近在研究如何写一个组件库并发布。。发现有太多的结构。

[eJayYoung]

sweat_smile，目前eui不是我在开发。
不过从代码看思路，现在eui也只做了一个copy file的事儿，可能是用于规划整包里子包的文件名吧。本来我之前是计划用webpack打包就行的。
不过子包发布的时候都已经用webpack+babel打过包了，所以整包这块要做的事情最多就是整合入口。

感谢，最近在研究如何写一个组件库并发布。。发现有太多的结构。

是的，我们这边做，主要也是参考antd和uxcore的，可以尝试玩玩lerna。
这是我对eui的架构设计图，可以参考一二

[Adherentman]

@eJayYoung 是的。。我基于lerna。。packages里有各种xxx-component-xxx文件夹...感谢！

[Adherentman]

@eJayYoung 有以下疑问。。询问下。 不管是否基于lerna，然后我们把所有组件分成一个包的好处是什么？是按需下载减少项目的大小吗？

[eJayYoung]

@eJayYoung 有以下疑问。。询问下。 不管是否基于lerna，然后我们把所有组件分成一个包的好处是什么？是按需下载减少项目的大小吗？

不是的，放在一个包里的好处是，解决各个组件对于依赖包的版本控制问题，不然每个组件依赖其他组件还得手动维护版本。

[Adherentman]

@eJayYoung 有以下疑问。。询问下。 不管是否基于lerna，然后我们把所有组件分成一个包的好处是什么？是按需下载减少项目的大小吗？

不是的，放在一个包里的好处是，解决各个组件对于依赖包的版本控制问题，不然每个组件依赖其他组件还得手动维护版本。

最近折腾死了。。先js写，发现没法支持ts。然后用ts，发现各种类型定义加继承React.xxxxx要搞半天。然后还是转到了js。现在发现webpack打包出来太多无用的code，又想用rollup但是想了想，还是觉得就该直接babel去转就好了。。坑啊~