Conventional Commits

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

Conventional Commits 1.0.0-beta.4

概要

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

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


原文:

<type>[optional scope]: <description>

[optional body]

[optional footer]

訳:

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

[任意 本文]

[任意 脚注]


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

  1. fix: fix はコードベースのバグにパッチを当てる場合です。(これは セマンティックバージョン管理におけるPATCHに相当します)
  2. feat: feat はコードベースに新しい機能を追加した場合です。(これはセマンティックバージョン管理における MINORに相当します)
  3. BREAKING CHANGE: 本体または脚注の冒頭に BREAKING CHANGE: という内容があるコミットは、APIの重大な変更を意味できます。(セマンティックバージョン管理におけるMAJORに相当します) BREAKING CHANGE はあらゆる のコミットに含めることができます。

  4. Others: fix: and feat: 以外のコミット を許容します、例えば @commitlint/config-conventional (Angularの規約ベース)は chore:, docs:, style:, refactor:, perf:, test:, などがあります。

新しい機能の追加やバグを修正ではなく、現在の実装を改善するコミットには improvement をおすすめします。

これらの は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

重大な変更であることに気づいてもらうために ! を付けてメッセージをコミットできる

chore!: drop Node 6 from testing matrix

BREAKING CHANGE: dropping Node 6 which hits end of life in April

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

docs: correct spelling of CHANGELOG

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

feat(lang): add polish language

(オプション) issueの番号を修正用のコミットメッセージに含めます

fix: correct minor typos in code

see the issue for details on the typos fixed

closes issue #12

仕様

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

  1. コミットは から始まり、次に選択できる( OPTIONAL ) 範囲 と、末尾に要求されている( REQUIRED )コロンとスペースで成り立ちます。
  2. コミットがあなたのアプリケーションやライブラリに新しい機能を追加するとき、 featにしなければならない( MUST )。
  3. コミットがあなたのアプリケーションのためのバグ修正を表すとき、 fixにしなければならない( MUST )。
  4. 範囲 の後に記述してもよい( MAY )。 範囲 は括弧で囲まれたコードベースのセクションを記述する名詞にしなければならない( MUST )。例: `fix(構文解析ツール): ‘
  5. 説明 は型/範囲の直後にしなければならない( MUST )。 説明 はコード変更の要約です。 fix:文字列に複数の空白がある場合の配列解析における問題
  6. 短い 説明 の後に、より長いコミットの本文を追加してもよく( MAY )、コード変更に関する追加の情報を提供することができます。 本文は、説明 の下に1行の空行を追加しなければならない( MUST )。
  7. 1行以上の 脚注 は、本文の後ろに1行の空白行を入れてもよい( MAY )。 脚注 はコミットに関するメタ情報、例えば関連するプルリクエスト、レビュアー、変更の中断などを1行につき1つのメタ情報として含めなければならない( MUST )。
  8. 重大な変更(BREAKING CHANGE)は、本文セクションの一番最初、または脚注の先頭にしなければいけません( MUST )。 重大な変更は大文字のテキスト BREAKING CHANGE と続くコロンとスペースから構成されなければいけません( MUST )。
  9. APIについて何が変わったのかを説明するBREAKING CHANGE:の後には説明を描かなければいけません( MUST )。 例、 BREAKING CHANGE: 環境変数が設定ファイルよりも優先されるようになりました。
  10. featfix 以外の をあなたのコミットメッセージに仕様してもよい( MAY )。
  11. Conventional Commitsを構成する情報の単位は、必ず大文字のBREAKING CHANGEを除いて、実装側は大文字と小文字を別の物して扱ってはいけない( MUST NOT )
  12. さらに重大な変更の注意を引くために、 種類 / 範囲: の前に !を追加することができます( MAY )。BREAKING CHANGE: descriptionは、接頭辞の!とともに、本文または脚注にも含めなければなりません( 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 Commitの仕様は、Angular Commitのガイドラインに触発されており、それに基づいています。

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

Conventional Commitsのためのツール一覧

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

Conventional Commits

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