基于Node的项目文档自动生成工具standard-release

2022/12/14
## 简介 > 爱美之心人皆有之。本文就介绍如何使用[standadr-release](https
月上老狗
@dingdangdog
渲染中...
## 简介
> 爱美之心人皆有之。本文就介绍如何使用[standadr-release](https://github.com/conventional-changelog/standard-version)自动生成好看的Git提交记录文档。

## 背景
> 作为一只程序猿，`Git`代码管理工具相信大家都用过，那么`Git`提交记录想必大家也都看过，不管是用什么工具查看，多多少少都感觉乱，但部署个人博客时发现，[Vanblog](https://github.com/Mereithhh/vanblog)发布版的更新日志（[Changelog](https://github.com/Mereithhh/vanblog/blob/master/CHANGELOG.md)）都很漂亮，而且都链接到每一次的提交记录，这样就很漂亮，你觉得呢？
> 
> 本文就来记录我理解的`standran-release`的使用方法，如有错误敬请指正！

<div class="article-ads"></div>

<!-- more -->

## 提交信息规范

> 首先，使用一些工具，就要遵守这个工具一些规矩，`standard-release`则需要提交记录的信息说明要符合一定的规范。
> 
> 大家都知道，在提交一次Git时，需要写一些这次提交的信息说明，即`commit message`，`standard-release`就是需要你的这些`commit message`符合一定的规范。
> 
> 这个规范起初好像是`Angular`社区提出的[AngularJS Git Commit Message Conventions](https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit#)，中文文档：[Angular提交信息规范](https://zj-git-guide.readthedocs.io/zh_CN/latest/message/Angular%E6%8F%90%E4%BA%A4%E4%BF%A1%E6%81%AF%E8%A7%84%E8%8C%83/)。现在已经算是Git通用规范了，`standard-release`相关说明文档则是指向[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)，文档是纯英文的，英文不好的朋友们可以自行翻译。**不想看也可以，下边我会挑一些重要内容说明。**

### 整体规范

规范要求`commit message`的整体大概要是这个样子：

```
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
```

**解析**：`commit message`可分为三部分：`header`（头部）、`body`（身体）、`footer`（脚部）。`<BLANK LINE>`即空白行，这一点见仁见智，不想留空白行就不要写。

- **header**：信息的头部，即`<type>(<scope>): <subject>`，头部是最重要的部分下面会单独说明。
- body：本次提交的详细说明，如果提交内容不多（或懒得写），可以只写和`header`中的`<subject>`，问题不大🤐。
- footer：本次提交的关联信息。不知道大家知道github上的`issues`吗，简单来说就是一些需求或bug在`issues`上提出，如果你本次提交的内容与某个需求或bug有关联，就在最后加上说明，写法如：`#1`，其中`1`是`issue`的ID。

### header

> `header`分为三部分，`<subject>`最简单，本次提交的概述，自己根据实际情况写即可，没有硬性要求，但`type`和`scope`就相对严格一些，下面详细说明。

#### type

> 即本次提交的类型，如：新功能、BUG修复、文档提交、架构调整等等，这部分都有固定的单词，需要强制使用这些单词，不要自己造词哦，常用类型如下。

- feat (feature)：新版本、新功能
- fix (bug fix)：bug修复
- docs (documentation)：文档相关
- style (formatting, missing semi colons, …)：不影响代码含义的修改，比如空格、格式化、缺失的分号等
- refactor：代码重构（不改变任何逻辑、功能的代码修改）
- test (when adding missing tests)：添加测试用例
- chore (maintain)：代码架构调整

#### scope

> 这部分在`standard-release`的规范里是可选的，只有一些特殊场合用到，目前我只发现在创建新`tag`时会用到，如：`chore(release: 0.43.0)`，而且这次提交记录是`standard-release`自动提交的，也就是说平常我们基本不会用到`scope`这部分。。

### 实例

- 直接上大佬的实例吧，懒得手打了

<img src="https://images.oldmoon.top/images/dingdangdog/dingdangdog-1673856694.png" width=500/>

<div class="article-ads"></div>

## 工具使用

> 上面讲了基本的代码提交规范，下边就是具体的工具使用了。
> 
> 作为非专业人员，接触`node`不是很多，看`vanblog`源码和`standard-release`官方说明好久才大致理解了使用方法，如有错误请一定指出！

根据我的理解，要想形成[Changelog](https://github.com/Mereithhh/vanblog/blob/master/CHANGELOG.md)这样好看的文档，只需三步：1、添加`standard-release`依赖；2、添加配置文件；3、运行指令生成文档。接下啦就分别讲解每一步的具体工作。

### 添加`standard-release`依赖

- 以开发环境依赖安装（推荐）：

```shell
npm i --save-dev standard-version
```

- 全局安装：

```shell
npm i -g standard-version
```

安装完成后，建议在项目的`package.json`文件中增加相应脚本，我的配置如下，仅供参考

```json
{
  "name": "cashbook",
  "version": "0.0.9",
  "private": true,
  "scripts": {
    "tag-major": "standard-version --release-as major",
    "tag-minor": "standard-version --release-as minor",
    "tag-patch": "standard-version --release-as patch",
    "release-docs": "node scripts/changelog.js"
  },
  "devDependencies": {
    "standard-version": "^9.5.0"
  }
}
```

### 添加配置文件

- 项目根目录下添加`.versionrc.js`或`/versionrc.json`文件，官方说明：[conventional-changelog-conventionalcommits](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-changelog-conventionalcommits/README.md)
- 官方配置说明：[conventional-changelog-config-spec](https://github.com/conventional-changelog/conventional-changelog-config-spec/blob/master/versions/2.2.0/README.md)

- 本文以`.versionrc.js`文件为例：

```javascript
module.exports = {
  header: "# Changelog",
  commitUrlFormat: "https://github.com/{{owner}}/{{repository}}/commit/{{hash}}",
  compareUrlFormat:"https://github.com/{{owner}}/{{repository}}/compare/{{previousTag}}...{{currentTag}}",
  issueUrlFormat:"https://github.com/{{owner}}/{{repository}}/issues/{{id}}",
  types: [
    { type: "feat", section: "🛴 Features | 新功能" },
    { type: "fix", section: "🚑 Bug Fixes | Bug 修复" },
    { type: "init", section: "🛫 Init | 初始化" },
    { type: "docs", section: "📚 Documentation | 文档" },
    { type: "style", section: "🚙 Styles | 风格" },
    { type: "refactor", section: "✂ Code Refactoring | 代码重构" },
    { type: "perf", section: "🚀 Performance Improvements | 性能优化" },
    { type: "test", section: "🚔 Tests | 测试" },
    { type: "revert", section: "🚧 Revert | 回退" },
    { type: "build", section: "⚓ Build System | 打包构建" },
    { type: "chore", section: "🚩 Chore | 构建/工程依赖/工具" },
    { type: "ci", section: "⛽ Continuous Integration | CI 配置" },
  ],
};
```
> 说明一下配置项：
> - `header`：即文件标题，因为生成的是md文件，所以使用`markdown`语法。
> - `commitUrlFormat`：文档中链接到提交记录时，url的格式
> - `compareUrlFormat`：文档中链接到`tag`比较时，url的格式
> - `issueUrlFormat`：文档中链接到`issue`时，url的格式
> - `types`：具体文档内容的格式，这个不多说了，根据上面讲的[type](#type)自己对应看，应该能看明白吧。
> 
> 补充：之所以配置三个`UrlFormat`，是因为我本地有多个Git帐号，导致自动生成的URL是我本地的配置，直接上传到github之后是链接不到的，所以在这配置上正确地址格式。关于Git多账号，可以阅读《[GitHub使用SSH连接](https://oldmoon.top/post/9)》，其中有讲解多用户配置。

### 运行指令生成文档

根据阅读和使用，使用`standard-version`工具，项目的版本号应该是三级，如：`1.2.1`，相应总结出三个常用指令：
```sh
# 升级大版本
standard-version --release-as major
# 升级小版本
standard-version --release-as minor
# 升级补丁版本
standard-version --release-as patch
```
三条指令相对应三个数字，每次执行会自动在对应的数字上加一，当然，如果是升高级版本，低级版本的数字会被置0，如`1.2.1`升级大版本后应该是`2.0.0`。

**提示：指令运行成功后，会自动帮你把相关文件都提交了，但只是提交到本地分支，不会帮你推送到远程仓库，你需要手动将相关提交和`tags`推送。运行命令`git push --follow-tags origin main`将相关`tags`推送到仓库。**

## 完结

以上，就是全部`standard-version`的使用方式方法介绍，感谢你的阅读。但是还没完，经过阅读[Vanblog](https://github.com/Mereithhh/vanblog)源码发现，**Mereith**大佬还写了一个自动推送的脚本，并且会执行一些特殊操作，下边介绍一下他的脚本。

## 拓展：自动推送Git的js脚本

- 脚本源码，我理解的注释写在源码里，自行阅读体会吧。
- 其中有两次`推送tags`，是因为Git的tag有两种类型，需要不同命令来推送。
```javascript
const insertLog = () => {
  // standard-version自动生成的文档内容读取，并修改标题（这是大佬个性化的需求）
  const fs = require("fs");
  const log = fs.readFileSync("CHANGELOG.md", { encoding: "utf-8" });
  const newLog =
    "---\ntitle: 更新日志\nicon: update\n---\n\n" +
    log.replace("# Changelog", "");

  fs.writeFileSync("docs/ref/changelog.md", newLog, { encoding: "utf-8" });
  // 读取一个叫doc-version的文件，并将版本号+1
  let version = fs.readFileSync("doc-version", { encoding: "utf-8" });
  version = version.split("\n")[0].trim();
  const arr = version.split(".");
  const sub = arr.pop();
  arr.push(String(parseInt(sub) + 1));
  const newVersion = arr.join(".");
  fs.writeFileSync("doc-version", newVersion, { encoding: "utf-8" });

  // 添加并应用：执行shell命令的工具，用于执行git相关命令
  const { execSync } = require("child_process");
  execSync(
    // 添加文件 && 提交 && 创建分支，其中分支版本是上面从doc-version文件读到处理后的 && 推送tags && 推送tags
    `git add . && git commit -m 'docs: 更新文档' && git tag doc-${newVersion} && git push --follow-tags origin master && git push --tags`,
    (err, stdout, stderr) => {
      if (err) {
        console.log(err);
        return;
      }
      console.log(`stdout: ${stdout}`);
    }
  );
};
insertLog();
```

<div class="article-ads"></div>
END
登录后收藏
登录后查看和发表评论
前往登录