docs/ja_JP: submitting-patches: Amend "Describe your changes"

To make the translation of "Describe your changes" (into
"変更内容を記述する") easier to follow, do some rewording and
rephrasing, as well as fixing a couple of mistranslations.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260326114637.144601-1-akiyks@gmail.com>

Documentation/translations/ja_JP/process/submitting-patches.rst

@@ -55,67 +55,66 @@ Documentation/process/maintainer-handbooks.rst.
 変更内容を記述する
 ------------------
 
-問題を記述してください。あなたのパッチが 1 行のバグ修正であっても、
+まず問題点を記べてください。あなたのパッチが 1 行のバグ修正であっても、
 5000 行の新機能であっても、それを行う動機となった根本的な問題が
-必ずあるはずです。修正すべき価値のある問題が存在し、レビューアが
+必ずあるはずです。レビューアが、修正すべき問題がたしかに存在し、冒頭の
-最初の段落以降を読む意味があることを納得させてください。
+段落の続きを読むべきだと納得できるように書いてください。
 
-ユーザーから見える影響を記述してください。クラッシュやロックアップは
+次にユーザーから見える影響を記述してください。クラッシュやロックアップは
 分かりやすいですが、すべてのバグがそこまで露骨とは限りません。
 たとえコードレビュー中に見つかった問題であっても、ユーザーに
 どのような影響があり得るかを記述してください。
 Linux の多くの環境は、上流から特定のパッチだけを取り込む二次的な
 安定版ツリーや、ベンダー／製品固有のツリーのカーネルで動いています。
-したがって、変更を下流へ適切に流す助けになる情報（発生条件、dmesg
+したがって、変更を適切に下流へ流す助けになる情報（発生条件、dmesg
 の抜粋、クラッシュ内容、性能劣化、レイテンシのスパイク、
 ロックアップ等）があれば記載してください。
 
-最適化とトレードオフを定量的に示してください。パフォーマンス、
+次に最適化とトレードオフを定量的に示してください。パフォーマンス、
 メモリ消費量、スタックフットプリント、バイナリサイズの改善を主張する
 場合は、それを裏付ける数値を記載してください。
-また、目に見えないコストについても記述してください。最適化は通常
+また、目に見えないコストについても記述してください。多くの場合、
-無料ではなく、CPU・メモリ・可読性の間でのトレードオフになります。
+最適化は CPU・メモリ・可読性の間でのトレードオフとなります。
-ヒューリスティクスの場合は、異なるワークロード間でのトレードオフに
+ヒューリスティクスの場合は、異なるワークロード間でのトレードオフと
 なります。レビューアがコストとメリットを比較検討できるよう、
-最適化によって予想されるデメリットも記述してください。
+最適化に伴って想定されるデメリットも記述してください。
 
-問題を明確にできたら、実際にどのような対策を講じているかを技術的に
+問題点の明確化が済んだら、実際にどのような対策を講じているかを技術的に
-詳しく記述してください。レビューアがコードが意図したとおりに動作して
+詳しく説明してください。コードが意図したとおりに動作していることを
-いるかを確認できるよう、変更内容を平易な言葉で書き下すことが重要です。
+レビューアが確認できるよう、変更内容を平易な言葉で書き下すことが重要です。
 
-パッチ説明を Linux のソースコード管理システム ``git`` の
+パッチの説明が Linux のソースコード管理システム ``git`` の「コミットログ」
-「コミットログ」としてそのまま取り込める形で書けば、メンテナは
+としてそのまま取り込める形で書かれていれば、メンテナは助かります。
-助かります。詳細は原文の該当節を参照してください。
+詳細は原文の該当節 ("The canonical patch format") を参照してください。
 
 .. TODO: Convert to file-local cross-reference when the destination is
    translated.
 
 1 つのパッチでは 1 つの問題だけを解決してください。記述が長くなり
-始めたら、パッチを分割すべきサインです。詳細は原文の該当節を参照
+始めたら、それはパッチを分割すべきサインです。
-してください。
+詳細は原文の該当節 ("Separate your changes") を参照してください。
 
 .. TODO: Convert to file-local cross-reference when the destination is
    translated.
 
 パッチまたはパッチシリーズを投稿／再投稿する際は、その完全な
-説明と、それを正当化する理由を含めてください。単に、これが
+説明と、それを正当化する理由を含めてください。単に「これはパッチ
-パッチ（シリーズ）のバージョン N であるとだけ書かないでください。
+（シリーズ）のバージョン N です」とだけ書くのは避けてください。
-サブシステムメンテナが以前のパッチ版や参照先 URL をさかのぼって
+サブシステムメンテナが以前のパッチバージョンや参照先 URL をさかのぼって
-パッチ説明を探し、それをパッチに補うことを期待してはいけません。
+パッチ記述を探し、それをパッチに補うことを期待してはいけません。
 つまり、パッチ（シリーズ）とその説明は、それだけで完結しているべき
 です。これはメンテナとレビューアの双方に有益です。レビューアの
