Conventional Commits

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

簡単なまとめ すべての仕様 GitHub

Conventional Commits 1.0.0

概要

Conventional Commitsの仕様は、コミットメッセージのための軽量の規約です。 明示的なコミット履歴を作成するための簡単なルールを提供します、この規則に従うことで自動化ツールの導入を簡単にします。 この規約はSemVerと組み合わせることで、コミットメッセージへ機能、修正、破壊的変更を入れることで、さらに詳細な説明を可能にします。

コミットメッセージは次のような形にする必要があります

原文：

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

訳：

<型>[任意 範囲]: <説明>

[任意 本文]

[任意 脚注]

コミットにはあなたのライブラリの利用者に思想を伝えるために、次の構造要素を持ちます：

  1. fix: 型 fix はコードベースのバグにパッチを当てる場合です。（これは セマンティックバージョン管理におけるPATCHに相当します)
  2. feat: 型 feat はコードベースに新しい機能を追加した場合です。(これはセマンティックバージョン管理における MINORに相当します)
  3. BREAKING CHANGE: 本文 または 脚注 に BREAKING CHANGE:が存在する、または 型 、 範囲 の直後に!が追加されているコミットは、APIの破壊的変更を意味できます。(セマンティックバージョン管理におけるMAJORに相当します) BREAKING CHANGE はあらゆる 型 のコミットに含めることができます。
  4. fix: and feat: 以外の 型 を許容します、例えば @commitlint/config-conventional ([Angularの規約] (https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)ベース)は build:, chore:, ci:,docs:, style:, refactor:, perf:, test:, などがあります。
  5. 次のような規則に従うことで、BREAKING CHANGE: <説明> 以外の 脚注 を使うこともできます。 git trailer format.

追加された 型 はconventional commitsで強制されているものではなく、セマンティックバージョン管理に暗黙的な影響も与えません。（それが、BREAKING CHANGEを含めない限り）

コミットの 型 には、追加の情報として 範囲 を追加することができ、それは括弧で囲みます。例 feat(parser): add ability to parse arrays

例

説明と破壊的変更を含む脚注のメッセージをコミットに含める

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

破壊的変更であることに気づいてもらうために ! を付けてメッセージをコミットする

refactor!: drop support for Node 6

! と BREAKING CHANGE の両方を脚注に追加して、メッセージをコミットする

refactor!: drop support for Node 6

BREAKING CHANGE: refactor to use JavaScript features not available in Node 6.

本文無しでメッセージをコミットする

docs: correct spelling of CHANGELOG

範囲 のあるメッセージをコミットする

feat(lang): add polish language

複数の 本文 と 脚注 を持ったメッセージをコミットする

fix: correct minor typos in code

see the issue for details

on typos fixed.

Reviewed-by: Z
Refs #133

仕様

この文書における次の各キーワード「しなければならない（ MUST ）」、 「してはならない（ MUST NOT ）」、「要求されている（ REQUIRED ）」、 「することになる（ SHALL ）」、「することはない（ SHALL NOT ）」、 「する必要がある（ SHOULD ）」、「しないほうがよい（ SHOULD NOT ）」、 「推奨される（ RECOMMENDED ）」、「してもよい（ MAY ）」、 「選択できる（ OPTIONAL ）」は、 RFC 2119 (IPA 日本語) で述べられているように 解釈されるべきものです。

  1. コミットは名詞、feat、fixなどから始まる（ REQUIRED ） 型 から始まり、次に選択できる（ OPTIONAL ） 範囲 と、必須の! 末尾に要求されている（ REQUIRED ）コロンとスペースで成り立ちます。
  2. コミットがあなたのアプリケーションやライブラリに新しい機能を追加するとき、 型 はfeatにしなければならない（ MUST ）。
  3. コミットがあなたのアプリケーションのためのバグ修正を表すとき、 型 は fixにしなければならない（ MUST ）。
  4. 範囲 は 型 の後に記述してもよい（ MAY ）。 範囲 は括弧で囲まれたコードベースのセクションを記述する名詞にしなければならない（ MUST ）。例： fix(構文解析ツール):
  5. 説明 は型/範囲の後にあるコロンとスペースの直後にしなければならない（ MUST ）。 説明 はコード変更の要約です。 例： fix：文字列に複数の空白がある場合の配列解析における問題
  6. 短い 説明 の後に、より長いコミットの本文を追加してもよく（ MAY ）、コード変更に関する追加の情報を提供することができます。 本文は、説明 の下に1行の空行を追加しなければならない（ MUST ）。
  7. コミットの本文は自由形式であってよく（ MAY ）、改行で区切られた複数の段落で構成することが可能です。
  8. １つ以上のフッターを持つことができます（ MAY ）、フッターは改行の後に一つの空白を持ちます。 各フッターは文字トークンで構成されてなければいけません（ MUST ）、その後に :<space> か <space># による区切りが続き、最後に文字列が入ります。（これはgit trailer conventionにインスパイアされています）
  9. 脚注 のトークンには空白の代わりに - を使う必要があります（ MUST ）、例えば Acked-by などです（脚注 と 本文 を区別するのに役立ちます ）。 BREAKING CHANGEの例外を作ることができ、これはトークンとして使用することもできます（ MAY ）。
  10. 脚注 の本文にはスペースと改行を含めることができます（ MAY ）、そして次の 脚注 トークンとセパレーターのペアが見つかった時、以前の 脚注 の解析は終了しなければなりません（ MUST ）。
  11. 破壊的変更は、コミットの 型 / 範囲 の接頭辞か、脚注 に指定する必要があります（ MUST ）
  12. 破壊的変更がフッターに含まれる場合、大文字の REAKING CHANGE の後にコロンとスペース、そして説明を続ける必要があります（ MUST ）。例： BREAKING CHANGE: 環境変数が設定ファイルよりも優先されるようになりました
  13. 破壊的変更がある場合、型 や 範囲 の接頭辞には : の直前に ! を用いて明示的にしなければなりません（ MUST ）。 ! を使用する場合には、 脚注 セクションから BREAKING CHANGE: を省略できます（ MAY ）。そうすると、コミットの 説明 部分で破壊的変更の内容を説明することになるでしょう（ SHALL ）。
  14. コミットメッセージでは feat と fix 以外の 型 を使うことができます（ MAY ）。 （例：docs: ドキュメントの参照を更新）
  15. Conventional Commitsを構成する情報の単位は、必ず大文字のBREAKING CHANGEを除いて、実装側は大文字と小文字を別の物して扱ってはいけない（ MUST NOT ）
  16. 脚注 の BREAKING-CHANGE は BREAKING CHANGE と同じトークンとして解釈されなければいけません（ MUST ）。

