@kwooshung/cvlar

为什么开发它？

在这之前，做一个开源项目，我需要使用以下包，才能实现，git提交标准化，版本号管理，changelog自动生成等功能，还得使用我自己开发的项目 standard-version-helper 才能实现控制台交互式升级版本的功能；当然自然也没有在 Github Actions 中自动发布版本的功能。当您如用了 Cvlar 之后，您只需要选择性保留 commitlint 即可实现前面说的所有功能，而且还有更多的功能。

~~commitizen~~
commitlint
~~commitlint-config-cz~~
~~commitlint-config-git-commit-emoji~~
~~conventional-changelog~~
~~conventional-changelog-cli~~
~~cz-conventional-changelog~~
~~cz-customizable~~
~~standard-version~~
~~@kwooshung/standard-version-helper~~

为什么叫 Cvlar？

C：commit
V：version
L：changelog
A：auto
R：release

当然，虽然名字叫 Cvlar，功能并不局限于此。

怎么读？

cvlar，是一个工具合集的首字母组成的词，没有具体的意义，但是怎么读呢？根据单词的发音，可以推出音标[siːvəlɑr]，而读起来感觉和中文的 思维乐 很相似，所以就起了这么一个名字；

因为编程这个职业，需要大量的思考，作者更希望大家在乐趣中编程。（好吧，我承认，其实是因为先有的名字，这个是强行解释的😂）

特点简述

简单记住：命令 cvlar 即可，也可使用 cvlar -h/help 查看帮助；
轻松选择并运行：package.json 中的 scripts 脚本；
包管理：
- 轻松选择 npm、yarn、pnpm，或其他包管理工具，自动安装；
- 可设置源，不会影响原有配置；
git提交：
- 轻松选择 '提交 types' 和 提交 scopes；
- 写入 '短说明'、'长说明'、'关闭 issues'、自定义 '字段'、验证 '提交信息' 等，同时还能自动 '推送到仓库'；
- 若您希望希望 commit message 使用英文，而自己又不擅长英文，也支持通过 google 自动翻译成您指定的语言；
版本管理：
- 轻松 '升级版本号' 选择 '主要版本'、'次要版本'、'补丁版本' 和 '预览版本'，而 '预览版本' 可自动迭代 '预览版本号'，比如 v1.0.0-preview.1、v1.0.0-preview.2 等；
- 你也可以指定 '升级版本号'；也可以 '降级版本'；
- 可自动生成 'changelog'，并自动 '推送到仓库'；
日志管理：轻松设置 '模板'，自动根据 git message 生成 changelog，更是可以通过 Google 翻译，自动翻译成 多种语言 日志，自动 '推送到仓库'；
自动发布：
- 在 Github Actions 中，调用 cvlar -r 命令，将会自动分析 日志 文件，将其自动发布到仓库版本页面中。
- 参考：本仓库的 releases 页；
配置简单：
- 也可以通过 cvlar -i/init，交互式生成配置文件；
- 初始化交互式菜单，支持中文和英文，后续的使用，支持任意语言，只需要在 cvlar 的配置文件中自定义即可；
- 配置文件本可支持 js、cjs 和 mjs；
  - 为了方便只配置一次 commit types 和 commit scopes；
  - 发现 commitlint 无法识别 mjs，所以暂时只支持 cjs 和 js 格式的配置；
- 参考：
菜单可通过配置自定义语言
提升工作效率
对新手友好

安装

npm

npm install @kwooshung/cvlar -D

yarn

yarn add @kwooshung/cvlar -D

pnpm

pnpm add @kwooshung/cvlar -D

你可以选择把此包安装在项目 `开发依赖` 中，也可以选择安装在 `全局`。

开发依赖

如果你有 commitlint 的话，建议项目中安装，因为你可能需要在 .commitlintrc.cjs 中这样做：

const types = require('./scripts/ks-cvlar.types.cjs');
const scopes = require('./scripts/ks-cvlar.scopes.cjs');
const { ConvertToLintTypes, ConvertToLintScopes } = require('@kwooshung/cvlar'); // 需要引入它

优点

方便引入 @kwooshung/cvlar

缺点

需要在 package.json 中的 scripts 中配置 cvlar 命令，如下：

{
  "scripts": {
    "cvlar": "cvlar"
  }
}

而后 npm cvlar [-xxx] 执行

全局

如果你没有 commitlint 的话，建议全局安装；

优点

直接使用 cvlar [-xxx] 执行

缺点

后续如果需要使用 commitlint，需要再在项目中安装一次；

全局 + 开发依赖方式安装（推荐）

优点

