[PATCH] docs: ja_JP: process: translate second half of 'Describe your changes'

[PATCH] docs: ja_JP: process: translate second half of 'Describe your changes'

[Akiyoshi Kurita]

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 <weibu@redadmin.org>
---
 .../ja_JP/process/submitting-patches.rst      | 84 +++++++++++++++++++
 1 file changed, 84 insertions(+)

diff --git a/Documentation/translations/ja_JP/process/submitting-patches.rst b/Documentation/translations/ja_JP/process/submitting-patches.rst
index 1c0f694fd2a0..91bd79a0e9dc 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")
-- 
2.47.3

Re: [PATCH] docs: ja_JP: process: translate second half of 'Describe your changes'

[Akira Yokosawa]

Hi,

Sorry for the late response.

On Mon,  9 Mar 2026 19:50:15 +0900, Akiyoshi Kurita wrote:
> 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 <weibu@redadmin.org>

Acked-by: Akira Yokosawa <akiyks@gmail.com>

I have noticed a couple of minor translation issues in this patch,
but I'd rather submit a patch on top of this, rather than comment on
those issues in English.

I guess I can prepare a follow-up patch within a week.

By the way, now I see why Kurita-san is wrapping lines at 30 wide-chars
or so.  I guess they are broken that way so that each line corresponds
to that in the English text.  That makes sense.

Thanks, Akira

> ---
>  .../ja_JP/process/submitting-patches.rst      | 84 +++++++++++++++++++
>  1 file changed, 84 insertions(+)
> 
[...]

Re: [PATCH] docs: ja_JP: process: translate second half of 'Describe your changes'

[weibu]

Hi Akira-san,

Thank you very much for your review and for your kind message.

I appreciate your taking the time to look at the patch.
Thank you also for letting me know about the minor translation issues.

If you are willing to prepare a follow-up patch, I would greatly 
appreciate it.
I am also glad that the reason for the line wrapping makes sense.

Thank you again for your help and support.

Best regards,
Akiyoshi Kurita

2026-03-23 17:11 に Akira Yokosawa さんは書きました:
> Hi,
> 
> Sorry for the late response.
> 
> On Mon,  9 Mar 2026 19:50:15 +0900, Akiyoshi Kurita wrote:
>> 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 <weibu@redadmin.org>
> 
> Acked-by: Akira Yokosawa <akiyks@gmail.com>
> 
> I have noticed a couple of minor translation issues in this patch,
> but I'd rather submit a patch on top of this, rather than comment on
> those issues in English.
> 
> I guess I can prepare a follow-up patch within a week.
> 
> By the way, now I see why Kurita-san is wrapping lines at 30 wide-chars
> or so.  I guess they are broken that way so that each line corresponds
> to that in the English text.  That makes sense.
> 
> Thanks, Akira
> 
>> ---
>>  .../ja_JP/process/submitting-patches.rst      | 84 
>> +++++++++++++++++++
>>  1 file changed, 84 insertions(+)
>> 
> [...]

Re: [PATCH] docs: ja_JP: process: translate second half of 'Describe your changes'

[Jonathan Corbet]

Akiyoshi Kurita <weibu@redadmin.org> writes:

> 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 <weibu@redadmin.org>
> ---
>  .../ja_JP/process/submitting-patches.rst      | 84 +++++++++++++++++++
>  1 file changed, 84 insertions(+)

Applied, thanks.

jon