-中には、以前のパッチ版を受け取っていない人もいるでしょう。
+中には、以前のパッチバージョンを受け取っていない人もいるでしょう。
 
-変更内容は命令形で記述してください。たとえば、
+変更内容は、あたかもコードベースに対してその振る舞いを変えるように
-「make xyzzy do frotz」とし、
+命令するかの如く、（訳補: 英語の）命令形で記述してください。たとえば、
-「[This patch] makes xyzzy do frotz」や
+"[This patch] makes xyzzy do frotz" や
-「[I] changed xyzzy to do frotz」
+"[I] changed xyzzy to do frotz" のような言い回しを避け、
-のようには書かないでください。あたかもコードベースに対して、
+"make xyzzy do frotz" のように書いてください。
-その振る舞いを変えるよう命令しているかのように書いてください。
 
-特定のコミットに言及したい場合は、コミットの SHA-1 ID だけを
+特定のコミットに言及したい場合に、コミットの SHA-1 ID だけを
-書かないでください。レビューアがそれが何についてのものかを
+書くのは避けてください。レビューアがそれが何についてのものかを
-把握しやすくなるよう、コミットの 1 行要約も含めてください。例::
+把握しやすいよう、コミットの 1 行要約も含めてください。例::
 
 	Commit e21d2170f36602ae2708 ("video: remove unnecessary
 	platform_set_drvdata()") removed the unnecessary
@@ -123,28 +122,29 @@ Linux の多くの環境は、上流から特定のパッチだけを取り込
 	delete it.
 
 また、SHA-1 ID は少なくとも先頭 12 文字を使うようにしてください。
-カーネルのリポジトリには非常に多くのオブジェクトがあるため、
+カーネルのリポジトリには\ **非常に多くの**\ オブジェクトがあるため、
-それより短い ID では衝突が現実に起こり得ます。いま 6 文字の ID に
+それより短い ID では衝突が現実問題となります。6 文字の ID が今現在
-衝突がなくても、5 年後もそうだとは限らないことに注意してください。
+衝突しないからといって、5 年後もそうであるとは限らないことを念頭に
+置いてください。
 
 変更に関連する議論や、その背景情報が Web 上で参照できる場合は、
-それを指す ``Link:`` タグを追加してください。パッチが過去の
+それを指す 'Link:' タグを追加してください。過去のメーリングリスト
-メーリングリストでの議論や、Web に記録された何かの結果であるなら、
+での議論や、Web に記録された何かに由来するパッチならば、
 それを示してください。
 
-メーリングリストのアーカイブへリンクする場合は、できれば
+メーリングリストのアーカイブへリンクする場合は、できれば lore.kernel.org
-lore.kernel.org のメッセージアーカイブサービスを使ってください。
+のメッセージアーカイブサービスを使ってください。リンク URL を作るには、
-リンク URL を作るには、そのメッセージの ``Message-ID`` ヘッダの内容
+そのメッセージの ``Message-ID`` ヘッダの内容から、前後の山括弧を取り除いた
-から、前後の山括弧を取り除いたものを使います。例::
+ものを使います。例::
 
     Link: https://lore.kernel.org/30th.anniversary.repost@klaava.Helsinki.FI
 
 実際にリンクが機能し、該当するメッセージを指していることを
-確認してください。ただし、外部リソースを見なくても説明が理解できる
+確認してください。
-ようにするよう努めてください。
 
+ただし、外部リソースを見なくても説明が理解できるようにするよう努めてください。
 メーリングリストのアーカイブやバグへの URL を示すだけでなく、
-投稿されたパッチに至った議論の要点も要約してください。
+投稿されたパッチに至った議論のポイントも要約してください。
 
 パッチがバグを修正するものであれば、メーリングリストのアーカイブや
 公開バグトラッカー上の報告を指す URL を付けて、``Closes:`` タグを
@@ -153,23 +153,22 @@ lore.kernel.org のメッセージアーカイブサービスを使ってくだ
     Closes: https://example.com/issues/1234
 
 このようなタグ付きのコミットが適用されたとき、自動的に issue を
-閉じられるバグトラッカーもあります。メーリングリストを監視している
+閉じるバグトラッカーもあります。メーリングリストを監視している
 ボットの中には、そのようなタグを追跡して一定の動作を行うものも
-あります。非公開のバグトラッカーや無効な URL は禁止です。
+あります。ただし、非公開バグトラッカーの（訳補: 部外者が）閲覧できない
+URL は禁止です。
 
-パッチが特定のコミットに含まれるバグを修正するものであれば、
+パッチが特定のコミットに含まれるバグを修正するもの、たとえば
-たとえば ``git bisect`` で問題を見つけた場合には、SHA-1 ID の
+``git bisect`` で問題を見つけたものの場合には、SHA-1 ID の
-先頭少なくとも 12 文字と 1 行要約を含めて、``Fixes:`` タグを
+先頭少なくとも 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 log`` や ``git show`` の出力を上の形式で整形させるには、
-次の ``git config`` 設定を使えます::
+次の ``git config`` 設定が使えます::
 
     [core]
         abbrev = 12