何故 Conventional Commits を使うのか

よくある質問

初期の開発段階ではコミットメッセージをどのように扱うべきですか？

すでに製品をリリースしているかのように進めることをお勧めします。 あなたの仲間のソフトウェア開発者であっても、普通は誰かがあなたのソフトウェアを使っています。 何が修正されたのか、何が壊れたのかなどを知りたいでしょう。

コミットタイトル(1行目)の型は大文字か小文字のどちらが良いですか？

どちらでも問題はありません、一貫性を保つことが最善です。

コミットが複数のコミットタイプ( 型 )に準拠している場合はどうすればいいですか？

可能な限り前に戻り複数のコミットに分割します。 Conventional Commits の利点の一つは、より組織化されたコミットとプルリクエストを行う事を可能にする事です。

これは開発速度とインテグレーションを遅くしたりはしませんか？

無秩序にただ早く開発することはお勧めではありません。 それはあなたがさまざまな貢献者との複数のプロジェクト間で長期的に素早く動けるようにするのを助けます。

Conventional Commitsで開発者は提供された 型 を検討することになるため、コミットの 型 を制限することができますか？

Conventional Commitsは、修正などの特定の 型 のコミットメントを行うように促します。 それ以外の点では、Conventional Commitsの柔軟性により、あなたのチームは彼ら自身の 型 を新しく作り、時間の経過とともにそれらの 型 を変更することもできます。

これはSemVerとどのような関係を持っていますか？

fix 型 のコミットはPATCHリリースへ変換します。 feat 型 のコミットはMINORリリースに変換します。 型 にかかわらずコミット内で BREAKING CHANGEを使ったコミットはMAJORリリースに変換するべきでしょう。

私の拡張仕様をどのようにしてConventional Commitsの仕様にバージョンアップするべきでしょうか？、例： @jameswomack/conventional-commit-spec

SemVerを使用して、この仕様に対する独自の拡張仕様をリリースすることをお勧めします（そしてこれらの拡張仕様を作成することをお勧めします）。

間違ったコミットタイプを使用してしまった時はどうしたらいいですか？

仕様的に正しい型だが意味を間違っえた 型 を使用した場合、例えば featの代わりにfix

間違いをマージやリリースする前に、コミット履歴を編集するgit rebase -iを使うことを勧めます。 リリース後、どのツールやプロセスを使用するかによってクリーンアップは異なってくるでしょう。

仕様に ない 型 を使った時、例えばfeat ではなくfeet

最悪のシナリオはコミットが conventional commit の仕様を満たさない場合です、しかしそれは世界の終わりではありません。 それは単に仕様に基づいているツールによってコミットが見逃されるだけでしかありません。

貢献者全員が conventional commit を使用する必要がありますか？

いいえ！ Gitでsquashベースのワークフローを使用するなら、主要メンテナはマージ時にコミットメッセージをクリーンアップすることができるため、通常のコミッタには作業負荷がかかりません。 また一般的なワークフローの場合は、あなたのgitシステムが自動的にpull requestからコミットを破棄し、主要メンテナにマージのための適切なgit commitメッセージを入力するためのフォームを提示することです。

Conventional Commitsはrevertコミットをどのように扱いますか？

コードを元に戻すのは複雑な場合があります。 複数のコミットを元に戻していますか？機能をもとに戻す時にリリースはパッチにまとめる必要がありますか？

Conventional Commitsはrevertの振る舞いを定義するための明示的な努力をしません、代わりにツールに任せます。 作者は 型 と 脚注 の柔軟性を利用して、revertを処理するためのロジックを開発します。

おすすめの方法として、ひとつは revert 型 とrevertされるコミットのSHAを参照するフッターを使うようにすることです。

revert: let us never again speak of the noodle incident

Refs: 676104e, a215868

要約

Conventional Commitの仕様は、Angular Commitのガイドラインに触発されており、それに基づいています。

この仕様書の最初のドラフトは、以下に何人かのコントリビューターと共同して書かれました:

Conventional Commitsのためのツール一覧

Conventional Commitsを利用しているプロジェクト

Conventional Commits

あなたのプロジェクトをこのリストに載せたいですか？ プルリクエストを送ってください.