変更履歴

このガイドには、いつ、どのように変更ログエントリーファイルを作成するのか、また変更ログプロセスに関する情報や歴史についての説明が含まれています。

概要

CHANGELOG.md ファイルの各リスト項目（エントリ）は、Git のコミットの件名から生成されます。コミットにはChangelog Git トレーラーが含まれています。変更ログを生成する際には、作成者とマージリクエストの詳細が自動的に追加されます。

Changelog トレーラーは次の値を受け入れます：

added:新機能
fixed:バグ修正
changed:機能変更
deprecated:新しい非推奨
removed:機能削除
security:セキュリティ修正
performance:パフォーマンス改善
other:その他

変更履歴に含める Git コミットの例を以下に示します：

Update git vendor to gitlab

Now that we are using gitaly to compile git, the git version isn't known
from the manifest, instead we are getting the gitaly version. Update our
vendor field to be `gitlab` to avoid cve matching old versions.

Changelog: changed

マージリクエストが複数のコミットで構成されている場合は、最初のコミットにChangelog のエントリを追加するようにしましょう。こうすることで、コミットが破棄されたときに正しいエントリが生成されるようになります。

GitLab Enterprise の変更点

GitLab Enterprise Edition専用の変更である場合は、トレイラーEE: true を追加する必要があります：

Update git vendor to gitlab

Now that we are using gitaly to compile git, the git version isn't known
from the manifest, instead we are getting the gitaly version. Update our
vendor field to be `gitlab` to avoid cve matching old versions.

Changelog: changed
MR: https://gitlab.com/foo/bar/-/merge_requests/123
EE: true

EE と CE の両方に適用される変更にはトレーラーは追加しないでください。

変更履歴のエントリーを保証するものは何ですか？

通常のマイグレーション、ポストマイグレーション、データマイグレーションを問わず、データベースマイグレーションを導入する変更には、たとえそれが無効化された機能フラグの後ろにあっても、変更ログエントリーが必要です。
セキュリティの修正には、Changelog のトレイラーをsecurity に設定した変更ログエントリが必要です。
ユーザー向けの変更には変更ログエントリが必要です。例”GitLabはすべてのテキストにシステムフォントを使うようになりました。”
私たちのREST APIやGraphQL APIに対するクライアント向けの変更には、必ず変更ログエントリーが必要です。GraphQLの変更を構成する完全なリストをご覧ください。
高度な検索マイグレーションを導入するすべての変更には、変更ログエントリーが必要です。
リグレッションが導入され、同じリリースで修正された場合 (月例リリース候補で導入されたバグの修正など) は、変更履歴エントリを持つべきではありません。
開発者向けの変更 (リファクタリング、技術的負債の修正、テストスイートの変更など) は、変更ログエントリを持つべきではありません。例”サイクルアナリティクスのモデル仕様で作成されたデータベースレコードを減らす”
貢献者が望むのであれば、コミュニティメンバーからの_貢献は_、どんなに小さくても、これらのガイドラインに関係なく、変更履歴を持つことができます。
実験的な変更には変更履歴エントリをつけるべきではありません。
ドキュメントの変更のみを含む MR は、変更履歴エントリを持つべきではありません。

詳しくは、機能フラグによる変更ログエントリの扱い方を参照してください。

良い変更ログエントリーを書く

良い変更ログエントリは、説明的で簡潔であるべきです。その変更についての_文脈を全く_知らない読者に対して、その変更を説明するものでなければなりません。簡潔かつ説明的なエントリーにするのが難しい場合は、説明的なほうを選んでください。

悪い例プロジェクトオーダーへ。
良いGo to project “ドロップダウンリストの一番上にユーザーのスター付きプロジェクトを表示します。

最初の例では、どこで変更されたのか、なぜ変更されたのか、ユーザーにどのようなメリットがあるのか、などのコンテキストがありません。

悪い例テキストを）クリップボードにコピーします。
良いクリップボードにコピー」のツールチップを更新して、何がコピーされているかを表示するようにしました。

繰り返しになりますが、最初の例は漠然としすぎていて、何の脈絡もありません。

悪い点ミニパイプライングラフとビルドダウンリストのCSSとHTMLの問題の修正と改善。
良いミニパイプライングラフとビルドドロップダウンリストのツールチップとホバー状態を修正。

最初の例は、実装の詳細に焦点を当てすぎています。ユーザーは、私たちがCSSやHTMLを変更したことなど気にしていません。

Bad：から返されたコミット・オブジェクトの配列からnilを取り除きます。find_commits_by_message_with_elastic
良いElasticsearch の結果がガベージコレクションされたコミットを参照することで発生する 500 エラーを修正

最初の例は、何を修正_したかではなく_、どのように_修正したかに焦点を当てています。書き直したバージョンでは、ユーザーにとっての_最終的なメリット（500エラーの減少）と、いつ（Elasticsearchでコミットを検索する）かを明確に記述しています。

あなたの最善の判断で、コンパイルされた変更履歴を読む人の気持ちになってみてください。このエントリは付加価値がありますか？その変更が_どこで_ _なぜ_行われたのか、コンテキストを提供していますか？

変更履歴の作成方法

Git Trailer は、変更をコミットするときに追加されます。これは、お好みのテキストエディタで行うことができます。既存のコミットにトレイラーを追加するには、そのコミットを (最新のものであれば) 修正するか、git rebase -i を使って対話的にリベースする必要があります。

最後のコミットを更新するには、以下を実行してください：

git commit --amend

そして、コミットメッセージにChangelog を追加します。以前のコミットをすでにリモートブランチにプッシュしていた場合は、新しいコミットを強制的にプッシュしなければなりません：

git push -f origin your-branch-name

古いコミット (あるいは複数のコミット) を編集するにはgit rebase -i HEAD~N を使用します。N はリベースする直近の N 個のコミットです。ブランチに 3 つのコミットがあるとしましょう：コミット B を更新したい場合は、次のように実行します：

git rebase -i HEAD~2

これは、直近の二つのコミットに対する対話的なリベースセッションを開始します。Git が起動すると、次のような内容のテキストエディタが表示されます：

pick B Subject of commit B
pick C Subject of commit C

コミット B を更新するには、pick をreword に変更します。いったん閉じると、GitはコミットBのコミットメッセージを編集するための新しいテキストエディタのインスタンスを表示します。トレイラーを追加し、保存してエディターを終了します。これで、コミット B が更新されました。

対話的リベースについての詳細はGit のドキュメントを参照ください。

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

変更履歴

概要

関連するマージリクエストの上書き

GitLab Enterprise の変更点

変更履歴のエントリーを保証するものは何ですか？

良い変更ログエントリーを書く

変更履歴の作成方法

Help & feedback

Docs

Product

Feature availability and product trials

Get Help