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

[Akira Yokosawa <akiyks@gmail.com>]

Hi,

A couple of comments.  Please see below.

On Sat,  7 Nov 2026 07:56:19 +0900, Akiyoshi Kurita wrote:
> 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`` の出力）。
> +
> +件名行をこの形式にすると、メールを件名のアルファベット順に
> +並べ替えることが非常に簡単になります。ほぼすべてのメールソフトが

My interpretation of original sentence is closer to the following:

  件名行をこの形式にすると、メールの並び替えを件名のアルファベット順で
  容易にできます。というのも、ほぼすべてのメールソフトが

> +この並べ替えに対応しており、連番がゼロ埋めされているため、
> +数値順とアルファベット順の並びが一致します。
> +
> +件名の ``subsystem`` には、パッチの対象となるカーネル内の領域や
> +サブシステムを指定してください。
> +
> +件名の ``summary phrase`` には、メールに含まれるパッチの内容を
> +簡潔に記述してください。ファイル名を使ってはいけません。また、
> +一連のパッチシリーズ（関連する複数のパッチを順序付けたもの）の
> +すべてに同じ ``summary phrase`` を使わないでください。
> +
> +メールの ``summary phrase`` は、そのパッチを識別するための
> +世界的に一意な識別子になることに注意してください。これは ``git`` の

I'd say "大域的" for "global".

> +変更履歴にも記録され、その後の開発者間の議論でパッチを参照する際に
> +使われることがあります。パッチについての議論を調べるために、
> +``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

Thanks, Akira