19 KiB
| draft | aliases | |
|---|---|---|
| false |
|
Conventional Commits 1.0.0
概要
Conventional Commitsの仕様は、コミットメッセージのための軽量の規約です。 明示的なコミット履歴を作成するための簡単なルールを提供します、この規則に従うことで自動化ツールの導入を簡単にします。 この規約はSemVerと組み合わせることで、コミットメッセージへ機能、修正、破壊的変更を入れることで、さらに詳細な説明を可能にします。
コミットメッセージは次のような形にする必要があります
原文：
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
訳：
<型>[任意 範囲]: <説明>
[任意 本文]
[任意 脚注]
コミットにはあなたのライブラリの利用者に思想を伝えるために、次の構造要素を持ちます：
- fix: 型
fixはコードベースのバグにパッチを当てる場合です。（これは セマンティックバージョン管理におけるPATCHに相当します) - feat: 型
featはコードベースに新しい機能を追加した場合です。(これはセマンティックバージョン管理におけるMINORに相当します) - BREAKING CHANGE: 本文 または 脚注 に
BREAKING CHANGE:が存在する、または 型 、 範囲 の直後に!が追加されているコミットは、APIの破壊的変更を意味できます。(セマンティックバージョン管理におけるMAJORに相当します)BREAKING CHANGEはあらゆる 型 のコミットに含めることができます。 fix:andfeat:以外の 型 を許容します、例えば @commitlint/config-conventional ([Angularの規約] (https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)ベース)はbuild:,chore:,ci:,docs:,style:,refactor:,perf:,test:, などがあります。- 次のような規則に従うことで、
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 日本語) で述べられているように 解釈されるべきものです。
- コミットは名詞、
feat、fixなどから始まる（ REQUIRED ） 型 から始まり、次に選択できる（ OPTIONAL ） 範囲 と、必須の!末尾に要求されている（ REQUIRED ）コロンとスペースで成り立ちます。 - コミットがあなたのアプリケーションやライブラリに新しい機能を追加するとき、 型 は
featにしなければならない（ MUST ）。 - コミットがあなたのアプリケーションのためのバグ修正を表すとき、 型 は
fixにしなければならない（ MUST ）。 - 範囲 は 型 の後に記述してもよい（ MAY ）。 範囲 は括弧で囲まれたコードベースのセクションを記述する名詞にしなければならない（ MUST ）。例：
fix(構文解析ツール): - 説明 は型/範囲の後にあるコロンとスペースの直後にしなければならない（ MUST ）。 説明 はコード変更の要約です。 例： fix：文字列に複数の空白がある場合の配列解析における問題
- 短い 説明 の後に、より長いコミットの本文を追加してもよく（ MAY ）、コード変更に関する追加の情報を提供することができます。 本文は、説明 の下に1行の空行を追加しなければならない（ MUST ）。
- コミットの本文は自由形式であってよく（ MAY ）、改行で区切られた複数の段落で構成することが可能です。
- １つ以上のフッターを持つことができます（ MAY ）、フッターは改行の後に一つの空白を持ちます。
各フッターは文字トークンで構成されてなければいけません（ MUST ）、その後に
:<space>か<space>#による区切りが続き、最後に文字列が入ります。（これはgit trailer conventionにインスパイアされています） - 脚注 のトークンには空白の代わりに
-を使う必要があります（ MUST ）、例えばAcked-byなどです（脚注 と 本文 を区別するのに役立ちます ）。BREAKING CHANGEの例外を作ることができ、これはトークンとして使用することもできます（ MAY ）。 - 脚注 の本文にはスペースと改行を含めることができます（ MAY ）、そして次の 脚注 トークンとセパレーターのペアが見つかった時、以前の 脚注 の解析は終了しなければなりません（ MUST ）。
- 破壊的変更は、コミットの 型 / 範囲 の接頭辞か、脚注 に指定する必要があります（ MUST ）
- 破壊的変更がフッターに含まれる場合、大文字の REAKING CHANGE の後にコロンとスペース、そして説明を続ける必要があります（ MUST ）。例： BREAKING CHANGE: 環境変数が設定ファイルよりも優先されるようになりました
- 破壊的変更がある場合、型 や 範囲 の接頭辞には
:の直前に!を用いて明示的にしなければなりません（ MUST ）。!を使用する場合には、 脚注 セクションからBREAKING CHANGE:を省略できます（ MAY ）。そうすると、コミットの 説明 部分で破壊的変更の内容を説明することになるでしょう（ SHALL ）。 - コミットメッセージでは
featとfix以外の 型 を使うことができます（ MAY ）。 （例：docs: ドキュメントの参照を更新） - Conventional Commitsを構成する情報の単位は、必ず大文字の
BREAKING CHANGEを除いて、実装側は大文字と小文字を別の物して扱ってはいけない（ MUST NOT ） - 脚注 の BREAKING-CHANGE は BREAKING CHANGE と同じトークンとして解釈されなければいけません（ 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メッセージを入力するためのフォームを提示することです。
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のガイドラインに触発されており、それに基づいています。
この仕様書の最初のドラフトは、以下に何人かのコントリビューターと共同して書かれました:
- traditional-changelog: git履歴からconventional commitのメッセージを変換するためのツールのセット。
- bumped: ソフトウェアの新しいバージョンをリリースする前後にアクションを実行することを手助けするためのツール。
- unleash: ソフトウェアのリリースを自動化し、ライフサイクルを公開するためのツール。
- lerna: Babelプロジェクトから生まれたモノレポを管理するためのツール。
Conventional Commitsのためのツール一覧
- fastlane-plugin: 仕様に従ってバージョンを管理し、更新ログを自動的生成します。
- php-commitizen: Conventional Commit の仕様に従ってコミットメッセージを作成するためのツール。 composerに依存するPHPプロジェクトに対して設定、使用可能であり、非PHPプロジェクトに対してもグローバルに使用可能。
- conform: conventional commitsを含めたgitリポジトリにポリシーを強制するために使用できるツール。
- standard-version: GitHubの新しいsquashボタンと推奨されているConventional Commitワークフローを使用した、自動のバージョン管理とCHANGELOG管理。
- Git Commit Template: JetBrains Editorsに_Conventional Commits_サポートを追加します。(IntelliJ IDEA, PyCharm, PhpStorm...).
- commitsar: ブランチのコミットがconventional commitに準拠しているかどうかを確認するためのGo言語で書かれたツール。 CI用のDockerイメージがあります。
- semantic-release: 次のバージョン番号の決定、リリースノートの生成、パッケージの公開など、パッケージリリースのワークフロー全体を自動化するツール。
Conventional Commitsを利用しているプロジェクト
- yargs: 多くの人に人気な海賊をテーマにしたコマンドライン引数パーサ。
- istanbuljs: JavaScriptテストにテストのカバレッジを追加するためのオープンソースのツールとライブラリのコレクション。
- uPortal-home と uPortal-application-framework: 追加のApereo uPortalでユーザーインターフェースを強化できます。
- massive.js: NodeとPostgreSQL用のデータアクセスライブラリ。
- electron: JavaScript、HTML、およびCSSを使用してクロスプラットフォームのデスクトップアプリケーションを構築します。
- scroll-utility: 要素のセンタリング、スムーズなスクロールアニメーションを簡単に実現するためのスクロールユーティリティパッケージです。
- Blaze UI: フレームワークに依存しないオープンソースUIツールキット。
- Monica: オープンソースの人的関係管理システム。
- mhy: 🧩 設定不要ですぐに使える多目的ツールボックスおよび開発環境。
- @thi.ng/umbrella: 〜１００からなるデータ駆動型開発用のTypeScriptプロジェクトのMonorepo。
- yii2-basic-firestarter: 🔥 強化されたYii2アプリテンプレート。
- dcyou/resume: 😎 オンライン履歴書を素早く簡単に作成できるテンプレート。
あなたのプロジェクトをこのリストに載せたいですか？ プルリクエストを送ってください.