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

简介

爱美之心人皆有之。本文就介绍如何使用standadr-release自动生成好看的Git提交记录文档。

背景

作为一只程序猿，Git代码管理工具相信大家都用过，那么Git提交记录想必大家也都看过，不管是用什么工具查看，多多少少都感觉乱，但部署个人博客时发现，Vanblog发布版的更新日志（Changelog）都很漂亮，而且都链接到每一次的提交记录，这样就很漂亮，你觉得呢？

本文就来记录我理解的standran-release的使用方法，如有错误敬请指正！

提交信息规范

首先，使用一些工具，就要遵守这个工具一些规矩，standard-release则需要提交记录的信息说明要符合一定的规范。

大家都知道，在提交一次Git时，需要写一些这次提交的信息说明，即commit message，standard-release就是需要你的这些commit message符合一定的规范。

这个规范起初好像是Angular社区提出的AngularJS Git Commit Message Conventions，中文文档：Angular提交信息规范。现在已经算是Git通用规范了，standard-release相关说明文档则是指向Conventional Commits，文档是纯英文的，英文不好的朋友们可以自行翻译。不想看也可以，下边我会挑一些重要内容说明。

整体规范

规范要求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这部分。。

实例

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

工具使用

上面讲了基本的代码提交规范，下边就是具体的工具使用了。

作为非专业人员，接触node不是很多，看vanblog源码和standard-release官方说明好久才大致理解了使用方法，如有错误请一定指出！

根据我的理解，要想形成Changelog这样好看的文档，只需三步：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
官方配置说明：conventional-changelog-config-spec
本文以.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自己对应看，应该能看明白吧。

补充：之所以配置三个UrlFormat，是因为我本地有多个Git帐号，导致自动生成的URL是我本地的配置，直接上传到github之后是链接不到的，所以在这配置上正确地址格式。关于Git多账号，可以阅读《GitHub使用SSH连接》，其中有讲解多用户配置。

运行指令生成文档

根据阅读和使用，使用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源码发现，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();

目录

简介

背景