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

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

[Akiyoshi Kurita]

Translate the first half of the "Describe your changes" section in
Documentation/translations/ja_JP/process/submitting-patches.rst.

Wrap lines at around 74 columns, and avoid cross-references for now by
adding TODO notes to convert them to file-local references when the
destinations are translated.

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

diff --git a/Documentation/translations/ja_JP/process/submitting-patches.rst b/Documentation/translations/ja_JP/process/submitting-patches.rst
index d61583399ef4..48188c772d47 100644
--- a/Documentation/translations/ja_JP/process/submitting-patches.rst
+++ b/Documentation/translations/ja_JP/process/submitting-patches.rst
@@ -54,3 +54,44 @@ Documentation/devicetree/bindings/submitting-patches.rst を読んでくださ
 
 変更内容を説明する
 ------------------
+
+問題を説明してください。あなたのパッチが 1 行のバグ修正であっても、
+5000 行の新機能であっても、それを行う動機となった根本的な問題が
+必ずあるはずです。修正すべき価値のある問題が存在し、レビューアが
+最初の段落以降を読む意味があることを納得させてください。
+
+ユーザーから見える影響を説明してください。クラッシュやハング
+（ロックアップ）は分かりやすいですが、すべてのバグがそこまで露骨
+とは限りません。たとえコードレビュー中に見つかった問題であっても、
+ユーザーにどのような影響があり得るかを説明してください。
+Linux の多くの環境は、上流から特定のパッチだけを取り込む二次的な
+安定版ツリーや、ベンダー／製品固有のツリーのカーネルで動いています。
+したがって、変更を下流へ適切に流す助けになる情報（発生条件、dmesg
+の抜粋、クラッシュ内容、性能劣化、レイテンシのスパイク、
+ハング／ロックアップ等）があれば記載してください。
+
+最適化とトレードオフを定量的に示してください。パフォーマンス、
+メモリ消費量、スタックフットプリント、バイナリサイズの改善を主張
+する場合は、それを裏付ける数値を記載してください。また、目に見えない
+コストについても説明してください。最適化は通常、CPU、メモリ、
+可読性などのコストを伴います。ヒューリスティクスの場合は、異なる
+ワークロード間のトレードオフも発生します。レビューアがコストと
+メリットを比較検討できるよう、最適化によって予想されるデメリットに
+ついても説明してください。
+
+問題が特定できたら、実際にどのような対策を講じているかを技術的に
+詳しく説明してください。レビューアがコードが意図したとおりに動作
+しているかを確認できるよう、変更内容を平易な言葉で説明することが
+重要です。
+
+パッチ説明を Linux のソースコード管理システム ``git`` の
+「コミットログ」としてそのまま取り込める形で書けば、メンテナは
+助かります。詳細は原文の該当節を参照してください。
+
+.. TODO: Convert to file-local cross-reference when the destination is translated.
+
+1 つのパッチでは 1 つの問題だけを解決してください。説明が長くなり
+始めたら、パッチを分割すべきサインです。詳細は原文の該当節を参照
+してください。
+
+.. TODO: Convert to file-local cross-reference when the destination is translated.
-- 
2.47.3

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

[Akira Yokosawa]

Hi,

On Sat, 21 Feb 2026 23:47:15 +0900, Akiyoshi Kurita wrote:
> Translate the first half of the "Describe your changes" section in
> Documentation/translations/ja_JP/process/submitting-patches.rst.
> 
> Wrap lines at around 74 columns, and avoid cross-references for now by
> adding TODO notes to convert them to file-local references when the
> destinations are translated.
> 
> Signed-off-by: Akiyoshi Kurita <weibu@redadmin.org>
> ---
>  .../ja_JP/process/submitting-patches.rst      | 41 +++++++++++++++++++
>  1 file changed, 41 insertions(+)
> 
> diff --git a/Documentation/translations/ja_JP/process/submitting-patches.rst b/Documentation/translations/ja_JP/process/submitting-patches.rst
> index d61583399ef4..48188c772d47 100644
> --- a/Documentation/translations/ja_JP/process/submitting-patches.rst
> +++ b/Documentation/translations/ja_JP/process/submitting-patches.rst
> @@ -54,3 +54,44 @@ Documentation/devicetree/bindings/submitting-patches.rst を読んでくださ
>  
>  変更内容を説明する

