Gitコミットメッセージから役に立つchangelogを自動的に生成する方法

ChangeLogを作成することは、新しいソフトウェアバージョンがリリースされることになっているならば、通常の仕事です.これは、すべてのchangeswhich含まれていた最後のリリース以来、どのようなコードで変更されたことを覚えて有用であり、私たちのコードのユーザーに通知することができます.
多くのプロジェクトでは、changelogを作成することは、しばしば望まれていない、エラーがちで、時間がかかる手動プロセスです.この記事では、Git履歴に基づいてchangelogの作成を自動化するのに役立つツールを説明します.
いくつかの基本から始めましょう.

意味的バージョン管理

Semantic Versioning (SemVer) コードバージョン管理のための事実上の標準です.Aversion番号は常にこれらの3つの部分を含んでいることを指定します.

主要な変更:例えば、互換性のないAPI変更を加えるとき、増加します

マイナー:後方互換機能を追加するときにインクリメントされます

パッチ:後方互換性のあるバグ修正を追加するとインクリメントされます

従来コミット

The Conventional Commits specification proposes introducing a standardized lightweight convention on top of commit messages.This convention dovetails with SemVer, asking software developers to describe in commit messages, features, fixes, and breaking changes that they make.

開発者はコミットメッセージを書く傾向があるserve no purpose . 通常、メッセージは変更が行われた場所、変更されたもの、および変更を行うための動機とは何かを説明しません.
それで、私はコミットメッセージを書くことを勧めますConventional Commits specification :

<type>[optional scope]: <description>

[optional body]

[optional footer]

このようなメッセージの例です.

fix: ABC-123: Caught Promise exception

We did not catch the promise exception thrown by the API call
and therefore we could not show the error message to the user

コミットタイプ<type> これらの値のいずれかを指定できます.

fix: このタイプのコミットは、あなたのコードベースでバグをパッチして、意味のバージョン化のパッチ・バージョンと相関します

feat: このタイプのコミットは、CodeBaseに新しい機能を導入して、意味的なバージョン化のマイナーなバージョンと相関します

BREAKING CHANGE: テキストを持つコミットBREAKING CHANGE: オプションの本体またはフッターセクションの先頭で、破壊的なAPI変更を導入して、意味的なバージョン管理の主要なバージョンと相関します.壊れた変化はどんなタイプのコミットでもありえます.例えば、fix: , feat: & chore: 他のタイプに加えて、型はすべて有効です.

その他のタイプchore: , docs: , style: , refactor: , perf: , test: を推奨しますAngular convention . theseypesは意味的なversioningに暗黙の影響を有しない、そして、従来のコミット仕様の一部でない.
私も読書をお勧めHow to Write Good Commit Messages: A Practical Git Guide .

自動生成changelog

ここでChangelogの作成を自動化することができます.

フォローするConventional Commits Specification あなたの倉庫で.私たちは@commitlint/config-conventional これを実施するGit hooks .

用途standard-version , SemverとChangeLog生成を用いたバージョン管理のためのユーティリティConventional Commits .

これに基づいて使い方をご紹介しますdemo project 実行初期化npm init and git init .
次のステップはインストールすることですhusky , どちらがあなたのGit hooks :

npm install husky

インストールcommitlint CONFIGを使用してコミットメッセージを表示します.

npm install @commitlint/{cli,config-conventional}

