@gzteacher/workflow/README.md

版本发布相关自动化工作流脚本

# @gzteacher/workflow

<p>
  <a href="https://www.npmjs.com/package/@gzteacher/workflow">
    <img src="https://img.shields.io/npm/v/@gzteacher/workflow.svg" alt="Version" />
  </a>
  <a href="https://github.com/yyz945947732/gzteacher-workflow/pulls">
    <img
      src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg"
      alt="PRs Welcome"
    />
  </a>
  <a href="/LICENSE.md">
    <img
      src="https://img.shields.io/badge/license-MIT-blue.svg"
      alt="GitHub license"
    />
  </a>
</p>

🚀 版本发布相关自动化工作流脚本:

- 更新版本文件
- 推送新版本文件
- 创建新 TAG
- 推送新 TAG
- 企业微信消息通知

<img src="https://s1.imagehub.cc/images/2023/09/03/workflow.png" alt="workflow.png" border="0" />

## Quick start

本地安装

```sh
npm install -D @gzteacher/workflow
```

`package.json` 文件添加以下命令:

```json
"scripts": {
  "tag": "autoTag"
}
```

执行以下命令，输出版本号即安装成功。

```bash
npm run tag -- -v
```

现在，你可以执行命令发布新版本了。

```bash
npm run tag
```

## Configuration

### 配置文件

在项目根目录创建 `workflow.config.js` 文件，其中的配置将覆盖默认配置。

以下是一个快速的简单配置:

```javascript
module.exports = {
  tag: {
    getEnv: ({ branchName }) => {
      if (branchName === 'master') {
        return 'prod';
      }
      return 'dev';
    },
    getVersionFileName: ({ branchName }) => {
      if (branchName !== 'master') {
        return 'VERSION.DEV';
      }
      return 'VERSION';
    },
    allowBranchs: ['master', 'dev'],
  }
};
```

详细配置可以查看[配置项](#配置项)。

完整配置案例可以查看[配置案例](https://github.com/yyz945947732/gzteacher-workflow/blob/master/example/workflow.config.js)。

#### 类型提示

为了获取良好的类型提示，推荐导入类型并使用 JSDOC 语法获取类型提示支持：

```js
/**
 * @typedef {import("@gzteahcer/workflow/types").WorkFlowConfig} WorkFlowConfig
 */

/**
 * @type {WorkFlowConfig}
 */
const config = {
 // ...
}
module.exports = config;
```

### 配置项

#### tag

发布 tag 行为相关配置。

##### tag.getVersion

- 类型：`(ctx: Context) => string`
- 默认值：`({ preVersion }) => preVersion`

配置新标签获取 tag 格式 `{version}-{env}-{order}` 中 `version` 值的方法。默认取上一个标签中 `version` 的值。

##### tag.getEnv

- 类型：`(ctx: Context) => string`
- 默认值：`({ preEnv }) => preEnv`

配置新标签获取 tag 格式 `{version}-{env}-{order}` 中 `env` 值的方法。默认取上一个标签中 `env` 的值。

##### tag.getOrder

- 类型：`(ctx: Context) => string`
- 默认值：`({ preOrder }) => ${Number(preOrder) + 1}`

配置新标签获取 tag 格式 `{version}-{env}-{order}`中 `order` 值的方法。默认取上一个标签中 `order` 的值加 1。

##### tag.getTagName

- 类型：`(ctx: Context) => string`
- 默认值：`undefined`

配置新标签获取 `tagName` 的方法。结果将替换原 `{version}-{env}-{order}` 格式的组装。

你可以用它来配置自定义的 tag 格式或用它来更灵活的创建新标签名。

```javascript
import semver from 'semver'
const config = {
  tag: {
    //...
    getTagName: ({ branchName, preVersion, preEnv, preOrder }) => {
      let version = preVersion;
      let env = preEnv;
      let order = preOrder;
      if (branchName === 'master') {
        version = semver.inc(version, 'prerelease');
        env = 'prod'
        order = 1
        return `${version}-${env}-${order}`;
      }
      order = Number(order) + 1
      return `${version}-${env}-${order}`;
    };
  }
}
```

##### tag.getMsg

- 类型：`(ctx: Context) => string`
- 默认值：`({ tagName }) => chore: release ${tagName}`

配置获取 commit 内容的方法。

##### tag.getVersionFileName

- 类型：`((ctx: Context) => string) | false`
- 默认值：`VERSION`

配置获取版本号文件名的方法，`false` 时关闭更新版本号文件的行为。

##### tag.getFirstTagName

- 类型：`(ctx: Context) => string`
- 默认值：`undefined`

配置获取第一个 tag 名的方法，将在仓库还没有 tag 记录时使用。`undefined` 时不自动提交第一个 tag。

##### tag.allowBranchs

- 类型：`string[]`
- 默认值：`undefined`

允许触发 tag 流程的分支名。`undefined` 时不限制分支名。

#### notify

企业微信消息通知相关配置，`undefined` 时关闭消息通知行为

##### notify.getWebhookUrl

- 类型：`(ctx: Context) => string`
- 默认值：`undefined`

配置获取消息机器人 webhook 地址的方法。`undefined` 时不发送消息。你可以将 webhook 地址设置为环境变量以防止泄露。配置企业微信机器人可查看[文档](https://developer.work.weixin.qq.com/document/path/91770)。

##### notify.getContent

- 类型：`(ctx: Context) => string`
- 默认值：`undefined`

配置获取消息内容的方法。支持 md 格式。`undefined` 时不发送消息。

##### notify.allowBranchs

- 类型：`string[]`
- 默认值：`undefined`

允许触发消息通知流程的分支名。`undefined` 时不限制分支名。

### Context

配置中 `getXXX` 类方法都可以通过参数拿到 `context` 上下文信息，其中包括以下信息：

- `branchName`：当前分支名
- `username`：当前 git 用户名
- `preVersion`：上一个标签中的 `version` 部分内容。
- `preEnv`：上一个标签中的 `env` 部分内容。
- `preOrder`：上一个标签中的 `order` 部分内容。
- `preTagName`：上一个 tag 名。
- `version`：新生成标签中的 `version` 部分内容。
- `env`：新生成标签中的 `env` 部分内容。
- `order`：新生成标签中的 `order` 部分内容。
- `tagName`：新生成的 tag 名。

## 命令行 Cli

全局安装以使用命令行 Cli。

### version

查看版本。

```bash
autoTag -v
```

### help

查看帮助。

```bash
autoTag -h
```

### silence

发布版本但不发送消息通知。

```bash
autoTag -s
```

### debug

执行脚本但不执行任何产生副作用的 git 操作与文件操作，同时开启日志信息，一般用于调试配置。

```bash
autoTag -d
```

## 手动执行

你可以在 Node 环境中调用方法执行发布流程。

```javascript
import workflow from '@gzteacher/workflow';

const options = {
  debug: false,
  silence: false
}

workflow(options);
```

## VSCode


安装 [VERSION](https://marketplace.visualstudio.com/items?itemName=yaoyuanzhang.version-highlight) 插件以支持 `VERSION.***` 文件语法高亮。

## LICENSE

[MIT](https://github.com/yyz945947732/gzteacher-workflow/blob/master/LICENSE.md)