Conventional Commitsで
machine readableなコミットを書く

TL;DR:

• Conventional Commitsでコミットを書くとパースしやすい
  • https://www.conventionalcommits.org/ja/v1.0.0/
• ちゃんと書けばversioningも自動でできるよ

TOC

• Conventional Commitsとは
• 具体的にどんな構文で書けばいいの?
• 実際にパースしてみる
• Versioning
• 自動でリリースノートを作成させる(appendix)

Conventional Commitsとは

人間と機械が読みやすく、意味のあるコミットメッセージにするための仕様

Conventional Commits の仕様はコミットメッセージのための軽量の規約です。
明示的なコミット履歴を作成するための簡単なルールを提供します。
この規則に従うことで自動化ツールの導入を簡単にします。
コミットメッセージで機能追加・修正・破壊的変更などを説明することで、この規約は SemVer と協調動作します。

具体的にどんな構文で書けばいいの?

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

(例): fix: 関数Aのバグを修正 #111

Type

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

• Angularの規約が元になっている
• typeに含まれうる文字種はいろいろある
  • 一番有名なのは@commitlint/config-conventional
• 破壊的変更が入る場合はfix!など!が付属する: 例

Scope

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

• モノレポなどだとfix(parse):みたいなコミットになることがある: 例(angular/angular)
  • プロジェクトの規約とかで拡張可能
• optionalなので無くてもよい

Description

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

• コミット本文
  • コミットのprefixと: で区切られていないといけない
• 末尾にissue番号(#111など)を含むとgithubなどで追跡しやすい

Footer

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

• コミットのフッタ
  • Co-authored-byなどはここにくる
    • フッタのトークンは空白の代わりに-を使わなければならない
    • git interpret trailersに準拠

実際にパースしてみる

https://gist.github.com/Omochice/e04b153d12a16bfe07d1af1dffa6ffd4

パースした結果

input: "feat(sample)!: send an email to the customer when a product is shipped  #1000"
{
  type: "feat",
  scope: "sample",
  subject: "send an email to the customer when a product is shipped  #1000",
  merge: null,
  header: "feat(sample)!: send an email to the customer when a product is shipped  #1000",
  body: null,
  footer: null,
  notes: [
    {
      title: "BREAKING CHANGE",
      text: "send an email to the customer when a product is shipped  #1000"
    }
  ],
  references: [
    {
      action: null,
      owner: null,
      repository: null,
      issue: "1000",
      raw: "feat(sample)!: send an email to the customer when a product is shipped  #1000",
      prefix: "#"
    }
  ],
  mentions: [],
  revert: null
}

Versioning

1. APIの変更に互換性のない場合はメジャーバージョンを、
2. 後方互換性があり機能性を追加した場合はマイナーバージョンを、
3. 後方互換性を伴うバグ修正をした場合はパッチバージョンを上げます。

セマンティック バージョニング 2.0.0 | Semantic Versioning

それぞれconventional commitsのtypeだと以下が対応する

1. !
2. feat
3. fix

リリースするバージョンの特定

• 前回リリース(図だとv1.0.0)からどんな種類のコミットが積まれているかを調べる
  • "!"を含むコミットが積まれていればメジャーバージョンを上げる
  • "feat"を含むコミットが積まれていればマイナーバージョンを上げる
  • "fix"を含むコミットが積まれていればパッチバージョンを上げる

自動でリリースノートを作成させる(appendix)

• googleapis/release-pleaseやrelease-it/release-itなどを使うとconventional commitsから次のリリースバージョンを特定、自動でリリースできる
  • https://github.com/folke/noice.nvim/releases/tag/v1.16.0 みたいなことができる

参考文献

• Conventional Commits
• commit typeは誰に向けたものなのか - HRBrain Blog
• コミットメッセージ規約 「Conventional Commits」を導入してみよう！ / Let's use Conventional Commits - Speaker Deck