方便引入 @kwooshung/cvlar
直接使用 cvlar [-xxx] 执行

缺点

第一次使用，需要安装两次，一次 全局，一次 开发依赖，后续只需要根据需要，项目中选择性安装即可。

使用方法

查看帮助 `cvlar -[h, help]`

初始化 `cvlar -[i, init]`

初始化配置，生成的配置文件，仅包含中文和英文两种语言的配置，且在配置中加入了大量对应的注释，方便理解；
cvlar 支持任意语言，只需要在 cvlar 的配置文件中自定义即可；
初始化之后的配置，.ks-cvlarrc.cjs 可以存在任何位置，上图因为检测到了配置文件，所以没有出现指定保存路径的选项；

本仓库的 commit types 配置
本仓库的 commit scopes 配置
本仓库的 cvlar config；

主菜单 `cvlar`

运行 `package.json script`

git 提交

提交代码

升级版本号

运行包管理

安装依赖

卸载依赖

更新依赖

列出过时的包

查看依赖列表

查看包详细信息

搜索包

日志管理

这里使用 重新生成日志 作为演示，因为它是由 清理日志 和 生成日志 两个步骤组成的。

自动发布

参考

本仓库的 releases 页；
本仓库的 Github Actions；

脚本参考

- name: Auto Release
  run: npx cvlar -r
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

配置

默认搜索路径及文件

其中注释的 .mjs 文件，就像前面说的那样，commitlint 无法识别 mjs，所以暂时只支持 cjs 和 js 格式的配置；

[
  '/ks-cvlar.js',
  '/ks-cvlar.conf.js',
  '/ks-cvlar.config.js',
  //'/ks-cvlar.mjs',
  //'/ks-cvlar.conf.mjs',
  //'/ks-cvlar.config.mjs',
  '/ks-cvlar.cjs',
  '/ks-cvlar.conf.cjs',
  '/ks-cvlar.config.cjs',
  '/ks-cvlarrc.js',
  '/ks-cvlarrc.conf.js',
  '/ks-cvlarrc.config.js',
  //'/ks-cvlarrc.mjs',
  //'/ks-cvlarrc.conf.mjs',
  //'/ks-cvlarrc.config.mjs',
  '/ks-cvlarrc.cjs',
  '/ks-cvlarrc.conf.cjs',
  '/ks-cvlarrc.config.cjs',
  'ks-cvlar.js',
  'ks-cvlar.conf.js',
  'ks-cvlar.config.js',
  //'ks-cvlar.mjs',
  //'ks-cvlar.conf.mjs',
  //'ks-cvlar.config.mjs',
  'ks-cvlar.cjs',
  'ks-cvlar.conf.cjs',
  'ks-cvlar.config.cjs',
  'ks-cvlarrc.js',
  'ks-cvlarrc.conf.js',
  'ks-cvlarrc.config.js',
  //'ks-cvlarrc.mjs',
  //'ks-cvlarrc.conf.mjs',
  //'ks-cvlarrc.config.mjs',
  'ks-cvlarrc.cjs',
  'ks-cvlarrc.conf.cjs',
  'ks-cvlarrc.config.cjs',
  '.ks-cvlar.js',
  '.ks-cvlar.conf.js',
  '.ks-cvlar.config.js',
  //'.ks-cvlar.mjs',
  //'.ks-cvlar.conf.mjs',
  //'.ks-cvlar.config.mjs',
  '.ks-cvlar.cjs',
  '.ks-cvlar.conf.cjs',
  '.ks-cvlar.config.cjs',
  '.ks-cvlarrc.js',
  '.ks-cvlarrc.conf.js',
  '.ks-cvlarrc.config.js',
  //'.ks-cvlarrc.mjs',
  //'.ks-cvlarrc.conf.mjs',
  //'.ks-cvlarrc.config.mjs',
  '.ks-cvlarrc.cjs',
  '.ks-cvlarrc.conf.cjs',
  '.ks-cvlarrc.config.cjs',
  'config/ks-cvlar.js',
  'config/ks-cvlar.conf.js',
  'config/ks-cvlar.config.js',
  //'config/ks-cvlar.mjs',
  //'config/ks-cvlar.conf.mjs',
  //'config/ks-cvlar.config.mjs',
  'config/ks-cvlar.cjs',
  'config/ks-cvlar.conf.cjs',
  'config/ks-cvlar.config.cjs',
  'config/ks-cvlarrc.js',
  'config/ks-cvlarrc.conf.js',
  'config/ks-cvlarrc.config.js',
  //'config/ks-cvlarrc.mjs',
  //'config/ks-cvlarrc.conf.mjs',
  //'config/ks-cvlarrc.config.mjs',
  'config/ks-cvlarrc.cjs',
  'config/ks-cvlarrc.conf.cjs',
  'config/ks-cvlarrc.config.cjs',
  '.config/ks-cvlar.js',
  '.config/ks-cvlar.conf.js',
  '.config/ks-cvlar.config.js',
  //'.config/ks-cvlar.mjs',
  //'.config/ks-cvlar.conf.mjs',
  //'.config/ks-cvlar.config.mjs',
  '.config/ks-cvlar.cjs',
  '.config/ks-cvlar.conf.cjs',
  '.config/ks-cvlar.config.cjs',
  '.config/ks-cvlarrc.js',
  '.config/ks-cvlarrc.conf.js',
  '.config/ks-cvlarrc.config.js',
  //'.config/ks-cvlarrc.mjs',
  //'.config/ks-cvlarrc.conf.mjs',
  //'.config/ks-cvlarrc.config.mjs',
  '.config/ks-cvlarrc.cjs',
  '.config/ks-cvlarrc.conf.cjs',
  '.config/ks-cvlarrc.config.cjs'
];

