変更履歴
このガイドには、いつ、どのように変更ログエントリーファイルを作成するのか、また変更ログプロセスに関する情報や歴史についての説明が含まれています。
概要
CHANGELOG.md の各項目は Git のコミットの件名から生成されます。コミットにはChangelog Git トレーラーが含まれています。変更ログを生成する際には、作成者とマージリクエストの詳細が自動的に追加されます。
Changelog トレーラーは次の値を受け入れます：
- 追加
- 固定
- 変更済み
- 非推奨
- 削除
- セキュリティ
- パフォーマンス
- その他
変更履歴に含める 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
GitLab は変更ログを生成するときに、マージリクエストを自動的にコミットにリンクします。リンクするマージリクエストを上書きしたい場合は、MR トレーラーを使って別のマージリクエストを指定することができます：
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
この値はマージリクエストの完全なURLでなければなりません。
変更履歴のエントリーを保証するものは何ですか？
- ユーザー向けの変更には変更ログエントリが必要です。例”GitLabは全てのテキストにシステムフォントを使うようになりました。”
- リグレッションが導入され、同じリリースで修正された場合(つまり、毎月のリリース候補で導入されたバグを修正した場合)は、変更履歴エントリを持つべきではありません。
- 開発者向けの変更 (リファクタリング、技術的負債の修正、テストスイートの変更など) は、変更ログエントリを持つべきではありません。例”サイクルアナリティクスのモデル仕様で作成されたデータベースレコードを減らす”
- コミュニティメンバーからの_貢献は_、どんなに小さくても、貢献者が望むなら、このガイドラインに関係なく、変更履歴を持つことができます。例「検索結果ページのタイプミスを修正しました。(Jane Smith)”
良い変更ログエントリーを書く
良い変更ログエントリは、説明的で簡潔であるべきです。その変更についての_文脈を全く_知らない読者に対して、その変更を説明するものでなければなりません。簡潔かつ説明的なエントリーにするのが難しい場合は、説明的なほうを選んでください。
- 悪い例プロジェクトオーダーへ。
- 良い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の主要なコードベースから採用されました。