変更履歴

このガイドには、いつ、どのように変更ログエントリファイルを生成するかという説明と、変更ログプロセスに関する情報と履歴が含まれています。 これらのエントリは後で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の主要なコードベースから採用されました。

開発者のドキュメントに戻る