Conventional Commits 1.0.0-beta.4
概要
Conventional Commitsの仕様は、コミットメッセージのための軽量の規約です。 明示的なコミット履歴を作成するための簡単なルールを提供します、この規則に従うことで自動化ツールの導入を簡単にします。 この規約はSemVerと組み合わせることで、コミットメッセージへ機能、修正、重大な変更を入れることで、さらに詳細な説明を可能にします。
コミットメッセージは次のような形にする必要があります
原文:
<type>[optional scope]: <description>
[optional body]
[optional footer]
訳:
<型>[任意 範囲]: <説明>
[任意 本文]
[任意 脚注]
コミットにはあなたのライブラリの利用者に思想を伝えるために、次の構造要素を持ちます:
-
fix: 型
fix
はコードベースのバグにパッチを当てる場合です。(これは セマンティックバージョン管理におけるPATCH
に相当します) -
feat: 型
feat
はコードベースに新しい機能を追加した場合です。(これはセマンティックバージョン管理におけるMINOR
に相当します) -
BREAKING CHANGE: 本体または脚注の冒頭に
BREAKING CHANGE:
という内容があるコミットは、APIの重大な変更を意味できます。(セマンティックバージョン管理におけるMAJOR
に相当します)BREAKING CHANGE
はあらゆる 型 のコミットに含めることができます。 -
Others:
fix:
andfeat:
以外のコミット 型 を許容します、例えば @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 (JPNIC 日本語) で述べられているように 解釈されるべきものです。
- コミットは 型 から始まり、次に選択できる( OPTIONAL ) 範囲 と、末尾に要求されている( REQUIRED )コロンとスペースで成り立ちます。
- コミットがあなたのアプリケーションやライブラリに新しい機能を追加するとき、 型 は
feat
にしなければならない( MUST )。 - コミットがあなたのアプリケーションのためのバグ修正を表すとき、 型 は
fix
にしなければならない( MUST )。 - 範囲 は 型 の後に記述してもよい( MAY )。 範囲 は括弧で囲まれたコードベースのセクションを記述する名詞にしなければならない( MUST )。例: `fix(構文解析ツール): '
- 説明 は型/範囲の直後にしなければならない( MUST )。 説明 はコード変更の要約です。 fix:文字列に複数の空白がある場合の配列解析における問題
- 短い 説明 の後に、より長いコミットの本文を追加してもよく( MAY )、コード変更に関する追加の情報を提供することができます。 本文は、説明 の下に1行の空行を追加しなければならない( MUST )。
- 1行以上の 脚注 は、本文の後ろに1行の空白行を入れてもよい( MAY )。 脚注 はコミットに関するメタ情報、例えば関連するプルリクエスト、レビュアー、変更の中断などを1行につき1つのメタ情報として含めなければならない( MUST )。
- 重大な変更(
BREAKING CHANGE
)は、本文セクションの一番最初、または脚注の先頭にしなければいけません( MUST )。 重大な変更は大文字のテキストBREAKING CHANGE
と続くコロンとスペースから構成されなければいけません( MUST )。 - APIについて何が変わったのかを説明する
BREAKING CHANGE:
の後には説明を書かなければいけません( MUST )。 例、 BREAKING CHANGE: 環境変数が設定ファイルよりも優先されるようになりました。 feat
とfix
以外の 型 をあなたのコミットメッセージに仕様してもよい( MAY )。- Conventional Commitsを構成する情報の単位は、必ず大文字の
BREAKING CHANGE
を除いて、実装側は大文字と小文字を別の物して扱ってはいけない( MUST NOT ) - さらに重大な変更の注意を引くために、 種類 / 範囲 の
:
の前に!
を追加することができます( MAY )。BREAKING CHANGE: description
は、接頭辞の!
とともに、本文または脚注にも含めなければなりません( MUST )。
何故 Conventional Commits を使うのか
- 変更履歴(CHANGELOG)を自動的に生成できます。
- semantic version単位で自動的に履歴を纏めれます(コミットされた 型 に基づきます)。
- チームメイトや一般のユーザー、およびその他の利害関係者へ変更の内容を伝えることができる。
- ビルドおよび公開プロセスをトリガーにできます。
- より構造化されたコミット履歴を調査できるようにすることで、人々があなたのプロジェクトに貢献しやすくなります。
よくある質問
初期の開発段階ではコミットメッセージをどのように扱うべきですか?
すでに製品をリリースしているかのように進めることをお勧めします。 あなたの仲間のソフトウェア開発者であっても、普通は 誰か があなたのソフトウェアを使っています。 何が修正されたのか、何が壊れたのかなどを知りたいでしょう。
コミットタイトル(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メッセージを入力するためのフォームを提示することです。