From 736b6bac34dd656657ff5313b1d720c02b993c66 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tetsuaki=20Hamano=20/=20=E6=B5=9C=E9=87=8E=20=E5=93=B2?= =?UTF-8?q?=E6=98=8E?= Date: Sun, 17 Sep 2023 08:04:46 +0000 Subject: [PATCH] translate/best-practices/commit-messages.md --- core/best-practices/commit-messages.md | 218 ++++++++++++++++++++++++- 1 file changed, 209 insertions(+), 9 deletions(-) diff --git a/core/best-practices/commit-messages.md b/core/best-practices/commit-messages.md index dfe207c..6b74deb 100644 --- a/core/best-practices/commit-messages.md +++ b/core/best-practices/commit-messages.md @@ -1,57 +1,143 @@ + +# コミットメッセージ + + + +コミットメッセージは、WordPress がどのように開発されてきたかを示す重要な要素です。チェンジセットそのものとともに、プロジェクトの歴史の重要な一部です。私たちは、同世代の人々 (コア開発者達、プラグイン開発者、コア開発に関わる人々)、将来の貢献者、そしてコンピューターという対象者の読者に向けてコミットメッセージを書きます。優れたコミットメッセージは、これらの対象者のそれぞれに有益です。コミットメッセージは、チェンジセットの「内容」、「理由」を記述します。「どのように」は diff 自体によって記述されます。 + + +たとえあなたがコミッターでなくても、WordPress への貢献や自分のプロジェクトでこれらのガイドラインを活用できます。ここで概説されている懸念事項に配慮した方法でパッチを記述することで、あるいは自分自身でコミットメッセージを作成することで、コミッターがあなたの貢献を迅速に処理しやすくなります。 + +注意: 同じコミットで複数のブランチにコミットしないでください。これは、少なくとも Git ミラーを壊すことになります。 + + + +## フォーマット + + +コミット メッセージの一般的な形式は次のとおりです: > Component: Brief summary. -> +> > Longer description with more details, such as a \`new\_hook\` being introduced with the context of a \`$post\` and a \`$screen\`. -> +> > More paragraphs can be added as needed. -> -> Props person, another. +> +> Props person, another. > Fixes [#30000](https://core.trac.wordpress.org/ticket/30000). See [#20202](https://core.trac.wordpress.org/ticket/20202), #105. + +一般的に、コミットメッセージの各行は大文字で始まり、フルストップまたはピリオドで終わります。関数名やフックのようなコードは、Trac や Slack で適切な書式になるように、バッククオートの内側に記述する必要があります。チケット番号の前に数字記号[#20202](https://core.trac.wordpress.org/ticket/20202)がつき、角括弧内のリビジョン番号[\[30000\]](https://core.trac.wordpress.org/changeset/30000) は、Trac、Slack、そしてここ make/core で自動リンクされます。 + + + +### 簡単な要約 + + +コミットメッセージの最初の行は、チェンジセットの簡単な要約です。これはメールの件名や Trac の変更履歴、および `git log --format=oneline` などのほとんどの VCS のログ形式で目立つ機能で使用されます。要約は目につきやすいため、スペースの制限内でできるだけ説明的な内容を作成することが重要です。 + +#### ガイドライン + + + +* 1行であり、改行を入れてはいけません。 +* およそ50文字以内、長くても70文字までにします。ログ閲覧ツールはほぼすべて、コミットメッセージの最初の行がこの制限内に収まることを期待しているので、これは重要です。この厳しい制限は、コミットの本質について批判的に考えさせることになるかもしれません。短い文章で変更を説明できない場合、コミットが必要以上に大きなものであるかもしれません。 +* 変更のコンポーネントまたは焦点を要約の前に付けることができます。このような接頭辞をつけることで、貢献者が興味のあるコミットを変更履歴から探しやすくなるかもしれません。例として、[\[33901\]](https://core.trac.wordpress.org/changeset/33901)、[\[33883\]](https://core.trac.wordpress.org/changeset/33883)、[\[33848\]](https://core.trac.wordpress.org/changeset/33848)を参照してください。接頭辞も50/70文字にカウントされることに注意してください。 +* 可能であれば、「Relaxes term ID comparisons…」の代わりに「Relax term ID comparisons…」という命令形を使用します。 + +### 説明 + + + +コミットに関するより長い説明には、そのコミットの詳細と開発者への影響を含めるべきです。これには、新しいフック、「gotchas (見落としやすい点)」、検討された他の解決策、背景などが含まれるかもしれません。コミットメーリングリストをフォローしている開発者、各リリースの開発者ノートや WordPress Core Weekly のために情報をまとめているボランティア、そして誰が何をなぜ行ったのかを解明しようとしている人などです。 + + +#### ガイドライン + +* 要約と空白行で区切らなければなりません。 +* 必要であれば、空行で区切って複数の段落にできます。コミットメッセージが最終的な変更セットそのものよりも冗長である場合もあります。 +* 要約とは異なり、行を手動で折り返す必要はありません。必要に応じて、ログ ビューア自身が説明を折り返すことができます。 + + + +### Props (称賛) + + +パッチ、更新されたパッチ、提案されたコード、デザイン、ライティング、ユーザーテスト、その他多大な時間と労力を費やして最終的なコミットに貢献したすべての人に賞賛が贈られるべきです。ユーザー名はクレジットリストと WordPress.org プロフィールのために解析されます。 + +バグレポートの場合、バグの報告者にも props が与えられるべきです。 + + + +重複としてクローズされたチケットも、props に値する貢献が含まれている可能性があるためチェックしてください。 + + +#### ガイドライン + +* 先頭には空白行が必要です。 +* ユーザー名は `@` (アット) 記号で始めることはできません。 +* ユーザー名はカンマとスペースで区切ってください。正規表現: `/^props (\s*([^,]+),?)+$/` +* タイプミスを避けるため、ユーザー名はコピー & ペーストしてください。(ごめんなさい、rmccue さん。それとも rmmcue さんですか ?) +* ユーザーの表示名にスペースがある場合は、w.org プロフィールの URL のスラッグを使用してください。たとえば、Trac の `Frank Klein` は `frank-klein` として props を取得する必要があります。 +* Props は自由に与える側に回ってください。Props は貢献者に大きな励ましを与えます。 +* もし誰かに props を与えることを忘れた場合、その人が現在のリリースですでに props を与えられているかどうか確認してください。与えられていれば、いずれにしてもリリースクレジットに含まれるため、長期的には問題とはなりません。まだ props が与えられていなければ、[リリースコーディネーター](https://make.wordpress.org/core/handbook/about/release-cycle/wordpress-release-team-and-focus-leads/#release-co-ordinator)に連絡し、リリース日にその人が追加されるようにすることができます。また、礼儀として Slack やチケットのコメントで貢献者に連絡を取り、コミットメッセージに名前がなかったことをお詫びし、彼らの貢献が評価されることとその方法を伝えることを推奨します。 + + + +#### 自分の props + +* 大きな機能、API、特にやっかいなバグなど、コミットが複数の人関わった多大な努力の結果である場合は、自分自身に props を与えてください。 +* 一般的に、貢献者にパッチに対するフィードバックを提供し、反復する機会を与えることが推奨されるプロセスです。ただし、コミッターであるあなたがパッチのアイデアを完成させる場合には、「props X for initial patch.」と書くこともできます。 +* コミッターがコミットの前にスタイルを調整したり、ロジックを並べ替えたり、あるいは単純なエッジケースを考慮したりするのはよくあることです。このような場合、自分自身を省略してください。コミット上のあなたの名前は、あなたがそれをレビューしてテストしたことを暗示しており、これはコミットの内容と同じくらい重要です。 +* 自分自身のコードをコミットする場合は、props が前提となりますので、ここでも自分自身を省略します。 + + + +### チケットリファレンス + + +Trac は、「fixes」や「see」として参照されたチケットにコメントとしてコミットメッセージを追加します。コミットメッセージに「Fixes [#12345](https://core.trac.wordpress.org/ticket/12345)」というテキストが含まれている場合、 Trac はチケット[#12345](https://core.trac.wordpress.org/ticket/12345)をクローズし、まだ所有者がいなければあなたを所有者にします。 + +#### ガイドライン + + + +* チケットリファレンスは、props の直下の行に記述してください。props がない場合は、空の改行で上のコンテンツと区切ります。 +* 複数のチケットはカンマとスペースで区切ります。 +* 修正されたチケットと関連されたチケットの両方を参照する場合は、「Fixes」で始めて各セットをピリオドで終了します。たとえば「Fixes [#19867](https://core.trac.wordpress.org/ticket/19867), [#9864](https://core.trac.wordpress.org/ticket/9864). See [#31696](https://core.trac.wordpress.org/ticket/31696).」などです。セット内の項目が多い場合は、別の行に入れます。 +* チケット番号を入れ忘れた場合は、チケットにコメントを残します (例: 「Fixed in \[changeset\_number\]」。オプションでコミットメッセージのコピーを付けると、トレーサビリティを確保しやすくなります)。 + + +## 例 + + +悪い: > Don’t use strict comparisons for term IDs. props booneiscool. fixes [#3398](https://core.trac.wordpress.org/ticket/3398). + + +まあまあ良い: > Fixing \`wp\_dropdown\_categories()\` and other places that use term IDs. -> +> > props boonerocks. fixes [#20000](https://core.trac.wordpress.org/ticket/20000). + + +良い: > Taxonomy: Relax term ID comparisons. -> +> > Term IDs are sometimes provided as strings. This is particularly evident in \`wp\_dropdown\_categories()\`, where the \`selected\` argument was not being respected. Plugin authors should also be wary of using strict comparisons for term IDs. -> -> Props booneistheman. +> +> Props booneistheman. > Fixes [#13237](https://core.trac.wordpress.org/ticket/13237). + +## コミットメッセージを自動的に事前入力する + + + +Git を使用している場合 (場合によっては git-svn を使用してコミットしている場合)、フックによって新しいコミット メッセージを標準形式で自動的に埋め込むことができます。 Create a `.git/hooks/prepare-commit-msg` file with the following script, and then `chmod +x .git/hooks/prepare-commit-msg`. +次のスクリプトを使用して `.git/hooks/prepare-commit-msg` ファイルを作成し、`chmod +x .git/hooks/prepare-commit-msg` を実行します。 + ```bash #!/bin/bash COMMIT_MSG_FILE=$1 @@ -130,14 +281,31 @@ Fixes #30000. See #20202, #105. echo "$template" > $COMMIT_MSG_FILE ``` + + +## コミッター向けのその他のヒント + + +これらはコミットメッセージそのものに関するものではありませんが、以下のガイドラインは覚えておくとよいでしょう。 + +RC の段階では、コミットされる前に[すべてのパッチは2人目のコミッターのレビューを受ける必要があります](https://make.wordpress.org/core/handbook/about/release-cycle/releasing-major-versions/#release-candidate)。 + + + +### コミットの前 + +* パッチが受け入れられるかどうか疑問がある場合は、他のコミッターにセカンドオピニオンを求めてください。 +* 変更された行が[コーディング規約](https://make.wordpress.org/core/handbook/best-practices/coding-standards/)に準拠していることを確認してください。 + * PHP + * 変更されたすべてのファイルのすべての行をチェックするには、`phpcs $(git diff trunk --name-only)` または `phpcs $(svn stat | grep "\(M \|A \)" | grep -v "external item" | cut -c8-)` を実行します。 + * 変更された行だけをチェックするには、[wp-dev-lib](https://github.com/xwp/wp-dev-lib/) をクローンし、`DIFF_BASE=trunk DEV_LIB_ONLY=phpsyntax,phpcs /path/to/wp-dev-lib/pre-commit` を[実行](https://github.com/xwp/wp-dev-lib/#manually-invoking-pre-commit)します。ローカルブランチが `trunk` 以外である必要があり、変更がコミットされているか、コミット用にステージされている必要があることに注意してください。ステージされていない変更はスキャンされません。 + * これらのコマンドは、Bash でエイリアスを作成することをおすすめします。 + * JavaScript + * `npm run grunt jshint` を[実行](https://make.wordpress.org/core/handbook/best-practices/coding-standards/javascript/#jshint)します。これは `npm run grunt precommit` でも自動的に行われます。 + * HTML、CSS、a11y + * これらは手動でチェックする必要があります。 +* `npm run grunt build && npm run grunt precommit` を実行します。これにより、PHP と JavaScript の自動テストスイートが実行され、CSS や画像などのさまざまなタスクも実行されます。 + * 変更内容によっては、PHPUnit をさまざまなフラグをつけて手動で実行する必要があるかもしれません。 +* 最後にもう一度完全な diff をチェックします (`svn diff`)。Git を使用している場合は、インタラクティブなステージング (`git add -p`) は個々のチャンクをレビューするのに良い方法です。 +* 変更されたファイルのリストをチェックし (`svn stat`)、新しいファイルが追加されていることを確認します。新しいファイルを追加するパッチを適用すると、新しいファイルの内容が重複してしまうことがあるため、新しいファイルの内容を再確認することもおすすめします。また、新しいファイルの名前が `$_old_files` 配列にあるものと同じでないことを確認してください。そうしないと、すぐにまた削除されてしまいます。もし同じ名前がある場合は、同じ名前のファイルがいつ追加され戻されたかを示すメモを添えて、配列からその行をコメントアウトしてください。その行は削除しないでください。 +* ファイルを削除する場合は、それらを `$_old_files` 配列に追加します。 +* `svn switch ^/branches/4.3 && svn merge -c 12345 ^/trunk` を使用して、`trunk` からリリースブランチへのコミットを「チェリーピック」できます。コミットする前にメッセージを編集するように求められます。詳しくは[コミットのバックポート](https://make.wordpress.org/core/handbook/best-practices/backporting-commits/) を参照してください。 +* リリースのタグ付けとブランチの手順は、[メジャーバージョンのリリースｎコアセクション](https://make.wordpress.org/core/handbook/about/release-cycle/releasing-major-versions/#core)ページにあります。 +* ヒント: 追跡されていないファイルを含めずに変更されたファイルを表示するには、次のように Bash のエイリアスまたは関数として追加してください: `svn stat --ignore-externals | grep '^[^?X]'` + + + +### コミットの後 + +* 他の環境でテストが失敗した場合に備えて、[GitHub Actions](https://github.com/WordPress/wordpress-develop/actions) で対応するジョブを監視します。 + + + +## その他のリソース * [A Note About Git Commit Messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) * [5 Useful Tips For A Better Commit Message](https://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message) -* [How to Write a Git Commit Message](http://chris.beams.io/posts/git-commit/) \ No newline at end of file +* [How to Write a Git Commit Message](http://chris.beams.io/posts/git-commit/)