bsg/README.md

Lint all in one tool for BSG-FE

# BSG

Lint all in one tool for BSG-FE.

## 介绍

BSG 是一个用于 BSG 前端团队统一规范的工具，它集合了每个项目中必需的规范工具，包括语法规则规范工具、代码风格规范工具、文件命名规范工具、提交格式规范工具，并升华了工具的能力。它让开发者无需在每个项目中重复地去做复杂的规范工具配置，并统一了不同开发者、不同业务线之间的规范差异，让整个 BSG 前端团队的前端规范做到统一并提升了项目的开发效率。

## 安装

```bash
$ npm i -D bsg
```

安装前请先卸载 eslint、stylelint 等相关依赖、删除相关配置文件（尤其注意 webpack 配置，比如过时的 eslint-loader 等，以免打包出错），精简 package.json 和项目目录。

## 基本使用

### lint

本工具提供了 `lint` 一条龙服务，会对 `.js`, `jsx`, `.ts`, `.tsx`, `.vue`, `.css`, `.less`, `.scss` 文件进行代码格式检查（强制），会对所有文件进行命名格式检查（可选）。

#### 主动使用 `lint`

只需在 `package.json` 的 `scripts` 中添加或者替换：

```json
// package.json
{
  "scripts": {
    "lint": "bsg lint"
  }
}
```

然后运行 `npm run lint` 即可。

#### 提交时自动检测

安装 `husky`：

```bash
$ npm i -D husky
```

在 `package.json` 的 `scripts` 中添加：

```json
// package.json
{
  "scripts": {
    "prepare": "husky install && echo 'PATH=$PATH:'$PATH >> .husky/_/husky.sh"
  }
}
```

运行：

```bash
$ npm run prepare
```

添加钩子：

```bash
$ npx husky add .husky/pre-commit "npx --no-install bsg lint-staged"
```

完成上述步骤之后就可以在提交时自动对提交的文件做规范检查并自动格式化代码了。

#### 文件/文件夹命名检测（可选）

只需要在项目根目录添加 `.ls-lint.yml` 即可开启文件/文件夹命名检测功能。

推荐的配置：

```yml
ls:
  src:
    .dir: kebab-case
    .js: kebab-case
    .ts: kebab-case
    .scss: snakecase|kebab-case
    .d.ts: kebab-case
    .scss.d.ts: snakecase|kebab-case

  src/**/components/**/*:
    .dir: PascalCase
    .vue: lowercase|PascalCase
```

老项目可以根据项目文件/文件夹已有的命名格式去收窄后续的命名格式，尽量做到项目内的统一。

新项目建议都开启此功能，从项目初期就去控制命名，以免日后难以控制。

### commitlint

工具提供了开箱即用的 `bsg commit` 规范检测能力。

在完成了上文 `husky` 的安装流程之后，添加钩子：

```bash
$ npx husky add .husky/commit-msg "npx --no-install bsg commitlint"
```

即可享用 `commit` 检测服务！

### changelog

在遵守了 `bsg` 规范之后，就可以享受遵守规范带来的便利了，工具提供了基于 `bsg commit` 规范的 `changelog` 自动生成工具，只需要在 `package.json` 的 `scripts` 中添加：

```json
// package.json
{
  "scripts": {
    "changelog": "bsg changelog"
  }
}
```

然后运行 `npm run changelog` 即可在项目根目录看到生成/更新的 `CHANGELOG.md` 文件。

## 深入使用

### eslint

工具提供了默认的 `.eslintrc.js` 配置文件

##### 1. 想继续使用编辑器的自动校验和格式化功能？

只需要在项目根目录的编辑器设置中添加配置文件路径：

```json
// .vscode/settings.json
{
  "eslint.options": {
    "configFile": "node_modules/bsg/.eslintrc.js"
  }
}
```

【不推荐】同时，工具也支持自定义配置，只需像往常一样，在项目的根目录添加 `.eslintrc.js` 文件即可，工具会优先使用自定义配置。

【推荐】当然，直接使用工具自带的配置也不会有任何问题，因为工具只会对你提交的文件做自动格式化，并不会将所有文件一次性全部格式化（除非你主动使用此功能），这将有助于你将项目一点点的向 `bsg` 规范迁移。

##### 2. 有些文件不需要被检测/格式化怎么办？

在项目的根目录添加 `.eslintignore` 文件即可.

### stylelint

和 `eslint` 一样，工具同样提供了默认的 `.stylelintrc.js` 配置

