npm 包 pon-task-changelog 使用教程-JavaScript中文网-JavaScript教程资源分享门户

前言

在软件开发过程中，版本迭代是很常见的。为了更好地跟踪各个版本的变化，我们需要记录每一个版本的更新内容。而pon-task-changelog正好是为此而生的。

在本文中，我们将会探讨如何使用这一npm包，以记录和生成项目版本变化文件。

前置技能

在学习使用pon-task-changelog之前，需要掌握以下技能:

基本的Node.js知识
熟悉npm包的安装及使用方法

安装

在掌握前置技能后，我们就可以通过npm来安装pon-task-changelog包。使用以下命令即可完成安装：

npm install --save-dev pon-task-changelog

快速开始

pon-task-changelog包可以用于记录项目的版本更改内容，具体来说，其会将项目的提交日志写入到类似于`CHANGELOG.md`这样的文件中。

使用该npm包的方式十分简单，您只需要在ponfile.js文件中引入并设置任务即可，例如：

module.exports = pon({
  "myProject:changelog": require("pon-task-changelog")()
});

上述代码中，我们通过require("pon-task-changelog")()来引入该npm包。

这里我们定义了一个名为“myProject:changelog”的任务。

现在，我们来执行这个任务：

pon myProject:changelog -- --from=<从哪个 Git 提交记录开始生成日志> --to=<从哪个 Git 提交记录开始生成日志>

其中，--from 和 --to 是非必填参数，可以用来指定要生成日志的提交范围。若不指定，则会生成所有提交日志。

待执行完成后，您会发现，在项目根目录下会多出一个CHANGELOG.md的文件，该文件便是记录了我们的项目版本变更日志。

指南

基本设置

在前述“快速开始”中，我们简单地引入了pon-task-changelog，但是这并不足以让您满意。

在这一部分，我们将开始添加一些对pon-task-changelog开发人员友好的设置。

首先，我们来看一下pon-task-changelog最基本的默认行为，您或许可以通过以下方法来创建并且运行一个基本的ponfile.js文件：

-- -------------------- ---- -------
----- - --- - - ---------------
----- --------- - ------------------------------

-------------- - ----
  -
    ---------- -----------
  --
  -
    ------- -----------
  -
--

这便是一个基本的ponfile.js文件，其中设定了一个名为“changelog”的默认任务，并且通过--prefix参数指定了命名空间为"myProject"。

现在，我们来试一下如何运行它，可以输入以下命令进行运行：

$ pon myProject:changelog

看起来很简单，是吧？

自定义目录和文件名

假如您不想使用CHANGELOG.md作为默认的记录日志的文件，或者您将CHANGELOG.md放在了其他目录中，那该怎么操作呢？

不要担心，pon-task-changelog早已为您准备好了自定义目录和文件名的方法。

修改上述代码，如下：

-- -------------------- ---- -------
----- - --- - - ---------------
----- --------- - ------------------------------

-------------- - ----
  -
    ---------- -----------
      ----- ------------------- -- -- ------
    --
  --
  -
    ------- -----------
  -
--

在代码中添加了一个新选项是dest，用于定义文件生成的位置和名称。可以在设置时设置该选项。

其中，'docs/changelog.md'为CHANGELOG.md创建的目录和文件名。您可以改变这个文件名，也可以更改目录名称，以适应不同的需求。

API详解

pon-task-changelog还提供了许多不同的各种设置。我们先来简单浏览一下它们：

バージョン情報を自動的に更新する
バージョン情報を挿入する
マークダウンの装飾を調整する
全ての Git ログを表示する
マージコミットをまとめて表示する
レリース日を指定する
自分で好みの処理方法を設定する

接下来，我们一一来看每一个选项的含义和用法。

`autoIncrement`

以下的代码展示了如何开启自动更新版本号并将版本号插入到日志顶部：

{
  autoIncrement: true
}

autoIncrement是一个boolean类型的选项，开启之后，该选项将默认为您提取变更日志并自动更新版本号，然后再将新的版本号写回文件中。这个版本号将会被插入到 CHANGELOG 文件的开头。

`header`

您也可以遵循以下方法，将一行或多行文本插入到 CHANGELOG 文件的开头：

