変更内容を記述する
------------------
-問題を記述してください。あなたのパッチが 1 行のバグ修正であっても、
+まず問題点を記べてください。あなたのパッチが 1 行のバグ修正であっても、
5000 行の新機能であっても、それを行う動機となった根本的な問題が
-必ずあるはずです。修正すべき価値のある問題が存在し、レビューアが
-æ\9c\80å\88\9dã\81®æ®µè\90½ä»¥é\99\8dã\82\92èªã\82\80æ\84\8få\91³ã\81\8cã\81\82ã\82\8bã\81\93ã\81¨ã\82\92ç´\8då¾\97ã\81\95ã\81\9bてください。
+必ずあるはずです。レビューアが、修正すべき問題がたしかに存在し、冒頭の
+段è\90½ã\81®ç¶\9aã\81\8dã\82\92èªã\82\80ã\81¹ã\81\8dã\81 ã\81¨ç´\8då¾\97ã\81§ã\81\8dã\82\8bã\82\88ã\81\86ã\81«æ\9b¸ã\81\84てください。
-ユーザーから見える影響を記述してください。クラッシュやロックアップは
+次にユーザーから見える影響を記述してください。クラッシュやロックアップは
分かりやすいですが、すべてのバグがそこまで露骨とは限りません。
たとえコードレビュー中に見つかった問題であっても、ユーザーに
どのような影響があり得るかを記述してください。
Linux の多くの環境は、上流から特定のパッチだけを取り込む二次的な
安定版ツリーや、ベンダー／製品固有のツリーのカーネルで動いています。
-したがって、変更を下流へ適切に流す助けになる情報（発生条件、dmesg
+したがって、変更を適切に下流へ流す助けになる情報（発生条件、dmesg
の抜粋、クラッシュ内容、性能劣化、レイテンシのスパイク、
ロックアップ等）があれば記載してください。
-最適化とトレードオフを定量的に示してください。パフォーマンス、
+次ã\81«æ\9c\80é\81©å\8c\96ã\81¨ã\83\88ã\83¬ã\83¼ã\83\89ã\82ªã\83\95ã\82\92å®\9aé\87\8fç\9a\84ã\81«ç¤ºã\81\97ã\81¦ã\81\8fã\81 ã\81\95ã\81\84ã\80\82ã\83\91ã\83\95ã\82©ã\83¼ã\83\9eã\83³ã\82¹ã\80\81
メモリ消費量、スタックフットプリント、バイナリサイズの改善を主張する
場合は、それを裏付ける数値を記載してください。
-また、目に見えないコストについても記述してください。最適化は通常
-無料ではなく、CPU・メモリ・可読性の間でのトレードオフになります。
-ã\83\92ã\83¥ã\83¼ã\83ªã\82¹ã\83\86ã\82£ã\82¯ã\82¹ã\81®å ´å\90\88ã\81¯ã\80\81ç\95°ã\81ªã\82\8bã\83¯ã\83¼ã\82¯ã\83ã\83¼ã\83\89é\96\93ã\81§ã\81®ã\83\88ã\83¬ã\83¼ã\83\89ã\82ªã\83\95ã\81«
+また、目に見えないコストについても記述してください。多くの場合、
+最適化は CPU・メモリ・可読性の間でのトレードオフとなります。
+ã\83\92ã\83¥ã\83¼ã\83ªã\82¹ã\83\86ã\82£ã\82¯ã\82¹ã\81®å ´å\90\88ã\81¯ã\80\81ç\95°ã\81ªã\82\8bã\83¯ã\83¼ã\82¯ã\83ã\83¼ã\83\89é\96\93ã\81§ã\81®ã\83\88ã\83¬ã\83¼ã\83\89ã\82ªã\83\95ã\81¨
なります。レビューアがコストとメリットを比較検討できるよう、
-最適化によって予想されるデメリットも記述してください。
+最適化に伴って想定されるデメリットも記述してください。
-問題を明確にできたら、実際にどのような対策を講じているかを技術的に
-詳ã\81\97ã\81\8fè¨\98è¿°ã\81\97ã\81¦ã\81\8fã\81 ã\81\95ã\81\84ã\80\82ã\83¬ã\83\93ã\83¥ã\83¼ã\82¢ã\81\8cã\82³ã\83¼ã\83\89ã\81\8cæ\84\8få\9b³ã\81\97ã\81\9fã\81¨ã\81\8aã\82\8aã\81«å\8b\95ä½\9cã\81\97ã\81¦
-ã\81\84ã\82\8bã\81\8bã\82\92確認できるよう、変更内容を平易な言葉で書き下すことが重要です。
+問題点の明確化が済んだら、実際にどのような対策を講じているかを技術的に
+詳ã\81\97ã\81\8f説æ\98\8eã\81\97ã\81¦ã\81\8fã\81 ã\81\95ã\81\84ã\80\82ã\82³ã\83¼ã\83\89ã\81\8cæ\84\8få\9b³ã\81\97ã\81\9fã\81¨ã\81\8aã\82\8aã\81«å\8b\95ä½\9cã\81\97ã\81¦ã\81\84ã\82\8bã\81\93ã\81¨ã\82\92
+ã\83¬ã\83\93ã\83¥ã\83¼ã\82¢ã\81\8c確認できるよう、変更内容を平易な言葉で書き下すことが重要です。
-パッチ説明を Linux のソースコード管理システム ``git`` の
-ã\80\8cã\82³ã\83\9fã\83\83ã\83\88ã\83ã\82°ã\80\8dã\81¨ã\81\97ã\81¦ã\81\9dã\81®ã\81¾ã\81¾å\8f\96ã\82\8aè¾¼ã\82\81ã\82\8bå½¢ã\81§æ\9b¸ã\81\91ã\81°ã\80\81ã\83¡ã\83³ã\83\86ã\83\8aã\81¯
-助かります。詳細は原文の該当節を参照してください。
+パッチの説明が Linux のソースコード管理システム ``git`` の「コミットログ」
+ã\81¨ã\81\97ã\81¦ã\81\9dã\81®ã\81¾ã\81¾å\8f\96ã\82\8aè¾¼ã\82\81ã\82\8bå½¢ã\81§æ\9b¸ã\81\8bã\82\8cã\81¦ã\81\84ã\82\8cã\81°ã\80\81ã\83¡ã\83³ã\83\86ã\83\8aã\81¯å\8a©ã\81\8bã\82\8aã\81¾ã\81\99ã\80\82
+詳細は原文の該当節 ("The canonical patch format") を参照してください。
.. TODO: Convert to file-local cross-reference when the destination is
translated.
1 つのパッチでは 1 つの問題だけを解決してください。記述が長くなり
-å§\8bã\82\81ã\81\9fã\82\89ã\80\81ã\83\91ã\83\83ã\83\81ã\82\92å\88\86å\89²ã\81\99ã\81¹ã\81\8dã\82µã\82¤ã\83³ã\81§ã\81\99ã\80\82詳細ã\81¯å\8e\9fæ\96\87ã\81®è©²å½\93ç¯\80ã\82\92å\8f\82ç\85§
-してください。
+å§\8bã\82\81ã\81\9fã\82\89ã\80\81ã\81\9dã\82\8cã\81¯ã\83\91ã\83\83ã\83\81ã\82\92å\88\86å\89²ã\81\99ã\81¹ã\81\8dã\82µã\82¤ã\83³ã\81§ã\81\99ã\80\82
+詳細は原文の該当節 ("Separate your changes") を参照してください。
.. TODO: Convert to file-local cross-reference when the destination is
translated.
パッチまたはパッチシリーズを投稿／再投稿する際は、その完全な
-説æ\98\8eã\81¨ã\80\81ã\81\9dã\82\8cã\82\92æ£å½\93å\8c\96ã\81\99ã\82\8bç\90\86ç\94±ã\82\92å\90«ã\82\81ã\81¦ã\81\8fã\81 ã\81\95ã\81\84ã\80\82å\8d\98ã\81«ã\80\81ã\81\93ã\82\8cã\81\8c
-パッチ（シリーズ）のバージョン N であるとだけ書かないでください。
-サブシステムメンテナが以前のパッチ版や参照先 URL をさかのぼって
-ã\83\91ã\83\83ã\83\81説æ\98\8eを探し、それをパッチに補うことを期待してはいけません。
+説æ\98\8eã\81¨ã\80\81ã\81\9dã\82\8cã\82\92æ£å½\93å\8c\96ã\81\99ã\82\8bç\90\86ç\94±ã\82\92å\90«ã\82\81ã\81¦ã\81\8fã\81 ã\81\95ã\81\84ã\80\82å\8d\98ã\81«ã\80\8cã\81\93ã\82\8cã\81¯ã\83\91ã\83\83ã\83\81
+（シリーズ）のバージョン N です」とだけ書くのは避けてください。
+サブシステムメンテナが以前のパッチバージョンや参照先 URL をさかのぼって
+ã\83\91ã\83\83ã\83\81è¨\98è¿°を探し、それをパッチに補うことを期待してはいけません。
つまり、パッチ（シリーズ）とその説明は、それだけで完結しているべき
です。これはメンテナとレビューアの双方に有益です。レビューアの
-中には、以前のパッチ版を受け取っていない人もいるでしょう。
+中には、以前のパッチバージョンを受け取っていない人もいるでしょう。
-変更内容は命令形で記述してください。たとえば、
-「make xyzzy do frotz」とし、
-「[This patch] makes xyzzy do frotz」や
-「[I] changed xyzzy to do frotz」
-のようには書かないでください。あたかもコードベースに対して、
-その振る舞いを変えるよう命令しているかのように書いてください。
+変更内容は、あたかもコードベースに対してその振る舞いを変えるように
+命令するかの如く、（訳補: 英語の）命令形で記述してください。たとえば、
+"[This patch] makes xyzzy do frotz" や
+"[I] changed xyzzy to do frotz" のような言い回しを避け、
+"make xyzzy do frotz" のように書いてください。
-ç\89¹å®\9aã\81®ã\82³ã\83\9fã\83\83ã\83\88ã\81«è¨\80å\8f\8aã\81\97ã\81\9fã\81\84å ´å\90\88ã\81¯、コミットの SHA-1 ID だけを
-æ\9b¸ã\81\8bã\81ªã\81\84ã\81§ください。レビューアがそれが何についてのものかを
-æ\8a\8aæ\8f¡ã\81\97ã\82\84ã\81\99ã\81\8fã\81ªã\82\8bよう、コミットの 1 行要約も含めてください。例::
+ç\89¹å®\9aã\81®ã\82³ã\83\9fã\83\83ã\83\88ã\81«è¨\80å\8f\8aã\81\97ã\81\9fã\81\84å ´å\90\88ã\81«、コミットの SHA-1 ID だけを
+æ\9b¸ã\81\8fã\81®ã\81¯é\81¿ã\81\91ã\81¦ください。レビューアがそれが何についてのものかを
+æ\8a\8aæ\8f¡ã\81\97ã\82\84ã\81\99ã\81\84よう、コミットの 1 行要約も含めてください。例::
Commit e21d2170f36602ae2708 ("video: remove unnecessary
platform_set_drvdata()") removed the unnecessary
delete it.
また、SHA-1 ID は少なくとも先頭 12 文字を使うようにしてください。
-カーネルのリポジトリには非常に多くのオブジェクトがあるため、
-それより短い ID では衝突が現実に起こり得ます。いま 6 文字の ID に
-衝突がなくても、5 年後もそうだとは限らないことに注意してください。
+カーネルのリポジトリには\ **非常に多くの**\ オブジェクトがあるため、
+それより短い ID では衝突が現実問題となります。6 文字の ID が今現在
+衝突しないからといって、5 年後もそうであるとは限らないことを念頭に
+置いてください。
変更に関連する議論や、その背景情報が Web 上で参照できる場合は、
-それを指す ``Link:`` タグを追加してください。パッチが過去の
-ã\83¡ã\83¼ã\83ªã\83³ã\82°ã\83ªã\82¹ã\83\88ã\81§ã\81®è°è«\96ã\82\84ã\80\81Web ã\81«è¨\98é\8c²ã\81\95ã\82\8cã\81\9fä½\95ã\81\8bã\81®çµ\90æ\9e\9cã\81§ã\81\82ã\82\8bã\81ªã\82\89、
+それを指す 'Link:' タグを追加してください。過去のメーリングリスト
+ã\81§ã\81®è°è«\96ã\82\84ã\80\81Web ã\81«è¨\98é\8c²ã\81\95ã\82\8cã\81\9fä½\95ã\81\8bã\81«ç\94±æ\9d¥ã\81\99ã\82\8bã\83\91ã\83\83ã\83\81ã\81ªã\82\89ã\81°、
それを示してください。
-メーリングリストのアーカイブへリンクする場合は、できれば
-lore.kernel.org のメッセージアーカイブサービスを使ってください。
-ã\83ªã\83³ã\82¯ URL ã\82\92ä½\9cã\82\8bã\81«ã\81¯ã\80\81ã\81\9dã\81®ã\83¡ã\83\83ã\82»ã\83¼ã\82¸ã\81® ``Message-ID`` ã\83\98ã\83\83ã\83\80ã\81®å\86\85容
-ã\81\8bã\82\89ã\80\81å\89\8då¾\8cã\81®å±±æ\8b¬å¼§ã\82\92å\8f\96ã\82\8aé\99¤ã\81\84ã\81\9fã\82\82ã\81®ã\82\92使ã\81\84ã\81¾ã\81\99ã\80\82ä¾\8b::
+メーリングリストのアーカイブへリンクする場合は、できれば lore.kernel.org
+のメッセージアーカイブサービスを使ってください。リンク URL を作るには、
+ã\81\9dã\81®ã\83¡ã\83\83ã\82»ã\83¼ã\82¸ã\81® ``Message-ID`` ã\83\98ã\83\83ã\83\80ã\81®å\86\85容ã\81\8bã\82\89ã\80\81å\89\8då¾\8cã\81®å±±æ\8b¬å¼§ã\82\92å\8f\96ã\82\8aé\99¤ã\81\84ã\81\9f
+ものを使います。例::
Link: https://lore.kernel.org/30th.anniversary.repost@klaava.Helsinki.FI
実際にリンクが機能し、該当するメッセージを指していることを
-確認してください。ただし、外部リソースを見なくても説明が理解できる
-ようにするよう努めてください。
+確認してください。
+ただし、外部リソースを見なくても説明が理解できるようにするよう努めてください。
メーリングリストのアーカイブやバグへの URL を示すだけでなく、
-投稿されたパッチに至った議論の要点も要約してください。
+投稿されたパッチに至った議論のポイントも要約してください。
パッチがバグを修正するものであれば、メーリングリストのアーカイブや
公開バグトラッカー上の報告を指す URL を付けて、``Closes:`` タグを
Closes: https://example.com/issues/1234
このようなタグ付きのコミットが適用されたとき、自動的に issue を
-é\96\89ã\81\98ã\82\89ã\82\8cã\82\8bã\83\90ã\82°ã\83\88ã\83©ã\83\83ã\82«ã\83¼ã\82\82ã\81\82ã\82\8aã\81¾ã\81\99ã\80\82ã\83¡ã\83¼ã\83ªã\83³ã\82°ã\83ªã\82¹ã\83\88ã\82\92ç\9b£è¦\96ã\81\97ã\81¦ã\81\84ã\82\8b
+閉じるバグトラッカーもあります。メーリングリストを監視している
ボットの中には、そのようなタグを追跡して一定の動作を行うものも
-あります。非公開のバグトラッカーや無効な URL は禁止です。
+あります。ただし、非公開バグトラッカーの（訳補: 部外者が）閲覧できない
+URL は禁止です。
-ã\83\91ã\83\83ã\83\81ã\81\8cç\89¹å®\9aã\81®ã\82³ã\83\9fã\83\83ã\83\88ã\81«å\90«ã\81¾ã\82\8cã\82\8bã\83\90ã\82°ã\82\92ä¿®æ£ã\81\99ã\82\8bã\82\82ã\81®ã\81§ã\81\82ã\82\8cã\81°ã\80\81
-たとえば ``git bisect`` で問題を見つけた場合には、SHA-1 ID の
-先頭少なくとも 12 文字と 1 行要約を含めて、``Fixes:`` タグを
+ã\83\91ã\83\83ã\83\81ã\81\8cç\89¹å®\9aã\81®ã\82³ã\83\9fã\83\83ã\83\88ã\81«å\90«ã\81¾ã\82\8cã\82\8bã\83\90ã\82°ã\82\92ä¿®æ£ã\81\99ã\82\8bã\82\82ã\81®ã\80\81ã\81\9fã\81¨ã\81\88ã\81°
+``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`` で出力しやすくするために、
-次ã\81® ``git config`` è¨å®\9aã\82\92使えます::
+``git log`` や ``git show`` の出力を上の形式で整形させるには、
+次ã\81® ``git config`` è¨å®\9aã\81\8c使えます::
[core]
abbrev = 12
projects / thirdparty / linux.git / commitdiff
