[PATCH v1] docs/ja_JP: translate submitting-patches.rst (patch format)

[PATCH v1] docs/ja_JP: translate submitting-patches.rst (patch format)

[Akiyoshi Kurita]

Translate the sections describing permission requirements for
adding tags, the canonical patch format, and subject line
conventions into Japanese.

Update existing cross-references to point to the newly
translated section.

Signed-off-by: Akiyoshi Kurita <weibu@redadmin.org>
---
 .../ja_JP/process/submitting-patches.rst      | 108 ++++++++++++++++--
 1 file changed, 100 insertions(+), 8 deletions(-)

diff --git a/Documentation/translations/ja_JP/process/submitting-patches.rst b/Documentation/translations/ja_JP/process/submitting-patches.rst
index cc0b348086da..bcc0ffd74b17 100644
--- a/Documentation/translations/ja_JP/process/submitting-patches.rst
+++ b/Documentation/translations/ja_JP/process/submitting-patches.rst
@@ -85,11 +85,8 @@ Linux の多くの環境は、上流から特定のパッチだけを取り込
 
 パッチ説明を Linux のソースコード管理システム ``git`` の
 「コミットログ」としてそのまま取り込める形で書けば、メンテナは
-助かります。詳細は原文の該当節 ("The canonical patch format") を
-参照してください。
+助かります。詳細は :ref:`jp_the_canonical_patch_format` を参照してください。
 
-.. TODO: Convert to file-local cross-reference when the destination is
-   translated.
 
 1 つのパッチでは 1 つの問題だけを解決してください。記述が長くなり
 始めたら、パッチを分割すべきサインです。詳細は `変更を分割する`_ を
@@ -343,11 +340,8 @@ Documentation/process/email-clients.rst を参照してください。
 ときにはレビューアが機嫌を損ねることもあります。そのような場合でも、
 丁寧に応答し、指摘された問題に対応してください。次の版を送る際には、
 カバーレターまたは個々のパッチに ``patch changelog`` を追加し、前回の
-投稿との差分を説明してください。詳細は原文の該当節
-("The canonical patch format") を参照してください。
+投稿との差分を説明してください。詳細は :ref:`jp_the_canonical_patch_format` を参照してください。
 
-.. TODO: Convert to file-local cross-reference when the destination is
-   translated.
 
 あなたのパッチにコメントしてくれた人たちは、パッチの Cc リストに追加して
 新しい版について知らせてください。
@@ -688,3 +682,101 @@ Documentation/process/stable-kernel-rules.rst を参照してください。
 最後に、タグを付けることは歓迎され、通常は非常にありがたいものですが、
 署名者（すなわち、提出者およびメンテナー）は、提示されたタグを
 適用するかどうかを自身の判断で決めることができます。
+
+.. _jp_tagging_people:
+
+人をタグ付けするには許可が必要
+--------------------------------
+
+前述のタグをパッチに追加する際は注意してください。``Cc:``、
+``Reported-by:``、``Suggested-by:`` を除くすべてのタグには、
+名前を記載される本人の明示的な許可が必要です。これら三つのタグについては、
+lore のアーカイブやコミット履歴から、その人が同じ名前とメールアドレスで
+Linux カーネルに貢献していることを確認できれば、黙示的な許可で十分です。
+ただし、``Reported-by:`` と ``Suggested-by:`` については、
+その人が報告や提案を公開の場で行っている必要もあります。
+
+なお、bugzilla.kernel.org は、この意味では公開の場とみなされますが、
+そこで使用されるメールアドレスは非公開情報です。その人が過去の貢献で
+同じメールアドレスを使用していない限り、タグに記載して公開してはいけません。
+
+.. _jp_the_canonical_patch_format:
+
+標準的なパッチ形式
+------------------
+
+この節では、パッチ自体の形式を説明します。パッチを ``git`` リポジトリで
+管理している場合は、``git format-patch`` で適切な形式のパッチを
+生成できます。ただし、必要な説明文までツールで作成できるわけでは
+ありません。そのため、以下の説明にも目を通してください。
+
+件名行
+^^^^^^
+
+標準的なパッチの件名行は次の形式です::
+
+    Subject: [PATCH 001/123] subsystem: summary phrase
+
+標準的なパッチメールの本文には、次の要素が含まれます。
+
+  - パッチの作者を示す ``from`` 行と、その後の空行
+    （パッチの送信者と作者が異なる場合にのみ必要です）。
+
+  - このパッチの説明として恒久的な変更履歴に記録される本文。
+    1 行を 75 桁以内で折り返します。
+
+  - 空行。
+
+  - 前述の ``Signed-off-by:`` 行。これも変更履歴に記録されます。
+
+  - ``---`` だけを記載した区切り行。
+
+  - 変更履歴に含めるのが適切でない追加のコメント。
+
+  - 実際のパッチ（``diff`` の出力）。
+
+件名行をこの形式にすると、メールを件名のアルファベット順に
+並べ替えることが非常に簡単になります。ほぼすべてのメールソフトが
+この並べ替えに対応しており、連番がゼロ埋めされているため、
+数値順とアルファベット順の並びが一致します。
+
+件名の ``subsystem`` には、パッチの対象となるカーネル内の領域や
+サブシステムを指定してください。
+
+件名の ``summary phrase`` には、メールに含まれるパッチの内容を
+簡潔に記述してください。ファイル名を使ってはいけません。また、
+一連のパッチシリーズ（関連する複数のパッチを順序付けたもの）の
+すべてに同じ ``summary phrase`` を使わないでください。
+
+メールの ``summary phrase`` は、そのパッチを識別するための
+世界的に一意な識別子になることに注意してください。これは ``git`` の
+変更履歴にも記録され、その後の開発者間の議論でパッチを参照する際に
+使われることがあります。パッチについての議論を調べるために、
+``summary phrase`` で Web 検索する人もいるでしょう。また、
+2 ～ 3 か月後に ``gitk`` や ``git log --oneline`` などで
+数千件ものパッチを確認するとき、すぐに目に入る情報が
+``summary phrase`` だけという場合もあります。
+
+このため、``summary`` は 70 ～ 75 文字以内とし、パッチが
+**何を変更するのか** と **なぜその変更が必要なのか** の両方を
+説明する必要があります。簡潔さと説明の十分さを両立させるのは
+簡単ではありませんが、適切な要約にはその両方が求められます。
+
+``summary phrase`` の前には、角括弧で囲んだタグを付けることができます。
+たとえば ``Subject: [PATCH <tag>...] <summary phrase>`` の形式です。
+これらのタグは要約の一部とはみなされず、パッチをどのように
+扱うべきかを示します。一般的なタグには、コメントを受けて
+複数の版を送信した場合のバージョン番号（``v1``、``v2``、``v3`` など）や、
+意見を求めることを示す ``RFC`` などがあります。
+
+パッチシリーズが四つのパッチで構成される場合は、各パッチに
+``1/4``、``2/4``、``3/4``、``4/4`` のように番号を付けられます。
+これにより、開発者はパッチを適用する順序を把握でき、
+シリーズ内のすべてのパッチをレビューまたは適用したか確認できます。
+
+適切な件名の例を以下に示します::
+
+    Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching
+    Subject: [PATCH v2 01/27] x86: fix eflags tracking
+    Subject: [PATCH v2] sub/sys: Condensed patch summary
+    Subject: [PATCH v2 M/N] sub/sys: Condensed patch summary
-- 
2.52.0