2022-12-14
班门弄斧
00
请注意,本文编写于 665 天前,最后修改于 232 天前,其中某些信息可能已经过时。

目录

简介
背景
提交信息规范
整体规范
header
type
scope
实例
工具使用
添加standard-release依赖
添加配置文件
运行指令生成文档
完结
拓展:自动推送Git的js脚本

简介

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

背景

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

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

提交信息规范

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

大家都知道,在提交一次Git时,需要写一些这次提交的信息说明,即commit messagestandard-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,其中1issue的ID。

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

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" } }

添加配置文件

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();
如果对你有用的话,可以打赏哦
打赏
ali pay
wechat pay

本文作者:DingDangDog

本文链接:

版权声明:本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!