From: Akiyoshi Kurita Date: Mon, 9 Mar 2026 10:50:15 +0000 (+0900) Subject: docs: ja_JP: process: translate second half of 'Describe your changes' X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=0a4f3ef9880e505d41817419b0255d6552776143;p=thirdparty%2Fkernel%2Flinux.git docs: ja_JP: process: translate second half of 'Describe your changes' Translate the remaining part of the "Describe your changes" section in Documentation/translations/ja_JP/process/submitting-patches.rst. Follow review comments on wording and line wrapping, and cover guidance on self-contained patch descriptions, imperative mood, commit references, and Link:/Closes:/Fixes: tags. Signed-off-by: Akiyoshi Kurita Acked-by: Akira Yokosawa Signed-off-by: Jonathan Corbet Message-ID: <20260309105015.309116-1-weibu@redadmin.org> --- diff --git a/Documentation/translations/ja_JP/process/submitting-patches.rst b/Documentation/translations/ja_JP/process/submitting-patches.rst index b89e63a1f65c0..3bb2383871e1c 100644 --- a/Documentation/translations/ja_JP/process/submitting-patches.rst +++ b/Documentation/translations/ja_JP/process/submitting-patches.rst @@ -96,3 +96,87 @@ Linux の多くの環境は、上流から特定のパッチだけを取り込 .. TODO: Convert to file-local cross-reference when the destination is translated. + +パッチまたはパッチシリーズを投稿／再投稿する際は、その完全な +説明と、それを正当化する理由を含めてください。単に、これが +パッチ（シリーズ）のバージョン N であるとだけ書かないでください。 +サブシステムメンテナが以前のパッチ版や参照先 URL をさかのぼって +パッチ説明を探し、それをパッチに補うことを期待してはいけません。 +つまり、パッチ（シリーズ）とその説明は、それだけで完結しているべき +です。これはメンテナとレビューアの双方に有益です。レビューアの +中には、以前のパッチ版を受け取っていない人もいるでしょう。 + +変更内容は命令形で記述してください。たとえば、 +「make xyzzy do frotz」とし、 +「[This patch] makes xyzzy do frotz」や +「[I] changed xyzzy to do frotz」 +のようには書かないでください。あたかもコードベースに対して、 +その振る舞いを変えるよう命令しているかのように書いてください。 + +特定のコミットに言及したい場合は、コミットの SHA-1 ID だけを +書かないでください。レビューアがそれが何についてのものかを +把握しやすくなるよう、コミットの 1 行要約も含めてください。例:: + + Commit e21d2170f36602ae2708 ("video: remove unnecessary + platform_set_drvdata()") removed the unnecessary + platform_set_drvdata(), but left the variable "dev" unused, + delete it. + +また、SHA-1 ID は少なくとも先頭 12 文字を使うようにしてください。 +カーネルのリポジトリには非常に多くのオブジェクトがあるため、 +それより短い ID では衝突が現実に起こり得ます。いま 6 文字の ID に +衝突がなくても、5 年後もそうだとは限らないことに注意してください。 + +変更に関連する議論や、その背景情報が Web 上で参照できる場合は、 +それを指す ``Link:`` タグを追加してください。パッチが過去の +メーリングリストでの議論や、Web に記録された何かの結果であるなら、 +それを示してください。 + +メーリングリストのアーカイブへリンクする場合は、できれば +lore.kernel.org のメッセージアーカイブサービスを使ってください。 +リンク URL を作るには、そのメッセージの ``Message-ID`` ヘッダの内容 +から、前後の山括弧を取り除いたものを使います。例:: + + Link: https://lore.kernel.org/30th.anniversary.repost@klaava.Helsinki.FI + +実際にリンクが機能し、該当するメッセージを指していることを +確認してください。ただし、外部リソースを見なくても説明が理解できる +ようにするよう努めてください。 + +メーリングリストのアーカイブやバグへの URL を示すだけでなく、 +投稿されたパッチに至った議論の要点も要約してください。 + +パッチがバグを修正するものであれば、メーリングリストのアーカイブや +公開バグトラッカー上の報告を指す URL を付けて、``Closes:`` タグを +使ってください。例:: + + Closes: https://example.com/issues/1234 + +このようなタグ付きのコミットが適用されたとき、自動的に issue を +閉じられるバグトラッカーもあります。メーリングリストを監視している +ボットの中には、そのようなタグを追跡して一定の動作を行うものも +あります。非公開のバグトラッカーや無効な URL は禁止です。 + +パッチが特定のコミットに含まれるバグを修正するものであれば、 +たとえば ``git bisect`` で問題を見つけた場合には、SHA-1 ID の +先頭少なくとも 12 文字と 1 行要約を含めて、``Fixes:`` タグを +使ってください。タグを複数行に分割してはいけません。タグは +解析スクリプトを単純にするため、「75 桁で折り返す」規則の +例外です。 + +例:: + + Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") + +上の形式を ``git log`` や ``git show`` で出力しやすくするために、 +次の ``git config`` 設定を使えます:: + + [core] + abbrev = 12 + [pretty] + fixes = Fixes: %h ("%s") + +呼び出し例:: + + $ git log -1 --pretty=fixes 54a4f0239f2e + Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed")