変更履歴
このガイドには、いつ、どのように変更ログエントリファイルを生成するかという説明と、変更ログプロセスに関する情報と履歴が含まれています。 これらのエントリは後でchangelog_managerによってインテグレーションされます。
概要
CHANGELOG.md
ファイルのそれぞれの箇条書き、もしくはエントリーは、changelogs/unreleased/
フォルダにある1つのデータファイルから生成されます。このファイルは以下のフォーマットのYAMLファイルであることが期待されます:
---
title: "Change[log]s"
merge_request: 1972
author: Black Sabbath
type: added
merge_request
の値はこのエントリを追加するマージリクエストへの参照で、author
のキーはコミュニティの貢献者への帰属を示すために使用されます。どちらも省略可能です。type
フィールドは変更のカテゴリをマップします。有効なオプションは次のとおりです: 追加、修正、変更、非推奨、削除、セキュリティ、その他。Type フィールドは必須です。
コミュニティ貢献者とコアチームメンバーは、author
に自分の名前を追加することをお勧めします。GitLabチームメンバーは追加しないでください。
変更履歴を記載する理由は何ですか?
- ユーザー向けの変更には、変更履歴のエントリーが必要です。 例:”GitLab now uses system fonts for all text”(GitLabはすべてのテキストにシステムフォントを使うようになりました。
- リグレッションが導入され、同じリリースで修正された場合(つまり、毎月のリリース候補で導入されたバグを修正した場合)は、変更履歴エントリを持つべきではありません。
- 開発者向けの変更(例:リファクタリング、技術的負債の修正、テストスイートの変更)は、変更ログエントリーを持つべきではありません。 例:”Cycle Analytics モデル仕様の間に作成されたデータベースレコードを削減する”。
- コミュニティメンバーからの_貢献は_、どんなに小さなものであっても、貢献者が望むのであれば、このガイドラインに関係なく、変更履歴を記載することができます。 例:”検索結果ページのタイプミスを修正しました。 (Jane Smith)”
良い変更履歴の書き方
良い変更ログエントリーは、説明的で簡潔であるべきです。 その変更についての_文脈を全く_知らない読者に対して、その変更を説明するものでなければなりません。 簡潔と説明的の両方を作るのが難しい場合は、説明的の側を選んでください。
- 悪い:プロジェクトオーダーへ。
- Good:「Go to project」ドロップダウンの一番上に、ユーザーのスター付きプロジェクトを表示。
最初の例では、その変更がどこでなされたのか、なぜなされたのか、それがユーザーにどのような利益をもたらすのか、といった文脈がまったく示されていません。
- 悪い例:(テキストを)クリップボードにコピーします。
- Good:「クリップボードにコピー」ツールチップを更新し、何がコピーされているかを表示するようにしました。
繰り返しますが、最初の例は漠然としすぎていて、何の脈絡もありません。
- Bad:ミニパイプライングラフとビルドドロップダウンのCSSとHTMLの問題の修正と改善。
- Good:ミニパイプライングラフとビルドドロップダウンのツールチップとホバー状態を修正。
最初の例は、実装の細部にこだわりすぎています。 ユーザーは、CSSやHTMLを変更したことなど気にしていません。
-
悪い:から返されたコミット・オブジェクトの配列から
nil
を取り除きます。find_commits_by_message_with_elastic
- Good:Elasticsearch の結果がガベージコレクションされたコミットを参照することで発生する 500 エラーを修正しました。
最初の例では、何を修正_したかではなく_、どのように_修正したかに焦点を当てています。 書き換えたバージョンでは、ユーザーにとっての_最終的なメリット(500エラーの減少)と、いつ(Elasticsearchでコミットを検索する)かを明確に説明しています。
あなたの最善の判断で、編集された変更履歴を読む人の気持ちになってみてください。 このエントリーは付加価値がありますか?どこで、_なぜ_その変更がなされたのか、文脈を提供していますか?
変更履歴の作成方法
bin/changelog
スクリプトは、変更ログエントリーファイルを自動的に生成するために利用できます。
最も単純な使い方は、title
の値を提供することです:
bin/changelog 'Hey DZ, I added a feature to GitLab!'
この時点で、スクリプトは変更のカテゴリーを選択するよう求めます(エントリーのtype
フィールドにマッピングされます):
>> Please specify the category of your change:
1. New feature
2. Bug fix
3. Feature change
4. New deprecation
5. Feature removal
6. Security fix
7. Other
エントリーのファイル名は、現在の Git ブランチの名前に基づいています。上のコマンドをfeature/hey-dz
というブランチで実行すると、changelogs/unreleased/feature-hey-dz.yml
というファイルが生成されます。
コマンドは生成されたファイルのパスとその内容を出力します:
create changelogs/unreleased/my-feature.yml
---
title: Hey DZ, I added a feature to GitLab!
merge_request:
author:
type:
議論
議論 | 速記 | 目的 |
---|---|---|
--amend
| 前回のコミットを修正 | |
--force
| -f
| 既存のエントリーを上書き |
--merge-request
| -m
| マージリクエストIDの設定 |
--dry-run
| -n
| 実際には何も書かず、ただ印刷するだけです |
--git-username
| -u
| gitのuser.nameの設定を作成者として使用します。 |
--type
| -t
| 有効なオプションは、追加、修正、変更、非推奨、削除、セキュリティ、その他です。 |
--help
| -h
| ヘルプメッセージの印刷 |
--amend
--amend
引数を渡すと、生成されたファイルを自動的にステージし、前回のコミットに修正します。
--amend
を使ってタイトルを指定しなかった場合は、自動的に直前のコミットの “subject” が使われます。これはコミットメッセージの最初の行です:
$ git show --oneline
ab88683 Added an awesome new feature to GitLab
$ bin/changelog --amend
create changelogs/unreleased/feature-hey-dz.yml
---
title: Added an awesome new feature to GitLab
merge_request:
author:
type:
--force
または-f
--force
または -f
を使って、既存の changelog エントリがすでに存在する場合は上書きしてください。
$ bin/changelog 'Hey DZ, I added a feature to GitLab!'
error changelogs/unreleased/feature-hey-dz.yml already exists! Use `--force` to overwrite.
$ bin/changelog 'Hey DZ, I added a feature to GitLab!' --force
create changelogs/unreleased/feature-hey-dz.yml
---
title: Hey DZ, I added a feature to GitLab!
merge_request: 1983
author:
type:
--merge-request
または-m
merge_request
の値を指定するには、--merge-request
または -m
の引数を使用します:
$ bin/changelog 'Hey DZ, I added a feature to GitLab!' -m 1983
create changelogs/unreleased/feature-hey-dz.yml
---
title: Hey DZ, I added a feature to GitLab!
merge_request: 1983
author:
type:
--dry-run
または-n
実際に何かを書いたりコミットしたりしないようにするには、--dry-run
または -n
引数を使います:
$ bin/changelog --amend --dry-run
create changelogs/unreleased/feature-hey-dz.yml
---
title: Added an awesome new feature to GitLab
merge_request:
author:
type:
$ ls changelogs/unreleased/
--git-username
または-u
--git-username
または -u
の引数を使うと、設定した gituser.name
の値でauthor
の値を自動的に埋めることができます:
$ git config user.name
Jane Doe
$ bin/changelog -u 'Hey DZ, I added a feature to GitLab!'
create changelogs/unreleased/feature-hey-dz.yml
---
title: Hey DZ, I added a feature to GitLab!
merge_request:
author: Jane Doe
type:
--type
または-t
type
の値を指定するには、--type
または -t
の引数を使用します:
$ bin/changelog 'Hey DZ, I added a feature to GitLab!' -t added
create changelogs/unreleased/feature-hey-dz.yml
---
title: Hey DZ, I added a feature to GitLab!
merge_request:
author:
type: added
歴史と推論
この方法は、GitLabの主要なコードベースから採用されました。