So, you are using "説明する" for "describe" throughout this patch.

I have trouble with the choice, because I tend to reverse translate
it into "explain" in my mind.  "To explain" is usually more involved than
"to describe".

You might have been affected by the outdated ja_JP/SubmittingPatches, but
please have a look at ja_JP/process/howto.rst and see how many "説明" are
there.

There, Japanese terms for "describe" include: "書き下す", "書かれている",
"記述する/される", "述べる", "言う", and few instances of "説明する".

"説明する" is used when what is described is "detailed" or for English word
of "explain".

I'd like you to follow the distinction in howto.rst.

>
> +
> +問題を説明してください。あなたのパッチが 1 行のバグ修正であっても、
> +5000 行の新機能であっても、それを行う動機となった根本的な問題が
> +必ずあるはずです。修正すべき価値のある問題が存在し、レビューアが
> +最初の段落以降を読む意味があることを納得させてください。

It looks like you are wrapping at 30 wide-chars, rather than 37 or so. 
Again, you might have been affected by SubmittingPatches ...

> +
> +ユーザーから見える影響を説明してください。クラッシュやハング
> +（ロックアップ）は分かりやすいですが、すべてのバグがそこまで露骨
> +とは限りません。たとえコードレビュー中に見つかった問題であっても、
> +ユーザーにどのような影響があり得るかを説明してください。
> +Linux の多くの環境は、上流から特定のパッチだけを取り込む二次的な
> +安定版ツリーや、ベンダー／製品固有のツリーのカーネルで動いています。
> +したがって、変更を下流へ適切に流す助けになる情報（発生条件、dmesg
> +の抜粋、クラッシュ内容、性能劣化、レイテンシのスパイク、
> +ハング／ロックアップ等）があれば記載してください。
> +
> +最適化とトレードオフを定量的に示してください。パフォーマンス、
> +メモリ消費量、スタックフットプリント、バイナリサイズの改善を主張
> +する場合は、それを裏付ける数値を記載してください。また、目に見えない
> +コストについても説明してください。

>                                 最適化は通常、CPU、メモリ、
> +可読性などのコストを伴います。ヒューリスティクスの場合は、異なる
> +ワークロード間のトレードオフも発生します。

These two sentences correspond to:

|      Optimizations usually aren't free but trade-offs between CPU,
| memory, and readability; or, when it comes to heuristics, between
| different workloads.

Your translation sounds to me slightly different from the original.
Could you rework?  Hint: "trade-offs" are in both sides of ";".

I think this is close to be merged.  Looking forward to seeing a v3.

Thanks, Akira

>                                        レビューアがコストと
> +メリットを比較検討できるよう、最適化によって予想されるデメリットに
> +ついても説明してください。
> +
> +問題が特定できたら、実際にどのような対策を講じているかを技術的に
> +詳しく説明してください。レビューアがコードが意図したとおりに動作
> +しているかを確認できるよう、変更内容を平易な言葉で説明することが
> +重要です。
> +
> +パッチ説明を Linux のソースコード管理システム ``git`` の
> +「コミットログ」としてそのまま取り込める形で書けば、メンテナは
> +助かります。詳細は原文の該当節を参照してください。
> +
> +.. TODO: Convert to file-local cross-reference when the destination is translated.
> +
> +1 つのパッチでは 1 つの問題だけを解決してください。説明が長くなり
> +始めたら、パッチを分割すべきサインです。詳細は原文の該当節を参照
> +してください。
> +
> +.. TODO: Convert to file-local cross-reference when the destination is translated.