{
  header: "# Changelog\n\nAll notable changes to this project will be documented in this file.\n\nThe format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)."
}

header是一个string类型的选项，您可以利用该选项，向生成的日志文件中写入自定义的内容。

`decorate`

在这种情况下，您可以决定使用差异符号，如连字符为节点，以装饰 markdown 日志的外观，例如：

{
  decorate: function(markdown: string): string {
    return `## Changelog\n\n${markdown.trim()}\n`
      .replace(/^### /gm, "- ")
      .replace(/^## /gm, "### ");
  }
}

decorate是一个function类型的选项，该方法将提供要生成的 markdown 字符串作为唯一参数，并返回装饰后的 markdown 字符串。

在上面的示例中，我们使用function方法传递了一个将markdown字符串从 "== 2.x.x ==" 修改成 "## 2.x.x" 格式的回调函数。

`all`

您也可以通过如下方式来包含 git 提交日志中的不同的分支（即默认不显示所有分支）：

{
  all: true
}

all是一个boolean类型的选项，默认值为false，当其值被设置为true时，它将会包含所有从master分支分离出来的分支的日志记录。

`mergePattern`

您还可以通过以下代码来聚合排除指定的merge提交 commit message：

{
  mergePattern: /^Merge pull request #\d+ from [\S]+/
}

mergePattern是一个RegExp类型的选项，用于识别那些默认情况下会被过滤掉的提交记录。

mergePattern可以将任何匹配项添加到这个数组中来完成聚合.如下，我们是使用该选项将git提交记录中的默认 merge commit message 模板所表示的记录过滤掉。

`date`

设置RELEASE日起：

{
  date: "2021-12-24"
}

date是一个string类型的选项。您可以指定RELEASE日时使用的字符串。

在对生成的版本日志文件进行修改时，这种选项可以非常有用。

`renderEnv`

我们还可以指定环境渲染器。例如:

{
  renderEnv: function(): string {
    return `[<a href="${PREVIOUS_URL}">previous versions</a>]`;
  }
}

renderEnv是一个function类型的选项。通过指定该选项，您可以自定义生成版本日志文件时的 ENV 展现行为。

`releaseCommitMessage`

您还可以自定义「发布提交」的提交信息：

{
  releaseCommitMessage: "chore(release): release <%= version %>"
}

该选项为releaseCommitMessage，它是一个string类型的选项，该选项表示我们可以自定义发布提交时的提交信息。

通过使用模板引擎，您可以替换掉其中的<%= version %>以适应不同的需求。

`plugin`

最后，我们也可以通过在使用时指定自己的插件函数，来自定义一些特定的处理过程。例如:

{
  plugin: function(changelog, _, done) {
    console.log(changelog);
    done();
  }
}

plugin是一个function类型的选项，您可以通过传入函数来在内部处理使用pon-task-changelog生成的版本日志文件。

在上述示例中，我们已经向该选项传递了一个回调函数。当plugin处理完成后，我们通过console.log输出了changelog内容。您可以在自定义的plugin函数内执行任何自定义过程。

示例代码

以下是使用pon-task-changelog的示例代码。

-- -------------------- ---- -------
----- - --- - - ---------------
----- --------- - ------------------------------

-------------- - ----
  -
    ---------------------- -----------
      ----- --------------- -- --------
      ------- -- ---------------- ------- ------- -- ---- ---- ---- ------- ----- ---- -- ---------- -- ---- ------------ ------ -- ----- -- ----- - ------------------------------------------------- --- ---- ------- ------- -- --------- -------------------------------------------------------
      ---- -----
      --------- ------------------ -
        ------ --- ----------------------------------
          -------------- ---- -- --
          ------------- ---- ---- ---
      -
    --
  --
  -
    ------- -----------
  -
--

您现在已经可以愉快的开始使用了。

结论

以上便是关于pon-task-changelog的完整使用教程。

在我们的日常开发工作中，不断地记录和追踪变更是非常重要的。使用该npm包，不仅可以轻松地完成这一目标，而且会让您的开发过程更为高效、顺畅。

我们希望这篇文章可以为您提供帮助，愿您在之后的开发过程中，越发得心应手！

来源：JavaScript中文网，转载请注明来源 https://www.javascriptcn.com/post/191059