指定配置文件

若您想将配置文件存放在其他位置，可以通过以下命令指定配置文件的所在目录，这样 cvlar 将会优先寻找 -[cd/config-dir] 指定的目录；

注意，是文件夹路径，不是文件路径！

cvlar -[cd/config-dir] xxx/xx/x

推荐在 package.json 中的 scripts 中配置；

{
  "scripts": {
    "cvlar": "cvlar -cd xxx/xx/x"
  }
}

配置文件说明及参考

通过 cvlar -i/init，生成对应配置文件，参考上方的 初始化 部分；以下两个文件，均使用此命令生成的配置文件，分别是中文和英文两种语言的配置；

.ks-cvlarrc.cjs
.ks-cvlarrc.en.cjs

其他

commitlint 配置

此文件 .commitlintrc.cjs 是 commitlint 的配置文件，用于 commitlint 的配置；为了方便统一管理，所以独立出来了 ks-cvlar.types.cjs 和 ks-cvlar.scopes.cjs 两个文件，用于 commitlint 的 types 和 scopes 的配置，及 cvlar 的 commit 菜单的配置；

本仓库的 commit types 配置
本仓库的 commit scopes 配置

在 .commitlintrc.cjs 中，可以引入 ks-cvlar.types.cjs 和 ks-cvlar.scopes.cjs 两个文件，但由于 cvlar 的 commit 配置和 commitlint 不同，所以您需要这样引入两个函数：

const { ConvertToLintTypes, ConvertToLintScopes } = require('@kwooshung/cvlar');

方便转换成 commitlint 的配置，具体使用方法，请参考 .commitlintrc.cjs；

commit message 启用翻译

若是开启了 commit message 的翻译功能，短说明一般是72个字符，则不建议 commitlint 的 header-max-length 规则不建议也是72个字符，因为 commit message 的翻译后，可能会超过72个字符，导致 commitlint 报错；推荐将 commitlint 的 header-max-length 规则设置方案有3个：

方案一（推荐）：将 `commitlint` 的 `header-max-length` 规则，设置为正常字数的 `72` 的 `2倍` 及 `以上`，比如 `200`

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'header-max-length': [2, 'always', 200]
  }
};

方案二：关闭 `commitlint` 的 `header-max-length` 规则，但不确定未来是否会有其他问题

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    // 'header-max-length': [0, 'always', 72]
  }
};

方案三：将 `commitlint` 的 `header-max-length` 规则，设置为如下

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'header-max-length': [0, 'always']
  }
};

.gitigonre 忽略git提交临时文件

建议在 .gitigonre 中添加以下内容，以免将 cvlar 的临时文件提交到仓库中；避免某些边缘情况下，误提交临时文件到仓库中，导致仓库中出现不必要的文件；这种文件会在合适的时候，自动删除，所以不用担心；这样做，是双保险！

.cvlar-commit-message-*.tmp

开发 & 维护

本项目主要是为了加速开发所生，每日开发时间较短，且时间比较紧簇，难免存在一些未知的问题，欢迎大家提出宝贵的意见和建议，请友好友善提交！
最近本人工作较赶，对于 issue 和 pr 的处理可能会有些慢，还请大家见谅，但还是希望大家能够踊跃提交 issue 和 pr，一旦有时间，将会集中处理！
因为本人时间问题，更推荐大家进行 pr，这样可以更快的解决问题！

Files

README.zh-CN.md

Latest commit

History