submit-checklist.rst

  1.. SPDX-License-Identifier: GPL-2.0
  2
  3.. Translated by Akira Yokosawa <akiyks@gmail.com>
  4
  5.. An old translation of this document of a different origin was at
  6   Documentation/translations/ja_JP/SubmitChecklist, which can be found
  7   in the pre-v6.14 tree if you are interested.
  8   Please note that this translation is independent of the previous one.
  9
 10======================================
 11Linux カーネルパッチ投稿チェックリスト
 12======================================
 13
 14.. note:: 【訳註】
 15   この文書は、
 16   Documentation/process/submit-checklist.rst
 17   の翻訳です。
 18   免責条項については、
 19   :ref:`免責条項の抄訳 <translations_ja_JP_disclaimer>` および、
 20   :ref:`Disclaimer (英語版) <translations_disclaimer>` を参照してください。
 21
 22以下は、カーネルパッチの投稿時に、そのスムーズな受け入れのために心がける
 23べき基本的な事項です。
 24
 25これは、 Documentation/process/submitting-patches.rst およびその他の
 26Linux カーネルパッチ投稿に関する文書を踏まえ、それを補足するものです。
 27
 28.. note:: 【訳註】
 29   可能な項目については、パッチもしくはパッチ内の更新を暗黙の主語として、
 30   その望ましい状態を表す文体とします。その他、原義を損なわない範囲で
 31   係り結びを調整するなど、簡潔で把握しやすい箇条書きを目指します。
 32
 33
 34コードのレビュー
 35================
 36
 371) 利用する機能について、その機能を定義・宣言しているファイルを
 38   ``#include`` している。
 39   他のヘッダーファイル経由での取り込みに依存しない。
 40
 412) Documentation/process/coding-style.rst に詳述されている一般的なスタイル
 42   についてチェック済み。
 43
 443) メモリバリアー (例, ``barrier()``, ``rmb()``, ``wmb()``) について、
 45   そのすべてに、作用と目的、及び必要理由についての説明がソースコード内の
 46   コメントとして記述されている。
 47
 48
 49Kconfig 変更のレビュー
 50======================
 51
 521) 新規の、もしくは変更された ``CONFIG`` オプションについて、それが関係する
 53   コンフィグメニューへの悪影響がない。また、
 54   Documentation/kbuild/kconfig-language.rst の
 55   "Menu attibutes: default value" に記載の例外条件を満たす場合を除き、
 56   そのデフォルトが無効になっている。
 57
 582) 新規の ``Kconfig`` オプションにヘルプテキストがある。
 59
 603) 妥当な ``Kconfig`` の組み合わせについて注意深くレビューされている。
 61   これをテストでやり切るのは困難で、知力が決め手となる。
 62
 63ドキュメンテーションの作成
 64==========================
 65
 661) グローバルなカーネル API が  :ref:`kernel-doc <kernel_doc>` の形式で
 67   ドキュメント化されている (静的関数には求められないが、付けてもよい)。
 68
 692) 新規 ``/proc`` エントリーが、すべて ``Documentation/`` 以下に記載されて
 70   いる。
 71
 723) 新規カーネル・ブート・パラメータが、すべて
 73   ``Documentation/admin-guide/kernel-parameters.rst`` に記載されている。
 74
 754) 新規モジュール・パラメータが、すべて ``MODULE_PARM_DESC()`` によって記述
 76   されている。
 77
 785) 新規ユーザースペース・インターフェースが、すべて ``Documentaion/ABI/``
 79   以下に記載されている。詳しくは、 Documentation/admin-guide/abi.rst
 80   (もしくは ``Documentation/ABI/README``) を参照。
 81   ユーザースペース・インターフェースを変更するパッチは、
 82   linux-api@vger.kernel.org にも CC すべし。
 83
 846) なんらかの ioctl を追加するパッチは、
 85   ``Documentation/userspace-api/ioctl/ioctl-number.rst``
 86   の更新を伴う。
 87
 88ツールによるコードのチェック
 89============================
 90
 911) スタイル・チェッカー (``scripts/checkpatch.pl``) によって、犯しがちな
 92   パッチ・スタイルの違反がないことを確認済み。
 93   指摘される違反を残す場合は、それを正当化できること。
 94
 952) sparse により入念にチェック済み。
 96
 973) ``make checkstack`` で指摘される問題があれば、それが修正済み。
 98   ``checkstack`` は問題点を明示的には指摘しないが、 スタック消費が
 99   512 バイトを越える関数は見直しの候補。
100
101コードのビルド
102==============
103
1041) 以下の条件でクリーンにビルドできる。
105
106   a) 適用可能な、および ``=y``, ``=m``, ``=n`` を変更した ``CONFIG``
107      オプションでのビルド。
108      ``gcc`` およびリンカーからの警告・エラーがないこと。
109
110   b) ``allnoconfig`` と ``allmodconfig`` がパス
111
112   c) ``O=builddir`` を指定してのビルド
113
114   d) Documentation/ 以下の変更に関して、ドキュメントのビルドで新たな警告や
115      エラーが出ない。
116      ``make htmldocs`` または ``make pdfdocs`` でビルドし、問題があれば修正。
117
1182) ローカルのクロス・コンパイル・ツール、その他のビルド環境 (訳註: build farm)
119   を使って、複数の CPU アーキテクチャ向けにビルドできる。
120   特に、ワードサイズ (32 ビットと 64 ビット) やエンディアン (ビッグとリトル)
121   の異なるアーキテクチャを対象とするテストは、表現可能数値範囲・データ整列・
122   エンディアンなどについての誤った仮定に起因する様々な移植上の問題を捕える
123   のに効果的。
124
1253) 新規に追加されたコードについて (``make KCFLAGS=-W`` を使って)
126   ``gcc -W`` でコンパイル。
127   これは多くのノイズを伴うが、
128   ``warning: comparison between signed and unsigned``
129   の類いのバグをあぶり出すのに効果的。
130
1314) 変更されるソースコードが、下記の ``Kconfig`` シンボルに関連するカーネル
132   API や機能に依存 (もしくは利用) する場合、それらの ``Kconfig`` シンボルが、
133   無効、および (可能なら) ``=m`` の場合を組み合わせた複数のビルドを
134   (全部まとめてではなく、いろいろなランダムの組み合わせで) テスト済み。
135
136   ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``,
137   ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``,
138   ``CONFIG_NET``, ``CONFIG_INET=n`` (ただし、後者は ``CONFIG_NET=y``
139   との組み合わせ)。
140
141コードのテスト
142==============
143
1441) ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``,
145   ``CONFIG_SLUB_DEBUG``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``,
146   ``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``,
147   ``CONFIG_PROVE_RCU`` および ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` をすべて
148   同時に有効にしてのテスト済み。
149
1502) ``CONFIG_SMP`` と ``CONFIG_PREEMPT`` が有効と無効の場合について、ビルドと
151   ランタイムのテスト済み。
152
1533) lockdep の機能をすべて有効にしての実行で、すべてのコード経路が確認済み。
154
1554) 最低限、slab と ページ・アロケーションの失敗に関する誤り注入
156   (訳註: fault injection) によるチェック済み。
157   詳しくは、 Documentation/fault-injection/index.rst を参照。
158   新規のコードが多い場合は、サブシステム対象の誤り注入を追加するのが望ましい
159   可能性あり。
160
1615) linux-next の最新タグに対するテストにより、他でキューイングされている
162   パッチや、VM、VFS、その他のサブシステム内のすべての変更と組み合わせての
163   動作を確認済み。