使用中config-conventional 我々は自動的に次のとおりですAngular commit convention .
今ハスキーに走らせる必要があるcommitlint Gitコミットフック中.我々はそれを追加することができますpackage.json

  "dependencies": {
    "@commitlint/cli": "latest",
    "@commitlint/config-conventional": "latest",
    "husky": "latest"
  },
  "husky": {
    "hooks": {
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
  }

あるいは.huskyrc ファイル

{
  "hooks": {
    "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
  }
}

最後に、我々は.commitlintrc.json ルールを拡張するファイルconfig-conventional :

{
  "extends": ["@commitlint/config-conventional"]
}

走るgit commit 無効なメッセージでエラーが発生します.

▶ git commit -m "this commit message is invalid"
husky > commit-msg (node v14.8.0)
⧗ input: this commit message is invalid
✖ subject may not be empty [subject-empty]
✖ type may not be empty [type-empty]

✖ found 2 problems, 0 warnings
ⓘ Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint

husky > commit-msg hook failed (add --no-verify to bypass)

有効なコミットが動作します.

▶ git commit -m "feat: initial feature commit"
[master (root-commit) a87f2ea] feat: initial feature commit
 5 files changed, 1228 insertions(+)
 create mode 100644 .commitlintrc.json
 create mode 100644 .gitignore
 create mode 100644 index.js
 create mode 100644 package-lock.json
 create mode 100644 package.json

現在、我々は安全で、有効なコミットメッセージだけが我々の倉庫にあることを保証することができます.

変更を生成する

最後に、gitの履歴からchangelogを作成することができます.最初のステップはインストールすることですstandard-version :

npm i --save-dev standard-version

これでNPMスクリプトを作成できますpackage.json :

  "scripts": {
    "release": "standard-version",
    "release:minor": "standard-version --release-as minor",
    "release:patch": "standard-version --release-as patch",
    "release:major": "standard-version --release-as major"
  },

changelogの生成は、.versionrc.json ファイルまたは配置standard-version あなたのスタンザpackage.json .
デモでは.versionrc.json ファイルに基づいてConventional Changelog Configuration Spec :

{
    "types": [
      {"type": "feat", "section": "Features"},
      {"type": "fix", "section": "Bug Fixes"},
      {"type": "chore", "hidden": true},
      {"type": "docs", "hidden": true},
      {"type": "style", "hidden": true},
      {"type": "refactor", "hidden": true},
      {"type": "perf", "hidden": true},
      {"type": "test", "hidden": true}
    ],
    "commitUrlFormat": "https://github.com/mokkapps/changelog-generator-demo/commits/{{hash}}",
    "compareUrlFormat": "https://github.com/mokkapps/changelog-generator-demo/compare/{{previousTag}}...{{currentTag}}"
  }

配列type オブジェクトは明示的にサポートされているコミットメッセージ型を表し、生成されたchangelogファイルに表示するかどうかを表します.commitUrlFormat ハッシュでの特定のコミットを表すURLcompareUrlFormat つのgit shasの比較を表すURLです.
最初のリリースを実行することによって作成することができますnpm run release -- --first-release 端末で:

▶ npm run release -- --first-release

> [email protected] release /Users/mhoffman/workspace/changelog-generator-demo
> standard-version "--first-release"

✖ skip version bump on first release
✔ created CHANGELOG.md
✔ outputting changes to CHANGELOG.md
✔ committing CHANGELOG.md
✔ tagging release v0.0.0
ℹ Run `git push --follow-tags origin master` to publish

代表的な例CHANGELOG.md 閉じるこの動画はお気に入りから削除されています

私が好きなのは、changelogがコミットの型によって分割されていることで、特定のコミットとリンクのリンクを含んでいることです.
もちろん、常にそれをより読みやすくするために自動生成changelogを編集することができます.生成されたChangeLog Markdownテキストは、各リリースタグの横に表示されるように、Githubリリースに貼り付けることができます.LINTINGコミットまたはchangelogの生成をカスタマイズするツールには、より多くのオプションがあります.

結論

私のような怠惰な開発者のために、自動changelog生成は私に多くの時間を節約する良いツールです.さらに、確立された仕様に従ってコードリポジトリにメッセージをコミットします.
コミット慣習に慣れるには少し時間が必要だ.AllCode貢献者が大会に従う必要があるので、あなたはあなたのチームのいくつかの議論に遭遇することができました.Gitフック解決策は可能な限り早くメッセージを間違えるでしょうが、あなたのCI/CDパイプラインでガードを追加することもできます.
私の意見では、プロジェクトにおけるGitコミット規約とChangeLog生成を導入する努力の価値があります.我々は開発者としてChangeLog世代のための多くの時間と脳容量を投資する必要はありませんし、我々は我々のソフトウェアリリースの間で変更されたものを調べることができるヘルプFullDocumentを持っている.また、私たちは簡単に、私たちのソフトウェアのユーザーを共有することができますので、彼らはまた、それぞれの新しいリリースから期待できるものを参照してください.