##### 1. 想继续使用编辑器的自动校验和格式化功能？

```json
// .vscode/settings.json
{
  "stylelint.configFile": "node_modules/bsg/.stylelintrc.js"
}
```

同样，工具也支持 `stylelint` 的自定义配置，只需要在项目根目录添加 `.stylelintrc.js` 即可。

##### 2. 有些文件不需要被检测/格式化怎么办？

在项目的根目录添加 `.stylelintignore` 文件即可.

### commitlint

##### 1. 忘记了 `bsg` 的规范怎么办？！

工具提供了贴心的 `commit` 引导工具，只需要在 `package.json` 的 `scripts` 中添加：

```json
// package.json
{
  "scripts": {
    "commit": "bsg commit"
  }
}
```

然后运行 `npm run commit` 即可唤出引导窗口！

##### 2. 提交平台为 `gerrit`，想同时使用 `gerrit` 钩子 / 无法提交到 `gerrit` ？

只需要在项目根目录的 `.husky/commit-msg` 文件中添加 `gerrit` 相关脚本即可。

完整脚本如下：

```sh
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

npx --no-install bsg commitlint

if [ -f .git/hooks/commit-msg ]; then
  . ".git/hooks/commit-msg"
fi
```

##### 3. 提交时遇到 `git exited with error code 1` ?

这是因为 `gerrit` 在获取 `core.commentChar` 时使用了 `git config --get core.commentChar` ，而 `--get` 在没有找到对应键时会返回 `error code 1`。

解决办法：为 `core.commentChar` 设置一个值。

例如：

```bash
$ git config --local core.commentChar '#'
```

### changelog

##### 1. 为什么我的 `CHANGELOG.md` 中只有一个版本/丢失了好多版本？

`bsg changelog` 是基于 `tag` 版本来生成的，请检查是否每个版本都认真打上了 `tag` !

##### 2. 为什么我的 `CHANGELOG.md` 中的信息重复生成了？

`bsg changelog` 默认情况下是基于最新的 `tag` 生成最新一个版本的 `changelog` 信息的，如果这是你第一次使用本工具或者想要生成所有以前的 `changelogs`，则可以使用：

```bash
$ npx bsg changelog -r 0
```

这将重新生成所有以前的 `changelogs` ！

如果你担心自己经常忘记去更新 `changelog`，可以将 `package.json` 的 `scripts`中的 `changelog` 命令变更为：

```json
// package.json
{
  "scripts": {
    "changelog": "bsg changelog -r 0"
  }
}
```

这将保证你每次生成的 `changelog` 都是完整且不重复的！

##### 3. 为什么 `CHANGELOG.md` 中的 commit 和 bug 的链接不正确？

工具默认使用的链接格式是基于类 GitHub / GitLab 项目的，假如你的项目是在公司的 GitLab 中且提 bug 是通过 issue 的形式，那么无需进行任何设置工具就能生成正确的链接。

如果你的项目是在公司的 gerrit 平台上的，则需要进行声明，因为公司有许多不同的 gerrit 平台。

举个例子，假如现在有一个项目是在地址为 `https://dev-gerrit-b2d.ge.cn` 的 gerrit 平台上且 bug 是通过地址为 `https://pm.ge.cn` 的禅道平台提交的，只需在 `package.json` 中进行如下设置即可在 `CHANGELOG.md` 中生成正确链接：

```json
{
  "repository": {
    "url": "https://dev-gerrit-b2d.ge.cn",
    "type": "gerrit"
  },
  "bugs": {
    "url": "https://pm.ge.cn"
  }
}
```

#### 进阶

众所周知，`changelog` 是搭配 `tag` 来使用的，那么如何在生成 `changelog` 的时候不忘记打 `tag`，如何在打 `tag` 的时候不忘生成 `changelog`，如何简化 **生成 `changelog` + 打 `tag` + 版本提交** 这一工作流呢？

只需要在 `package.json` 的 `scripts` 中添加：

```json
// package.json
{
  "scripts": {
    "version": "bsg changelog && git add CHANGELOG.md"
  }
}
```

然后直接运行 `npm version [patch|minor|major]` 即可。

`npm version` 自动生成的 `commit message` 不符合 `bsg` 的规范怎么办？

好办。在项目根目录添加 `.npmrc` 文件，写入：

```
tag-version-prefix=""
message="[bump]: %s"
```

之后再使用 `npm version` 时将自动生成符合 `bsg` 规范的提交信息：`[bump]: <your version>` ！