.. _jp_process_submitting_patches:

パッチの投稿: カーネルにコードを入れるための必須ガイド
======================================================

.. note::

   このドキュメントは :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` の日本語訳です。

   免責事項: :ref:`translations_ja_JP_disclaimer`

.. warning::

   **UNDER CONSTRUCTION!!**

   この文書は翻訳更新の作業中です。最新の内容は原文を参照してください。

Linux カーネルへ変更を投稿したい個人や企業にとって、もし「仕組み」に
慣れていなければ、そのプロセスは時に気後れするものでしょう。
このテキストは、あなたの変更が受け入れられる可能性を大きく高めるための
提案を集めたものです。

この文書には、比較的簡潔な形式で多数の提案が含まれています。
カーネル開発プロセスの仕組みに関する詳細は
Documentation/process/development-process.rst を参照してください。
また、コードを投稿する前に確認すべき項目の一覧として
Documentation/process/submit-checklist.rst を読んでください。
デバイスツリーバインディングのパッチについては、
Documentation/devicetree/bindings/submitting-patches.rst を読んでください。

この文書は、パッチ作成に ``git`` を使う前提で書かれています。
もし ``git`` に不慣れであれば、使い方を学ぶことを強く勧めます。
それにより、カーネル開発者として、また一般的にも、あなたの作業は
ずっと楽になるでしょう。

いくつかのサブシステムやメンテナツリーには、各々のワークフローや
期待事項に関する追加情報があります。次を参照してください:
Documentation/process/maintainer-handbooks.rst.

現在のソースツリーを入手する
----------------------------

もし手元に最新のカーネルソースのリポジトリがなければ、``git`` を使って取得して
ください。まずは mainline のリポジトリから始めるのがよいでしょう。これは
次のようにして取得できます::

  git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git

ただし、直接 mainline のツリーを対象に作業すればよいとは限らないことに注意
してください。多くのサブシステムのメンテナはそれぞれ独自のツリーを運用しており、
そのツリーに対して作成されたパッチを見たいと考えています。該当サブシステムの
ツリーは MAINTAINERS ファイル内の **T:** エントリを参照して見つけてください。
そこに掲載されていない場合は、メンテナに問い合わせてください。

変更内容を記述する
------------------

問題を記述してください。あなたのパッチが 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.
