Resguardo inicial

linux-7.2.3/Documentation/translations/ja_JP/SubmittingPatches

@@ -0,0 +1,747 @@
+NOTE:
+This is a version of Documentation/process/submitting-patches.rst into Japanese.
+This document is maintained by Keiichi KII <k-keiichi@bx.jp.nec.com>
+and the JF Project team <http://www.linux.or.jp/JF/>.
+If you find any difference between this document and the original file
+or a problem with the translation,
+please contact the maintainer of this file or JF project.
+
+Please also note that the purpose of this file is to be easier to read
+for non English (read: Japanese) speakers and is not intended as a
+fork. So if you have any comments or updates of this file, please try
+to update the original English file first.
+
+Last Updated: 2011/06/09
+
+==================================
+これは、
+linux-2.6.39/Documentation/process/submitting-patches.rst の和訳
+です。
+翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ >
+翻訳日： 2011/06/09
+翻訳者： Keiichi Kii <k-keiichi at bx dot jp dot nec dot com>
+校正者： Masanari Kobayashi さん <zap03216 at nifty dot ne dot jp>
+         Matsukura さん <nbh--mats at nifty dot com>
+         Takeshi Hamasaki さん <hmatrjp at users dot sourceforge dot jp>
+==================================
+
+        Linux カーネルに変更を加えるための Howto
+        又は
+        かの Linus Torvalds の取り扱い説明書
+
+Linux カーネルに変更を加えたいと思っている個人又は会社にとって、パッ
+チの投稿に関連した仕組みに慣れていなければ、その過程は時々みなさんを
+おじけづかせることもあります。この文章はあなたの変更を大いに受け入れ
+てもらえやすくする提案を集めたものです。
+
+コードを投稿する前に、Documentation/process/submit-checklist.rst の項目リストに目
+を通してチェックしてください。
+
+--------------------------------------------
+セクション1 パッチの作り方と送り方
+--------------------------------------------
+
+1) 「 diff -up 」
+------------
+
+パッチの作成には「 diff -up 」又は「 diff -uprN 」を使ってください。
+
+Linux カーネルに対する全ての変更は diff(1) コマンドによるパッチの形式で
+生成してください。パッチを作成するときには、diff(1) コマンドに「 -u 」引
+数を指定して、unified 形式のパッチを作成することを確認してください。また、
+変更がどの C 関数で行われたのかを表示する「 -p 」引数を使ってください。
+この引数は生成した差分をずっと読みやすくしてくれます。パッチは Linux
+カーネルソースの中のサブディレクトリではなく Linux カーネルソースのルート
+ディレクトリを基準にしないといけません。
+
+1個のファイルについてのパッチを作成するためには、ほとんどの場合、
+以下の作業を行えば十分です。
+
+	SRCTREE=linux-2.6
+	MYFILE=drivers/net/mydriver.c
+
+	cd $SRCTREE
+	cp $MYFILE $MYFILE.orig
+	vi $MYFILE	# make your change
+	cd ..
+	diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch
+
+複数のファイルについてのパッチを作成するためには、素の( vanilla )、す
+なわち変更を加えてない Linux カーネルを展開し、自分の Linux カーネル
+ソースとの差分を生成しないといけません。例えば、
+
+	MYSRC=/devel/linux-2.6
+
+	tar xvfz linux-2.6.12.tar.gz
+	mv linux-2.6.12 linux-2.6.12-vanilla
+	diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \
+		linux-2.6.12-vanilla $MYSRC > /tmp/patch
+
+dontdiff ファイルには Linux カーネルのビルドプロセスの過程で生成された
+ファイルの一覧がのっています。そして、それらはパッチを生成する diff(1)
+コマンドで無視されるべきです。dontdiff ファイルは 2.6.12 以後のバージョ
+ンの Linux カーネルソースツリーに含まれています。
+
+投稿するパッチの中に関係のない余分なファイルが含まれていないことを確
+認してください。diff(1) コマンドで生成したパッチがあなたの意図したとお
+りのものであることを確認してください。
+
+もしあなたのパッチが多くの差分を生み出すのであれば、あなたはパッチ
+を意味のあるひとまとまりごとに分けたいと思うかもしれません。
+これは他のカーネル開発者にとってレビューしやすくなるので、あなたの
+パッチを受け入れてもらうためにはとても重要なことです。これを補助でき
+る多くのスクリプトがあります。
+
+Quilt:
+http://savannah.nongnu.org/projects/quilt
+
+2) パッチに対する説明
+
+パッチの中の変更点に対する技術的な詳細について説明してください。
+
+説明はできる限り具体的に。もっとも悪い説明は「ドライバー X を更新」、
+「ドライバー X に対するバグフィックス」あるいは「このパッチはサブシス
+テム X に対する更新を含んでいます。どうか取り入れてください。」などです。
+
+パッチの説明を Linux カーネルのソースコードマネジメントシステム「 git 」の
+コミットログとして簡単に引用できる形で書けば、メンテナから感謝されるでしょう。
+以下の #15 を見てください。
+
+説明が長くなりだしたのであれば、おそらくそれはパッチを分ける必要がある
+という兆候です。次の #3 を見てください。
+
+パッチ(シリーズ)を(再)投稿する時、十分なパッチの説明とそのパッチが必要な理由を
+パッチに含めてください。ただ「これはパッチ(シリーズ)のバージョン N」とだけ
+書かないでください。そして、パッチをマージする人にパッチの説明を探させそれを
+パッチに追記させるため、過去のバージョンのパッチやそのパッチの URL を参照する
+手間をかけさせないでください。
+つまり、パッチシリーズとその説明は一緒にあるべきです。これはパッチをマージする
+人、レビューする人、どちらのためにもなります。レビューする人の中には、おそらく
+過去のバージョンのパッチを受け取ってもいない人がいます。
+
+登録済みのバグエントリを修正するパッチであれば、そのバグエントリを示すバグ ID
+や URL を明記してください。
+
+特定のコミットを参照したい場合は、その SHA-1 ID だけでなく、一行サマリ
+も含めてください。それにより、それが何に関するコミットなのかがレビューする
+人にわかりやすくなります。
+例 (英文のママ):
+
+       Commit e21d2170f36602ae2708 ("video: remove unnecessary
+       platform_set_drvdata()") removed the unnecessary
+       platform_set_drvdata(), but left the variable "dev" unused,
+       delete it.
+
+特定のコミットで導入された不具合を修正する場合（例えば ``git bisect`` で原因となった
+コミットを特定したときなど）は、コミットの SHA-1 の先頭12文字と1行の要約を添えた
+「Fixes:」タグを付けてください。この行は75文字を超えても構いませんが、途中で
+改行せず、必ず1行で記述してください。
+例:
+        Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed")
+
+以下の git の設定を使うと、git log や git show で上記形式を出力するための
+専用の出力形式を追加できます::
+
+        [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")
+
+3) パッチの分割
+
+意味のあるひとまとまりごとに変更を個々のパッチファイルに分けてください。
+
+例えば、もし1つのドライバーに対するバグフィックスとパフォーマンス強
+化の両方の変更を含んでいるのであれば、その変更を2つ以上のパッチに分
+けてください。もし変更箇所に API の更新と、その新しい API を使う新たな
+ドライバーが含まれているなら、2つのパッチに分けてください。
+
+一方で、もしあなたが多数のファイルに対して意味的に同じ1つの変更を加え
+るのであれば、その変更を1つのパッチにまとめてください。言いかえると、
+意味的に同じ1つの変更は1つのパッチの中に含まれます。
+
+あるパッチが変更を完結させるために他のパッチに依存していたとしても、
+それは問題ありません。パッチの説明の中で「このパッチはパッチ X に依存
+している」と簡単に注意書きをつけてください。
+
+もしパッチをより小さなパッチの集合に凝縮することができないなら、まずは
+15かそこらのパッチを送り、そのレビューと統合を待って下さい。
+
+4) パッチのスタイルチェック
+
+あなたのパッチが基本的な( Linux カーネルの)コーディングスタイルに違反し
+ていないかをチェックして下さい。その詳細を Documentation/process/coding-style.rst で
+見つけることができます。コーディングスタイルの違反はレビューする人の
+時間を無駄にするだけなので、恐らくあなたのパッチは読まれることすらなく
+拒否されるでしょう。
+
+あなたはパッチを投稿する前に最低限パッチスタイルチェッカー
+( scripts/checkpatch.pl )を利用してパッチをチェックすべきです。
+もしパッチに違反がのこっているならば、それらの全てについてあなたは正当な
+理由を示せるようにしておく必要があります。
+
+5) 電子メールの宛先の選び方
+
+MAINTAINERS ファイルとソースコードに目を通してください。そして、その変
+更がメンテナのいる特定のサブシステムに加えられるものであることが分か
+れば、その人に電子メールを送ってください。その際
+./scripts/get_maintainers.pl のスクリプトが有用です。
+
+もし、メンテナが載っていなかったり、メンテナからの応答がないなら、
+LKML ( linux-kernel@vger.kernel.org )へパッチを送ってください。ほとんど
+のカーネル開発者はこのメーリングリストに目を通しており、変更に対して
+コメントを得ることができます。
+
+15個より多くのパッチを同時に vger.kernel.org のメーリングリストへ送らな
+いでください!!!
+
+Linus Torvalds は Linux カーネルに入る全ての変更に対する最終的な意思決定者
+です。電子メールアドレスは torvalds@linux-foundation.org になります。彼は
+多くの電子メールを受け取っているため、できる限り彼に電子メールを送るのは
+避けるべきです。
+
+バグフィックスであったり、自明な変更であったり、話し合いをほとんど
+必要としないパッチは Linus へ電子メールを送るか CC しなければなりません。
+話し合いを必要としたり、明確なアドバンテージがないパッチは、通常まず
+は LKML へ送られるべきです。パッチが議論された後にだけ、そのパッチを
+Linus へ送るべきです。
+
+6) CC (カーボンコピー)先の選び方
+
+特に理由がないなら、LKML にも CC してください。
+
+Linus 以外のカーネル開発者は変更に気づく必要があり、その結果、彼らはそ
+の変更に対してコメントをくれたり、コードに対してレビューや提案をくれ
+るかもしれません。LKML とは Linux カーネル開発者にとって一番中心的なメー
+リングリストです。USB やフレームバッファデバイスや VFS や SCSI サブシステ
+ムなどの特定のサブシステムに関するメーリングリストもあります。あなた
+の変更に、はっきりと関連のあるメーリングリストについて知りたければ
+MAINTAINERS ファイルを参照してください。
+
+VGER.KERNEL.ORG でホスティングされているメーリングリストの一覧が下記の
+サイトに載っています。
+<http://vger.kernel.org/vger-lists.html>
+
+もし、変更がユーザランドのカーネルインタフェースに影響を与え
+るのであれば、MAN-PAGES のメンテナ( MAINTAINERS ファイルに一覧
+があります)に man ページのパッチを送ってください。少なくとも
+情報がマニュアルページの中に入ってくるように、変更が起きたという
+通知を送ってください。
+
+たとえ、メンテナが #5 で反応がなかったとしても、メンテナのコードに変更を
+加えたときには、いつもメンテナに CC するのを忘れないようにしてください。
+
+
+7) MIME やリンクや圧縮ファイルや添付ファイルではなくプレインテキストのみ
+
+Linus や他のカーネル開発者はあなたが投稿した変更を読んで、コメントでき
+る必要があります。カーネル開発者にとって、あなたが書いたコードの特定の
+部分にコメントをするために、標準的な電子メールクライアントで変更が引用
+できることは重要です。
+
+上記の理由で、すべてのパッチは文中に含める形式の電子メールで投稿さ
+れるべきです。警告：あなたがパッチをコピー&ペーストする際には、パッ
+チを改悪するエディターの折り返し機能に注意してください。
+
+パッチを圧縮の有無に関わらず MIME 形式で添付しないでください。多くのポ
+ピュラーな電子メールクライアントは MIME 形式の添付ファイルをプレーンテ
+キストとして送信するとは限らないでしょう。そうなると、電子メールクラ
+イアントがコードに対するコメントを付けることをできなくします。また、
+MIME 形式の添付ファイルは Linus に手間を取らせることになり、その変更を
+受け入れてもらう可能性が低くなってしまいます。
+
+例外：お使いの電子メールクライアントがパッチをめちゃくちゃにするので
+あれば、誰かが MIME 形式のパッチを再送するよう求めるかもしれません。
+
+余計な変更を加えずにあなたのパッチを送信するための電子メールクライアントの設定
+のヒントについては Documentation/process/email-clients.rst を参照してください。
+
+8) 電子メールのサイズ
+
+パッチを Linus へ送るときは常に #7 の手順に従ってください。
+
+大きなパッチはメーリングリストやメンテナにとって不親切です。パッチが
+未圧縮で 300KB を超えるようであるなら、インターネット上のアクセス可能な
+サーバに保存し、保存場所を示す URL を伝えるほうが適切です。
+
+9) カーネルバージョンの明記
+
+パッチが対象とするカーネルのバージョンをパッチの概要か電子メールの
+サブジェクトに付けることが重要です。
+
+パッチが最新バージョンのカーネルに正しく適用できなければ、Linus は
+そのパッチを採用しないでしょう。
+
+10) がっかりせず再投稿
+
+パッチを投稿した後は、辛抱強く待っていてください。Linus があなたのパッ
+チを気に入って採用すれば、Linus がリリースする次のバージョンのカーネル
+の中で姿を見せるでしょう。
+
+しかし、パッチが次のバージョンのカーネルに入っていないなら、いくつもの
+理由があるのでしょう。その原因を絞り込み、間違っているものを正し、更新
+したパッチを投稿するのはあなたの仕事です。
+
+Linus があなたのパッチに対して何のコメントもなく不採用にすることは極め
+て普通のことです。それは自然な姿です。もし、Linus があなたのパッチを受
+け取っていないのであれば、以下の理由が考えられます。
+* パッチが最新バージョンの Linux カーネルにきちんと適用できなかった
+* パッチが LKML で十分に議論されていなかった
+* スタイルの問題(セクション2を参照)
+* 電子メールフォーマットの問題(このセクションを参照)
+* パッチに対する技術的な問題
+* Linus はたくさんの電子メールを受け取っているので、どさくさに紛れて見
+  失った
+* 不愉快にさせている
+
+判断できない場合は、LKML にコメントを頼んでください。
+
+11) サブジェクトに「 PATCH 」
+
+Linus や LKML への大量の電子メールのために、サブジェクトのプレフィックスに
+「 [PATCH] 」を付けることが慣習となっています。これによって Linus や他の
+カーネル開発者がパッチであるのか、又は、他の議論に関する電子メールであるの
+かをより簡単に識別できます。
+
+12) パッチへの署名
+
+誰が何をしたのかを追いかけやすくするために (特に、パッチが何人かの
+メンテナを経て最終的に Linux カーネルに取り込まれる場合のために)、電子
+メールでやり取りされるパッチに対して「 sign-off 」という手続きを導入し
+ました。
+
+「 sign-off 」とは、パッチがあなたの書いたものであるか、あるいは、
+あなたがそのパッチをオープンソースとして提供する権利を保持している、
+という証明をパッチの説明の末尾に一行記載するというものです。
+ルールはとても単純です。以下の項目を確認して下さい。
+
+        原作者の証明書( DCO ) 1.1
+
+        このプロジェクトに寄与するものとして、以下のことを証明する。
+
+        (a) 本寄与は私が全体又は一部作成したものであり、私がそのファイ
+            ル中に明示されたオープンソースライセンスの下で公開する権利
+            を持っている。もしくは、
+
+        (b) 本寄与は、私が知る限り、適切なオープンソースライセンスでカバ
+            ーされている既存の作品を元にしている。同時に、私はそのライセ
+            ンスの下で、私が全体又は一部作成した修正物を、ファイル中で示
+            される同一のオープンソースライセンスで(異なるライセンスの下で
+            投稿することが許可されている場合を除いて)投稿する権利を持って
+            いる。もしくは、
+
+        (c) 本寄与は(a)、(b)、(c)を証明する第3者から私へ直接提供された
+            ものであり、私はそれに変更を加えていない。
+
+        (d) 私はこのプロジェクトと本寄与が公のものであることに理解及び同意す
+            る。同時に、関与した記録(投稿の際の全ての個人情報と sign-off を
+            含む)が無期限に保全されることと、当該プロジェクト又は関連する
+            オープンソースライセンスに沿った形で再配布されることに理解及び
+            同意する。
+
+もしこれに同意できるなら、以下のような1行を追加してください。
+
+	Signed-off-by: Random J Developer <random@developer.example.org>
+
+実名を使ってください。(残念ですが、偽名や匿名による寄与はできません。)
+
+人によっては sign-off の近くに追加のタグを付加しています。それらは今のところ
+無視されますが、あなたはそのタグを社内の手続きに利用したり、sign-off に特別
+な情報を示したりすることができます。
+
+あなたがサブシステムまたはブランチのメンテナであれば、受け取ったパッチを自身の
+ツリーにマージするために、わずかに変更が必要となる場合があります。なぜなら
+あなたのツリーの中のコードと投稿者のツリーの中のコードは同一ではないためです。
+もし、あなたが厳密に上記ルール(c)にこだわるのであれば、投稿者に再度差分を
+とるよう依頼すべきです。しかし、これは時間とエネルギーを非生産的に浪費する
+ことになります。ルール(b)はあなたにコードを修正する権利を与えてくれます。
+しかし、投稿者のコードを修正し、その修正によるバグを投稿者に押し付けてしまう
+ことはとても失礼なことです。この問題を解決するために、末尾の投稿者の
+Signed-off-by とあなたがその末尾に追加する Signed-off-by の間に、修正を
+加えたことを示す1行を追加することが推奨されています。
+(その1行の書き方に)決まりはありませんが、大括弧の中に電子メールアドレスや氏名
+と修正内容を記載するやり方は目につきやすく、最終段階での変更の責任があなたに
+あることを明確にするのに十分な方法のようです。例えば、
+
+	Signed-off-by: Random J Developer <random@developer.example.org>
+	[lucky@maintainer.example.org: struct foo moved from foo.c to foo.h]
+	Signed-off-by: Lucky K Maintainer <lucky@maintainer.example.org>
+
+あなたが安定版のブランチを管理しており、作成者のクレジット、変更の追跡、
+修正のマージ、と同時に苦情からの投稿者の保護を行いたい場合、この慣習は特に
+有用となります。いかなる事情があってもチェンジログに出てくる作成者の
+アイデンティティ情報(From ヘッダ)は変更できないことに注意してください。
+
+バックポートする人のための特別な注意事項。追跡を容易に行うために、コミット
+メッセージのトップ(サブジェクト行のすぐ後)にパッチの起源を示す情報を記述する
+ことは一般的で有用な慣習です。例えば、これは 2.6-stable ツリーでの一例です。    
+
+    Date:   Tue May 13 19:10:30 2008 +0000
+
+        SCSI: libiscsi regression in 2.6.25: fix nop timer handling
+
+        commit 4cf1043593db6a337f10e006c23c69e5fc93e722 upstream
+
+そして、これは 2.4 ツリーでの一例です。
+
+    Date:   Tue May 13 22:12:27 2008 +0200
+
+        wireless, airo: waitbusy() won't delay
+
+        [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a]
+
+どんな形式であれ、この情報はあなたのツリーを追跡する人やあなたのツリーのバグを
+解決しようとしている人にとって価値のある支援となります。
+
+13) いつ Acked-by: と Cc: を使うのか
+
+「 Signed-off-by: 」タグはその署名者がパッチの開発に関わっていたことやパッチ
+の伝播パスにいたことを示しています。
+
+ある人が直接パッチの準備や作成に関わっていないけれど、その人のパッチに対す
+る承認を記録し、示したいとします。その場合、その人を示すのに Acked-by: が使
+えます。Acked-by: はパッチのチェンジログにも追加されます。
+
+パッチの影響を受けるコードのメンテナがパッチに関わっていなかったり、パッチ
+の伝播パスにいなかった時にも、メンテナは Acked-by: をしばしば利用します。
+
+Acked-by: は Signed-off-by: のように公式なタグではありません。それはメンテナが
+少なくともパッチをレビューし、同意を示しているという記録です。そのような
+ことからパッチをマージする人がメンテナの「うん、良いと思うよ」という発言を
+Acked-by: へ置き換えることがあります。
+
+Acked-by: が必ずしもパッチ全体の承認を示しているわけではありません。例えば、
+あるパッチが複数のサブシステムへ影響を与えており、その中の1つのサブシステム
+のメンテナからの Acked-by: を持っているとします。その場合、Acked-by: は通常
+そのメンテナのコードに影響を与える一部分だけに対する承認を示しています。
+この点は、ご自分で判断してください。(その Acked-by: が)疑わしい場合は、
+メーリングリストアーカイブの中の大元の議論を参照すべきです。
+
+パッチにコメントする機会を持っていたが、その時にコメントしなかった人がいれば、
+その人を指す「Cc:」タグを任意で追加してもかまいません。これは指定された人からの
+明確なアクションなしに付与できる唯一のタグです。
+このタグはパッチに関心があると思われる人達がそのパッチの議論に含まれていたこと
+を明文化します。
+
+14) Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: および Fixes: の利用
+
+他の誰かによって報告された問題を修正するパッチであれば、問題報告者という寄与を
+クレジットするために、Reported-by: タグを追加することを検討してください。
+こまめにバグ報告者をクレジットしていくことで、うまくいけばその人たちが将来再び
+コミュニティの力となってくれるでしょう。
+ただし、報告者の許可無くこのタグを追加しないように注意してください。特に、
+問題が公の場で報告されていなかったのであれば。
+
+Tested-by: タグはタグで指定された人によって(ある環境下で)パッチのテストに成功
+していることを示します。このタグはメンテナにテストが実施済みであることを
+知らせ、将来の関連パッチのテスト協力者を見つける方法を提供し、テスト実施者に
+対するクレジットを保証します。
+
+Reviewed-by: タグは、それとは異なり、下記のレビューア宣言の下にレビューされ、
+受け入れ可能とみなされたパッチであることを示します。
+
+        レビューアによる監督宣言
+
+        私は Reviewed-by: タグを提示することによって、以下のことを明言する。
+
+        (a) 私はメインラインカーネルへの統合に向け、その妥当性及び「即応性
+            (訳注)」を検証し、技術的側面からパッチをレビュー済みである。
+
+        訳注:
+        「即応性」の原文は "readiness"。
+        パッチが十分な品質を持っており、メインラインカーネルへの統合を即座に
+        行うことができる状態であるかどうかを "readiness" という単語で表現
+        している。
+
+        (b) パッチに関するあらゆる問題、懸念、あるいは、疑問は投稿者へ伝達済み
+            である。私はそれらのコメントに対する投稿者の返答に満足している。
+
+        (c) 投稿に伴い改良されるコードがある一方で、現時点で、私は(1)それが
+            カーネルにとって価値のある変更であること、そして、(2)統合に際して
+            議論になり得るような問題はないものと確信している。
+
+        (d) 私はパッチをレビューし適切であると確信している一方で、あらゆる
+            状況においてその宣言した目的や機能が正しく実現することに関して、
+            いかなる保証もしない(特にどこかで明示しない限り)。
+
+Reviewed-by タグはそのパッチがカーネルに対して適切な修正であって、深刻な技術的
+問題を残していないという意見の宣言です。興味のあるレビューアは誰でも(レビュー
+作業を終えたら)パッチに対して Reviewed-by タグを提示できます。このタグは
+レビューアの寄与をクレジットする働き、レビューの進捗の度合いをメンテナに
+知らせる働きを持ちます。そのパッチの領域に詳しく、そして、しっかりとした
+レビューを実施したレビューアによって提供される時、Reviewed-by: タグがあなたの
+パッチをカーネルにマージする可能性を高めるでしょう。
+
+Suggested-by: タグは、パッチのアイデアがその人からの提案に基づくものである
+ことを示し、アイデアの提供をクレジットするものです。提案者の明示的な許可が
+ない場合、特にそのアイデアが公開のフォーラムで示されていない場合には、この
+タグをつけないように注意してください。とはいえ、アイデアの提供者をこつこつ
+クレジットしていけば、望むらくはその人たちが将来別の機会に再度力を貸す気に
+なってくれるかもしれません。
+
+Fixes: タグは、そのパッチが以前のコミットにあった問題を修正することを示します。
+これは、バグがどこで発生したかを特定しやすくし、バグ修正のレビューに役立ちます。
+また、このタグはstableカーネルチームが、あなたの修正をどのstableカーネル
+バージョンに適用すべきか判断する手助けにもなります。パッチによって修正された
+バグを示すには、この方法が推奨されます。前述の、「2) パッチに対する説明」の
+セクションを参照してください。
+
+15) 標準的なパッチのフォーマット
+
+標準的なパッチのサブジェクトは以下のとおりです。
+
+    Subject: [PATCH 001/123] subsystem: summary phrase
+
+標準的なパッチの、電子メールのボディは以下の項目を含んでいます。
+
+  - パッチの作成者を明記する「 from 」行
+
+  - 空行
+
+  - 説明本体。これはこのパッチを説明するために無期限のチェンジログ
+    (変更履歴)にコピーされます。
+
+  - 上述した「 Signed-off-by: 」行。これも説明本体と同じくチェン
+    ジログ内にコピーされます。
+
+  - マーカー行は単純に「 --- 」です。
+
+  - 余計なコメントは、チェンジログには不適切です。
+
+  - 実際のパッチ(差分出力)
+
+サブジェクト行のフォーマットは、アルファベット順で電子メールをとても
+ソートしやすいものになっています。(ほとんどの電子メールクライアント
+はソートをサポートしています)パッチのサブジェクトの連番は0詰めであ
+るため、数字でのソートとアルファベットでのソートは同じ結果になります。
+
+電子メールのサブジェクト内のサブシステム表記は、パッチが適用される
+分野またはサブシステムを識別できるようにすべきです。
+
+電子メールのサブジェクトの「summary phrase」はそのパッチの概要を正確
+に表現しなければなりません。「summary phrase」をファイル名にしてはい
+けません。パッチシリーズ中でそれぞれのパッチは同じ「summary phrase」を
+使ってはいけません(「パッチシリーズ」とは順序付けられた関連のある複数の
+パッチ群です)。
+
+あなたの電子メールの「summary phrase」がそのパッチにとって世界で唯一の識別子に
+なるように心がけてください。「summary phrase」は git のチェンジログの中へ
+ずっと伝播していきます。「summary phrase」は、開発者が後でパッチを参照する
+ために議論の中で利用するかもしれません。
+人々はそのパッチに関連した議論を読むために「summary phrase」を使って google で
+検索したがるでしょう。それはまた2、3ヶ月あとで、人々が「gitk」や
+「git log --oneline」のようなツールを使用して何千ものパッチに目を通す時、
+唯一目にとまる情報となるでしょう。
+
+これらの理由のため、「summary phrase」はなぜパッチが必要であるか、パッチが何を
+変更するかの2つの情報をせいぜい70〜75文字で表現していなければなりません。
+「summary phrase」は簡潔であり説明的である表現を目指しつつ、うまく
+まとめられている概要となるべきです。
+
+「summary phrase」は「Subject: [PATCH tag] <summary phrase>」のように、
+大括弧で閉じられたタグを接頭辞として付加してもかまいません。このタグは
+「summary phrase」の一部とは考えませんが、パッチをどのように取り扱うべきかを
+表現します。
+一般的には「v1, v2, v3」のようなバージョン情報を表すタグ(過去のパッチに対する
+コメントを反映するために複数のバージョンのパッチが投稿されているのであれば)、
+「RFC」のようなコメントを要求するタグが挙げられます。パッチシリーズとして4つの
+パッチがあれば、個々のパッチに「1/4, 2/4, 3/4, 4/4」のように番号を付けても
+かまいません。これは開発者がパッチを適用する順番を確実に把握するためです。
+そして、開発者がパッチシリーズの中のすべてのパッチをもらさずレビュー或いは
+適用するのを保証するためです。
+
+サブジェクトの例を二つ
+
+    Subject: [patch 2/5] ext2: improve scalability of bitmap searching
+    Subject: [PATCHv2 001/207] x86: fix eflags tracking
+
+「 from 」行は電子メールのボディの一番最初の行でなければなりません。
+その形式は以下のとおりです。
+
+        From: Original Author <author@example.com>
+
+「 from 」行はチェンジログの中で、そのパッチの作成者としてクレジットされ
+ている人を特定するものです。「 from 」行がかけていると、電子メールのヘッ
+ダーの「 From: 」が、チェンジログの中でパッチの作成者を決定するために使わ
+れるでしょう。
+
+説明本体は無期限のソースのチェンジログにコミットされます。なので、説明
+本体はそのパッチに至った議論の詳細を忘れているある程度の技量を持っている人
+がその詳細を思い出すことができるものでなければなりません。パッチが対処する
+障害の症状(カーネルログメッセージや oops メッセージ等)を記載することは問題に
+対処可能なパッチを求めてコミットログを検索する人々にとって特に有用です。
+パッチがコンパイル問題を解決するのであれば、そのパッチを探している人が見つける
+ことができる情報だけで十分であり、コンパイル時の全てのエラーを含める必要は
+ありません。「summary phrase」と同様に、簡潔であり説明的であることが重要です。
+
+「 --- 」マーカー行はパッチ処理ツールに対して、チェンジログメッセージの終端
+部分を認識させるという重要な役目を果たします。
+
+「 --- 」マーカー行の後の追加コメントの良い使用方法の1つに diffstat コマンド
+があります。diffstat コマンドとは何のファイルが変更され、1ファイル当たり何行
+追加され何行消されたかを示すものです。diffstat コマンドは特に大きなパッチに
+おいて役立ちます。その時点でだけ又はメンテナにとってのみ関係のあるコメント
+は無期限に保存されるチェンジログにとって適切ではありません。そのため、この
+ようなコメントもマーカー行の後に書かれるべきです。
+このようなコメントの良い例として、v1 と v2 のバージョン間で何が変更されたかを
+表す「パッチの変更履歴」が挙げられます。
+
+「 --- 」マーカー行の後に diffstat コマンドの結果を含めるのであれば、ファイル
+名はカーネルソースツリーのトップディレクトリからの表記で列記されるため、横方向
+のスペースをとり過ぎないように、diffstat コマンドにオプション「 -p 1 -w 70 」
+を指定してください(インデントを含めてちょうど80列に合うでしょう)。
+
+適切なパッチのフォーマットの詳細についてはセクション3の参考文献を参照して
+ください。
+
+16) 「git pull」要求の送り方(Linus の電子メールから)
+
+間違ったブランチから引っ張るのを防ぐために、git リポジトリのアドレスと
+ブランチ名を同じ行に1行で記載してください。そうすることで、3回の連続クリック
+で全て選択できます。
+
+正しい形式は下記の通りです。
+
+	"Please pull from
+
+		git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus
+
+	 to get these changes:"
+
+その結果、アドレスを自分自身でタイピングして間違えることはなくなります(実際に、
+何度か間違ったブランチから引っ張ってきてしまい、その時に diffstat の結果を
+検証して間違っていることに気づいたことがあります。どこから何を引っ張るべきかを
+「探したり」、正しいブランチ名かどうかを重ねてチェックしたりする必要が
+なくなればより快適になるでしょう)。
+
+diffstat の結果を生成するために「 git diff -M --stat --summary 」を使って
+ください。-M オプションはファイル名の変更を検知でき、--summary オプションは
+新規ファイル、削除されたファイル、名前が変更されたファイルの概要を生成します。
+
+-M オプション(ファイル名の変更検知)を指定すると、diffstat の結果はかなり
+異なってきます。git は大規模な変更(追加と削除のペア)をファイル名の変更と
+判断するためです。
+
+------------------------------------
+セクション2 - ヒントとTIPSと小技
+------------------------------------
+
+このセクションは Linux カーネルに変更を適用することに関係のある一般的な
+「お約束」の多くを載せています。物事には例外というものがあります。しか
+し例外を適用するには、本当に妥当な理由が不可欠です。あなたは恐らくこの
+セクションを Linus のコンピュータ・サイエンス101と呼ぶでしょう。
+
+1) Documentation/process/coding-style.rstを参照
+
+言うまでもなく、あなたのコードがこのコーディングスタイルからあまりに
+も逸脱していると、レビューやコメントなしに受け取ってもらえないかもし
+れません。
+
+特筆すべき例外は、コードをあるファイルから別のファイルに移動
+するときです。この場合、コードを移動するパッチでは、移動されるコード
+に関して移動以外の変更を一切加えるべきではありません。これにより、
+コードの移動とあなたが行ったコードの修正を明確に区別できるようにな
+ります。これは実際に何が変更されたかをレビューする際の大きな助けに
+なるとともに、ツールにコードの履歴を追跡させることも容易になります。
+
+投稿するより前にパッチのスタイルチェッカー( scripts/checkpatch.pl )で
+あなたのパッチをチェックしてください。このスタイルチェッカーは最終結
+論としてではなく、指標としてみるべきです。もし、あなたのコードが違反
+はしているが修正するより良く見えるのであれば、おそらくそのままにする
+のがベストです。
+
+スタイルチェッカーによる3段階のレポート:
+ - エラー: 間違っている可能性が高い
+ - 警告：注意してレビューする必要がある
+ - チェック：考慮する必要がある
+
+あなたはパッチに残っている全ての違反について、それがなぜ必要なのか正当な
+理由を示せるようにしておく必要があります。
+
+2) #ifdefは見苦しい
+
+ifdef が散乱したコードは、読むのもメンテナンスするのも面倒です。コードの中
+で ifdef を使わないでください。代わりに、ヘッダファイルの中に ifdef を入れて、
+条件付きで、コードの中で使われる関数を「 static inline 」関数かマクロで定義し
+てください。後はコンパイラが、何もしない箇所を最適化して取り去ってくれるで
+しょう。
+
+まずいコードの簡単な例
+
+	dev = alloc_etherdev (sizeof(struct funky_private));
+	if (!dev)
+		return -ENODEV;
+	#ifdef CONFIG_NET_FUNKINESS
+	init_funky_net(dev);
+	#endif
+
+クリーンアップしたコードの例
+
+(in header)
+	#ifndef CONFIG_NET_FUNKINESS
+	static inline void init_funky_net (struct net_device *d) {}
+	#endif
+
+(in the code itself)
+	dev = alloc_etherdev (sizeof(struct funky_private));
+	if (!dev)
+		return -ENODEV;
+	init_funky_net(dev);
+
+3) マクロより「 static inline 」を推奨
+
+「 static inline 」関数はマクロよりもずっと推奨されています。それらは、
+型安全性があり、長さにも制限が無く、フォーマットの制限もありません。
+gcc においては、マクロと同じくらい軽いです。
+
+マクロは「 static inline 」が明らかに不適切であると分かる場所(高速化パスの
+いくつかの特定のケース)や「 static inline 」関数を使うことができないような
+場所(マクロの引数の文字列連結のような)にだけ使われるべきです。
+
+「 static inline 」は「 static __inline__ 」や「 extern inline 」や
+「 extern __inline__ 」よりも適切です。
+
+4) 設計に凝りすぎるな
+
+それが有用になるかどうか分からないような不明瞭な将来を見越した設計
+をしないでください。「できる限り簡単に、そして、それ以上簡単になら
+ないような設計をしてください。」
+
+----------------------
+セクション3 参考文献
+----------------------
+
+Andrew Morton, "The perfect patch" (tpp).
+  <http://www.ozlabs.org/~akpm/stuff/tpp.txt>
+
+Jeff Garzik, "Linux kernel patch submission format".
+  <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>
+
+Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
+  <http://www.kroah.com/log/linux/maintainer.html>
+  <http://www.kroah.com/log/linux/maintainer-02.html>
+  <http://www.kroah.com/log/linux/maintainer-03.html>
+  <http://www.kroah.com/log/linux/maintainer-04.html>
+  <http://www.kroah.com/log/linux/maintainer-05.html>
+
+NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!
+  <https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net>
+
+Kernel Documentation/process/coding-style.rst:
+  <http://users.sosdg.org/~qiyong/lxr/source/Documentation/process/coding-style.rst>
+
+Linus Torvalds's mail on the canonical patch format:
+  <https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org>
+
+Andi Kleen, "On submitting kernel patches"
+  Some strategies to get difficult or controversial changes in.
+  http://halobates.de/on-submitting-patches.pdf
+
+--
+
+

linux-7.2.3/Documentation/translations/ja_JP/disclaimer-ja_JP.rst

@@ -0,0 +1,24 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _translations_ja_JP_disclaimer:
+
+==========================
+免責条項 (Disclaimer) 抄訳
+==========================
+
+.. note:: 【訳註】
+   この文書は、
+   :ref:`Disclaimer (英語版) <translations_disclaimer>`
+   の一部を翻訳したものです。全文は英語版を参照願います。
+
+Documentation/translations/ja_JP/ 以下のファイルは、対応する
+Documentation/　以下のファイル (原文) の日本語訳です。
+翻訳と原文との違いや翻訳上の問題を見つけたら、
+MAINTAINERS に記載の維持管理者に知らせてください。
+翻訳が原文の更新に追いついていない場合は、それを日本語版に反映するパッチの
+投稿も歓迎です。
+
+なお、この翻訳の目的は非英語 (ここでは日本語) 話者への便宜提供であり、
+フォークを意図したものではない事を念頭においてください。したがって、
+このファイルの内容に対するコメントや更新すべきことがあれば、先に原文の
+更新を検討してください。

linux-7.2.3/Documentation/translations/ja_JP/index.rst

@@ -0,0 +1,21 @@
+.. raw:: latex
+
+	\renewcommand\thesection*
+	\renewcommand\thesubsection*
+	\kerneldocCJKon
+	\kerneldocBeginJP{
+
+日本語訳
+=====================
+
+.. toctree::
+   :maxdepth: 1
+
+   disclaimer-ja_JP
+   process/howto
+   process/submitting-patches
+   process/submit-checklist
+
+.. raw:: latex
+
+	}\kerneldocEndJP

linux-7.2.3/Documentation/translations/ja_JP/process/howto.rst

@@ -0,0 +1,629 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. Originally contributed by Tsugikazu Shibata
+
+Linux カーネル開発のやり方
+==========================
+
+.. note:: 【訳註】
+   この文書は、
+   Documentation/process/howto.rst
+   の翻訳です。
+   免責条項については、
+   :ref:`免責条項の抄訳 <translations_ja_JP_disclaimer>` および、
+   :ref:`Disclaimer (英語版) <translations_disclaimer>` を参照してください。
+
+これは上のトピック( Linux カーネル開発のやり方)の重要な事柄を網羅した
+ドキュメントです。ここには Linux カーネル開発者になるための方法とLinux
+カーネル開発コミュニティと共に活動するやり方を学ぶ方法が含まれています。
+カーネルプログラミングに関する技術的な項目に関することは何も含めないよ
+うにしていますが、カーネル開発者となるための正しい方向に向かう手助けに
+なります。
+
+もし、このドキュメントのどこかが古くなっていた場合には、このドキュメント
+の最後にリストしたメンテナにパッチを送ってください。
+
+はじめに
+---------
+
+あなたは Linux カーネルの開発者になる方法を学びたいのでしょうか？　そ
+れとも上司から「このデバイスの Linux ドライバを書くように」と言われた
+のかもしれません。この文書の目的は、あなたが踏むべき手順と、コミュニティ
+と一緒にうまく働くヒントを書き下すことで、あなたが知るべき全てのことを
+教えることです。また、このコミュニティがなぜ今うまくまわっているのかと
+いう理由も説明しようと試みています。
+
+カーネルは少量のアーキテクチャ依存部分がアセンブリ言語で書かれている以
+外の大部分は C 言語で書かれています。C言語をよく理解していることはカー
+ネル開発に必要です。低レベルのアーキテクチャ開発をするのでなければ、
+(どんなアーキテクチャでも)アセンブリ(訳注: 言語)は必要ありません。以下
+の本は、C 言語の十分な知識や何年もの経験に取って代わるものではありませ
+んが、少なくともリファレンスとしては良い本です。
+
+ - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall]
+ - 『プログラミング言語Ｃ第2版』(B.W. カーニハン/D.M. リッチー著 石田晴久訳) [共立出版]
+ - "Practical C Programming" by Steve Oualline [O'Reilly]
+ - 『C実践プログラミング第3版』(Steve Oualline著 望月康司監訳 谷口功訳) [オライリージャパン]
+ - "C:  A Reference Manual" by Harbison and Steele [Prentice Hall]
+ - 『新・詳説 C 言語 H&S リファレンス』 (サミュエル P ハービソン/ガイ L スティール共著 斉藤 信男監訳)[ソフトバンク]
+
+カーネルは GNU C と GNU ツールチェインを使って書かれています。カーネル
+は ISO C11 仕様に準拠して書く一方で、標準には無い言語拡張を多く使って
+います。カーネルは標準 C ライブラリに依存しない、自立した C 環境です。
+そのため、C の標準の中で使えないものもあります。特に任意の long long
+の除算や浮動小数点は使えません。カーネルがツールチェインや C 言語拡張
+に置いている前提がどうなっているのかわかりにくいことが時々あり、また、
+残念なことに決定的なリファレンスは存在しません。情報を得るには、gcc の
+info ページ( info gcc )を見てください。
+
+あなたは既存の開発コミュニティと一緒に作業する方法を学ぼうとしているこ
+とに思い出してください。そのコミュニティは、コーディング、スタイル、開
+発手順について高度な標準を持つ、多様な人の集まりです。地理的に分散した
+大規模なチームに対してもっともうまくいくとわかったことをベースにしなが
+ら、これらの標準は長い時間をかけて築かれてきました。これらはきちんと文
+書化されていますから、これらの標準について事前にできるだけたくさ
+ん学んでください。また皆があなたやあなたの会社のやり方に合わせてくれる
+と思わないでください。
+
+法的問題
+--------
+
+Linux カーネルのソースコードは GPL ライセンスの下でリリースされていま
+す。ソースツリーのメインディレクトリにある COPYING のファイルを見てく
+ださい。Linux カーネルのライセンスルールとソースコード内の
+`SPDX <https://spdx.org/>`_ 識別子の使い方は
+:ref:`Documentation/process/license-rules.rst <kernel_licensing>`
+に説明されています。
+
+もしライセンスについてさらに質問があれば、
+Linux Kernel メーリングリストに質問するのではなく、どうぞ
+法律家に相談してください。メーリングリストの人達は法律家ではなく、法的
+問題については彼らの声明はあてにするべきではありません。
+
+GPL に関する共通の質問や回答については、以下を参照してください-
+
+	https://www.gnu.org/licenses/gpl-faq.html
+
+ドキュメント
+------------
+
+Linux カーネルソースツリーは幅広い範囲のドキュメントを含んでおり、それ
+らはカーネルコミュニティと会話する方法を学ぶのに非常に貴重なものです。
+新しい機能がカーネルに追加される場合、その機能の使い方について説明した
+新しいドキュメントファイルも追加することを勧めます。
+カーネルの変更が、カーネルがユーザ空間に公開しているインターフェイスの
+変更を引き起こす場合、その変更を説明するマニュアルページのパッチや情報
+をマニュアルページのメンテナ alx@kernel.org に送り、CC を
+linux-api@vger.kernel.org に送ることを勧めます。
+
+以下はカーネルソースツリーに含まれている読んでおくべきファイルの一覧で
+す-
+
+  :ref:`Documentation/admin-guide/README.rst <readme>`
+    このファイルは Linuxカーネルの簡単な背景とカーネルを設定(訳注
+    configure )し、生成(訳注 build )するために必要なことは何かが書かれ
+    ています。 カーネルに関して初めての人はここからスタートすると良い
+    でしょう。
+
+  :ref:`Documentation/process/changes.rst <changes>`
+    このファイルはカーネルをうまく生成(訳注 build )し、走らせるのに最
+    小限のレベルで必要な数々のソフトウェアパッケージの一覧を示してい
+    ます。
+
+  :ref:`Documentation/process/coding-style.rst <codingstyle>`
+    これは Linux カーネルのコーディングスタイルと背景にある理由を記述
+    しています。全ての新しいコードはこのドキュメントにあるガイドライン
+    に従っていることを期待されています。大部分のメンテナはこれらのルー
+    ルに従っているものだけを受け付け、多くの人は正しいスタイルのコード
+    だけをレビューします。
+
+  :ref:`Documentation/process/submitting-patches.rst <codingstyle>`
+    このファイルには、どうやってうまくパッチを作って投稿するかにつ
+    いて非常に詳しく書かれており、以下を含みます (これだけに限らない
+    けれども)
+
+      - Email に含むこと
+      - Email の形式
+      - だれに送るか
+
+    これらのルールに従えばうまくいくことを保証することではありません
+    が (すべてのパッチは内容とスタイルについて精査を受けるので)、
+    ルールに従わなければ間違いなくうまくいかないでしょう。
+
+    この他にパッチを作る方法についてのよくできた記述は-
+
+       "The Perfect Patch"
+		https://www.ozlabs.org/~akpm/stuff/tpp.txt
+
+       "Linux kernel patch submission format"
+		https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html
+
+  :ref:`Documentation/process/stable-api-nonsense.rst <stable_api_nonsense>`
+    このファイルはカーネルの中に不変の API を持たないことにした意識的
+    な決断の背景にある理由について書かれています。以下のようなことを含
+    んでいます-
+
+      - サブシステムとの間に層を作ること(コンパチビリティのため?)
+      - オペレーティングシステム間のドライバの移植性
+      - カーネルソースツリーの素早い変更を遅らせる(もしくは素早い変更を妨げる)
+
+    このドキュメントは Linux 開発の思想を理解するのに非常に重要です。
+    そして、他のOSでの開発者が Linux に移る時にとても重要です。
+
+  :ref:`Documentation/process/security-bugs.rst <securitybugs>`
+    もし Linux カーネルでセキュリティ問題を発見したように思ったら、こ
+    のドキュメントのステップに従ってカーネル開発者に連絡し、問題解決を
+    支援してください。
+
+  :ref:`Documentation/process/management-style.rst <managementstyle>`
+    このドキュメントは Linux カーネルのメンテナ達がどう行動するか、
+    彼らの手法の背景にある共有されている精神について記述しています。こ
+    れはカーネル開発の初心者なら（もしくは、単に興味があるだけの人でも）
+    重要です。なぜならこのドキュメントは、カーネルメンテナ達の独特な
+    行動についての多くの誤解や混乱を解消するからです。
+
+  :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`
+    このファイルはどのように stable カーネルのリリースが行われるかのルー
+    ルが記述されています。そしてこれらのリリースの中のどこかで変更を取
+    り入れてもらいたい場合に何をすれば良いかが示されています。
+
+  :Ref:`Documentation/process/kernel-docs.rst <kernel_docs>`
+    カーネル開発に付随する外部ドキュメントのリストです。もしあなたが探
+    しているものがカーネル内のドキュメントでみつからなかった場合、この
+    リストをあたってみてください。
+
+  :ref:`Documentation/process/applying-patches.rst <applying_patches>`
+    パッチとはなにか、パッチをどうやって様々なカーネルの開発ブランチに
+    適用するのかについて正確に記述した良い入門書です。
+
+カーネルはソースコードそのものや、このファイルのようなリストラクチャー
+ドテキストマークアップ(ReST)から自動的に生成可能な多数のドキュメントを
+もっています。これにはカーネル内APIの完全な記述や、正しくロックをかけ
+るための規則などが含まれます。
+
+これら全てのドキュメントを PDF や HTML で生成するには以下を実行します - ::
+
+        make pdfdocs
+        make htmldocs
+
+それぞれメインカーネルのソースディレクトリから実行します。
+
+ReSTマークアップを使ったドキュメントは Documentation/outputに生成され
+ます。Latex とePub 形式で生成するには - ::
+
+        make latexdocs
+        make epubdocs
+
+カーネル開発者になるには
+------------------------
+
+もしあなたが、Linux カーネル開発について何も知らないのならば、
+KernelNewbies プロジェクトを見るべきです
+
+	https://kernelnewbies.org
+
+このサイトには役に立つメーリングリストがあり、基本的なカーネル開発に関
+するほとんどどんな種類の質問もできます (既に回答されているようなことを
+聞く前にまずはアーカイブを調べてください)。またここには、リアルタイム
+で質問を聞くことができる IRC チャネルや、Linuxカーネルの開発に関して学
+ぶのに便利なたくさんの役に立つドキュメントがあります。
+
+Web サイトには、コードの構成、サブシステム、現在存在するプロジェクト
+(ツリーにあるもの無いものの両方)の基本的な管理情報があります。ここには、
+また、カーネルのコンパイルのやり方やパッチの当て方などの間接的な基本情
+報も記述されています。
+
+あなたがどこからスタートして良いかわからないが、Linux カーネル開発コミュ
+ニティに参加して何かすることをさがしているのであれば、Linux kernel
+Janitor's プロジェクトにいけば良いでしょう -
+
+        https://kernelnewbies.org/KernelJanitors
+
+ここはそのようなスタートをするのにうってつけの場所です。ここには、
+Linux カーネルソースツリーの中に含まれる、きれいにし、修正しなければな
+らない、単純な問題のリストが記述されています。このプロジェクトに関わる
+開発者と一緒に作業することで、あなたのパッチを Linuxカーネルツリーに入
+れるための基礎を学ぶことができ、そしてもしあなたがまだアイディアを持っ
+ていない場合には、次にやる仕事の方向性が見えてくるかもしれません。
+
+実際に Linux カーネルのコードについて修正を加える前に、どうやってその
+コードが動作するのかを理解することが必要です。そのためには、特別なツー
+ルの助けを借りてでも、それを直接よく読むことが最良の方法です(ほとんど
+のトリッキーな部分は十分にコメントしてありますから)。そういうツールで
+特におすすめなのは、Linux クロスリファレンスプロジェクトです。これは、
+自己参照方式で、索引がついた web 形式で、ソースコードを参照することが
+できます。この最新の素晴しいカーネルコードのリポジトリは以下で見つかり
+ます -
+
+	https://elixir.bootlin.com/
+
+開発プロセス
+------------
+
+Linux カーネルの開発プロセスは現在幾つかの異なるメインカーネル「ブラン
+チ」と多数のサブシステム毎のカーネルブランチから構成されます。これらの
+ブランチとは -
+
+  - Linus のメインラインツリー
+  - メジャー番号をまたぐ数本の安定版ツリー
+  - サブシステム毎のカーネルツリー
+  - 統合テストのための linux-next カーネルツリー
+
+メインラインツリー
+~~~~~~~~~~~~~~~~~~
+
+メインラインツリーは Linus Torvalds によってメンテナンスされ、
+https://kernel.org のリポジトリに存在します。
+この開発プロセスは以下のとおり -
+
+  - 新しいカーネルがリリースされた直後に、2週間の特別期間が設けられ、
+    この期間中に、メンテナ達は Linus に大きな差分を送ることができます。
+    このような差分は通常 linux-next カーネルに数週間含まれてきたパッチです。
+    大きな変更は git(カーネルのソース管理ツール、詳細は
+    http://git-scm.com/ 参照) を使って送るのが好ましいやり方ですが、パッ
+    チファイルの形式のまま送るのでも十分です。
+  - 2週間後 -rc1 カーネルがリリースされ、新しいカーネルを可能な限り堅牢に
+    することに焦点が移ります。この期間のパッチのほとんどは退行を修正する
+    ものとなります。以前から存在していたバグは退行には当たらないため、
+    送るのは重要な修正だけにしてください。
+    新しいドライバ (もしくはファイルシステム) のパッチは
+    -rc1 の後で受け付けられることもあることを覚えておいてください。な
+    ぜなら、変更が独立していて、追加されたコードの外の領域に影響を与え
+    ない限り、退行のリスクは無いからです。-rc1 がリリースされた後、
+    Linus へパッチを送付するのに git を使うこともできますが、パッチは
+    レビューのために、パブリックなメーリングリストへも同時に送る必要が
+    あります。
+  - 新しい -rc は Linus が、最新の git ツリーがテスト目的であれば十分
+    に安定した状態にあると判断したときにリリースされます。目標は毎週新
+    しい -rc カーネルをリリースすることです。
+  - このプロセスはカーネルが 「準備ができた」と考えられるまで継続しま
+    す。このプロセスはだいたい 6週間継続します。
+
+Andrew Morton が Linux-kernel メーリングリストにカーネルリリースについ
+て書いたことをここで言っておくことは価値があります -
+
+        *「カーネルがいつリリースされるかは誰も知りません。なぜなら、
+        これは現実に認識されたバグの状況によりリリースされるのであり、
+        前もって決められた計画によってリリースされるものではないから
+        です。」*
+
+メジャー番号をまたぐ数本の安定版ツリー
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+バージョン番号が3つの数字に分かれているカーネルは -stable カーネルです。
+これには最初の2つのバージョン番号の数字に対応した、
+メジャーメインラインリリースで見つかったセキュリティ問題や
+重大な後戻りに対する比較的小さい重要な修正が含まれます。
+
+メジャー安定版シリーズのそれぞれのリリースは
+バージョン番号の3番目を増加させ、最初の2つの番号は同じ値を保ちます。
+
+これは、開発/実験的バージョンのテストに協力することに興味が無く、最新
+の安定したカーネルを使いたいユーザに推奨するブランチです。
+
+安定版ツリーは"stable" チーム <stable@vger.kernel.org> でメンテされており、
+必要に応じてリリースされます。通常のリリース期間は 2週間毎ですが、差
+し迫った問題がなければもう少し長くなることもあります。セキュリティ関
+連の問題の場合はこれに対してだいたいの場合、すぐにリリースがされます。
+
+カーネルツリーに入っている、
+Documentation/process/stable-kernel-rules.rst ファイルにはどのような種
+類の変更が -stable ツリーに受け入れ可能か、またリリースプロセスがどう
+動くかが記述されています。
+
+サブシステム毎のカーネルツリー
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+それぞれのカーネルサブシステムのメンテナ達は --- そして多くのカーネル
+サブシステムの開発者達も --- 各自の最新の開発状況をソースリポジトリに
+公開しています。そのため、自分とは異なる領域のカーネルで何が起きている
+かを他の人が見られるようになっています。開発が早く進んでいる領域では、
+開発者は自身の投稿がどのサブシステムカーネルツリーを元にしているか質問
+されるので、その投稿とすでに進行中の他の作業との衝突が避けられます。
+
+大部分のこれらのリポジトリは git ツリーです。しかしその他の SCM や
+quilt シリーズとして公開されているパッチキューも使われています。これら
+のサブシステムリポジトリのアドレスは MAINTAINERS ファイルにリストされ
+ています。これらの多くは https://git.kernel.org/ で参照することができま
+す。
+
+提案されたパッチがこのようなサブシステムツリーにコミットされる前に、メー
+リングリストで事前にレビューにかけられます（以下の対応するセクションを
+参照）。いくつかのカーネルサブシステムでは、このレビューは patchworkと
+いうツールによって追跡されます。Patchwork は web インターフェイスによっ
+てパッチ投稿の表示、パッチへのコメント付けや改訂などができ、そしてメン
+テナはパッチに対して、レビュー中、受付済み、拒否というようなマークをつ
+けることができます。大部分のこれらの patchwork のサイトは
+https://patchwork.kernel.org/ でリストされています。
+
+統合テストのための linux-next カーネルツリー
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+サブシステムツリーの更新内容がメインラインツリーにマージされる
+前に、それらは統合テストされる必要があります。この目的のため、実質的に
+全サブシステムツリーからほぼ毎日プルされてできる特別なテスト用のリポジ
+トリが存在します-
+
+       https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git
+
+このやり方によって、linux-next は次のマージ機会でどんなものがメイン
+ラインにマージされるか、おおまかな展望を提供します。
+linux-next の実行テストを行う冒険好きなテスターは大いに歓迎されます。
+
+バグレポート
+-------------
+
+メインカーネルソースディレクトリにあるファイル
+'Documentation/admin-guide/reporting-issues.rst'
+は、カーネルバグらしきものの報告の仕方、および、カーネル開発者が問題を
+追跡する際の手がかりとなる情報についての詳細を説明しています。
+
+バグレポートの管理
+-------------------
+
+あなたのハッキングのスキルを訓練する最高の方法のひとつに、他人がレポー
+トしたバグを修正することがあります。あなたがカーネルをより安定化させる
+ことに寄与するということだけでなく、あなたは 現実の問題を修正することを
+学び、自分のスキルも強化でき、また他の開発者があなたの存在に気がつきま
+す。バグを修正することは、多くの開発者の中から自分が功績をあげる最善の
+道です、なぜなら多くの人は他人のバグの修正に時間を浪費することを好まな
+いからです。
+
+すでにレポートされたバグの作業をするためには、興味のあるサブシステムを
+見つけ、そのサブシステムのバグの報告先 (多くの場合メーリングリスト、
+稀にバグトラッカー) を MAINTAINERS ファイルで調べてください。
+そのアーカイブで最近の報告を検索し、できそうなものに力を貸してください。
+https://bugzilla.kernel.org でバグ報告を調べようとする人もいるでしょう。
+これは限られた一部のサブシステムのバグ報告と追跡に利用されるとともに、
+とりわけ、カーネル全体に対するバグの登録先となっています。
+
+メーリングリスト
+----------------
+
+上のいくつかのドキュメントで述べていますが、コアカーネル開発者の大部分
+は Linux kernel メーリングリストに参加しています。このリストの登録/脱
+退の方法については以下を参照してください-
+
+	https://subspace.kernel.org/subscribing.html
+
+このメーリングリストのアーカイブは web 上の多数の場所に存在します。こ
+れらのアーカイブを探すにはサーチエンジンを使いましょう。例えば-
+
+	https://lore.kernel.org/linux-kernel/
+
+リストに投稿する前にすでにその話題がアーカイブに存在するかどうかを検索
+することを是非やってください。多数の事がすでに詳細に渡って議論されてお
+り、アーカイブにのみ記録されています。
+
+大部分のカーネルサブシステムも自分の個別の開発を実施するメーリングリス
+トを持っています。個々のグループがどんなリストを持っているかは、
+MAINTAINERS ファイルにリストがありますので参照してください。
+
+多くのリストは kernel.org でホストされています。これらの情報は以下にあ
+ります -
+
+	https://subspace.kernel.org
+
+メーリングリストを使う場合、良い行動習慣に従うようにしましょう。少し安っ
+ぽいが、以下の URL は上のリスト(や他のリスト)で会話する場合のシンプル
+なガイドラインを示しています -
+
+	https://subspace.kernel.org/etiquette.html
+
+もし複数の人があなたのメールに返事をした場合、CC: で受ける人のリストは
+だいぶ多くなるでしょう。正当な理由がない限り、CC: リストから誰かを削除
+をしないように、また、メーリングリストのアドレスだけにリプライすること
+のないようにしましょう。1つは送信者から、もう1つはリストからのように、
+メールを2回受けることになってもそれに慣れ、しゃれたメールヘッダーを追
+加してこの状態を変えようとしないように。人々はそのようなことは好みませ
+ん。
+
+今までのメールでのやりとりとその間のあなたの発言はそのまま残し、
+"John Kernelhacker wrote ...:" の行をあなたのリプライの先頭行にして、
+メールの先頭でなく、各引用行の間にあなたの言いたいことを追加するべきで
+す。
+
+もしパッチをメールに付ける場合は、
+Documentation/process/submitting-patches.rst に提示されているように、そ
+れは プレーンな可読テキストにすることを忘れないようにしましょう。カー
+ネル開発者は 添付や圧縮したパッチを扱いたがりません。彼らはあなたのパッ
+チの行毎にコメントを入れたいので、そうするしかありません。あなたのメー
+ルプログラムが空白やタブを圧縮しないように確認しましょう。最初の良いテ
+ストとしては、自分にメールを送ってみて、そのパッチを自分で当ててみるこ
+とです。もしそれがうまく行かないなら、あなたのメールプログラムを直して
+もらうか、正しく動くように変えるべきです。
+
+何をおいても、他の購読者に対する敬意を表すことを忘れないでください。
+
+コミュニティと共に働くこと
+--------------------------
+
+カーネルコミュニティのゴールは可能なかぎり最高のカーネルを提供すること
+です。あなたがパッチを受け入れてもらうために投稿した場合、それは、技術
+的メリットだけがレビューされます。その際、あなたは何を予想すべきでしょ
+うか?
+
+  - 批判
+  - コメント
+  - 変更の要求
+  - パッチの正当性の証明要求
+  - 沈黙
+
+思い出してください、これはあなたのパッチをカーネルに入れる話です。あな
+たは、あなたのパッチに対する批判とコメントを受け入れるべきで、それらを
+技術的レベルで評価して、パッチを再作成するか、なぜそれらの変更をすべき
+でないかを明確で簡潔な理由の説明を提供してください。もし、あなたのパッ
+チに何も反応がない場合、たまにはメールの山に埋もれて見逃され、あなたの
+投稿が忘れられてしまうこともあるので、数日待って再度投稿してください。
+
+あなたがやるべきでないことは?
+
+  - 質問なしにあなたのパッチが受け入れられると想像すること
+  - 守りに入ること
+  - コメントを無視すること
+  - 要求された変更を何もしないでパッチを出し直すこと
+
+可能な限り最高の技術的解決を求めているコミュニティでは、パッチがどのく
+らい有益なのかについては常に異なる意見があります。あなたは協調的である
+べきですし、また、あなたのアイディアをカーネルに対してうまく合わせるよ
+うにすることが望まれています。もしくは、最低限あなたのアイディアがそれ
+だけの価値があるとすすんで証明するようにしなければなりません。
+正しい解決に向かって進もうという意志がある限り、間違うことがあっても許
+容されることを忘れないでください。
+
+あなたの最初のパッチに単に 1ダースもの修正を求めるリストの返答になるこ
+とも普通のことです。これはあなたのパッチが受け入れられないということで
+は **ありません**、そしてあなた自身に反対することを意味するのでも **あ
+りません**。単に自分のパッチに対して指摘された問題を全て修正して再送す
+れば良いのです。
+
+
+カーネルコミュニティと企業組織のちがい
+-----------------------------------------------------------------
+
+カーネルコミュニティは大部分の伝統的な会社の開発環境とは異ったやり方で
+動いています。以下は問題を避けるためにできると良いことのリストです。
+
+  あなたの提案する変更について言うときのうまい言い方 -
+
+    - "これは複数の問題を解決します"
+    - "これは2000行のコードを削除します"
+    - "以下のパッチは、私が言おうとしていることを説明するものです"
+    - "私はこれを5つの異なるアーキテクチャでテストしたのですが..."
+    - "以下は一連の小さなパッチ群ですが..."
+    - "これは典型的なマシンでの性能を向上させます..."
+
+  やめた方が良い悪い言い方 -
+
+    - "このやり方で AIX/ptx/Solaris ではできたので、できるはずだ..."
+    - "私はこれを20年もの間やってきた、だから..."
+    - "これは私の会社が金儲けをするために必要だ"
+    - "これは我々のエンタープライズ向け商品ラインのためである"
+    - "これは私が自分のアイディアを記述した、1000ページの設計資料である"
+    - "私はこれについて、6ケ月作業している..."
+    - "以下は ... に関する5000行のパッチです"
+    - "私は現在のぐちゃぐちゃを全部書き直した、それが以下です..."
+    - "私は〆切がある、そのためこのパッチは今すぐ適用される必要がある"
+
+カーネルコミュニティが大部分の伝統的なソフトウェアエンジニアリングの労
+働環境と異なるもう一つの点は、やりとりに顔を合わせないということです。
+email と irc を第一のコミュニケーションの形とする一つの利点は、性別や
+民族の差別がないことです。Linux カーネルの職場環境は女性や少数民族を受
+容します。なぜなら、email アドレスによってのみあなたが認識されるからで
+す。
+国際的な側面からも活動領域を均等にするようにします。なぜならば、あなた
+は人の名前で性別を想像できないからです。ある男性が アンドレアという名
+前で、女性の名前は パット かもしれません (訳注 Andrea は米国では女性、
+それ以外(欧州など)では男性名として使われることが多い。同様に、Pat は
+Patricia (主に女性名)や Patrick (主に男性名)の略称)。
+Linux カーネルの活動をして、意見を表明したことがある大部分の女性は、前
+向きな経験をもっています。
+
+言葉の壁は英語が得意でない一部の人には問題になります。メーリングリスト
+の中で、きちんとアイディアを交換するには、相当うまく英語を操れる必要が
+あることもあります。そのため、自分のメールを送る前に英語で意味が通じて
+いるかをチェックすることをお薦めします。
+
+変更を分割する
+--------------
+
+Linux カーネルコミュニティは、一度に大量のコードの塊を喜んで受容するこ
+とはありません。変更は正確に説明される必要があり、議論され、小さい、個
+別の部分に分割する必要があります。これはこれまで多くの会社がやり慣れて
+きたことと全く正反対のことです。あなたのプロポーザルは、開発プロセスのと
+ても早い段階から紹介されるべきです。そうすれば あなたは自分のやってい
+ることにフィードバックを得られます。これは、コミュニティからみれば、あ
+なたが彼らと一緒にやっているように感じられ、単にあなたの提案する機能の
+ゴミ捨て場として使っているのではない、と感じられるでしょう。
+しかし、一度に 50 もの email をメーリングリストに送りつけるようなことは
+やってはいけません、あなたのパッチ群はいつもどんな時でもそれよりは小さ
+くなければなりません。
+
+パッチを分割する理由は以下 -
+
+1) 小さいパッチはあなたのパッチが適用される見込みを大きくします、カー
+   ネルの人達はパッチが正しいかどうかを確認する時間や労力をかけないか
+   らです。5行のパッチはメンテナがたった1秒見るだけで適用できます。
+   しかし、500行のパッチは、正しいことをレビューするのに数時間かかるか
+   もしれません(時間はパッチのサイズなどにより指数関数に比例してかかり
+   ます)
+
+   小さいパッチは何かあったときにデバッグもとても簡単になります。パッ
+   チを1個1個取り除くのは、とても大きなパッチを当てた後に(かつ、何かお
+   かしくなった後で)解剖するのに比べればとても簡単です。
+
+2) 小さいパッチを送るだけでなく、送るまえに、書き直して、シンプルにす
+   る(もしくは、単に順番を変えるだけでも)ことも、とても重要です。
+
+以下はカーネル開発者の Al Viro のたとえ話です -
+
+        *"生徒の数学の宿題を採点する先生のことを考えてみてください、
+        先生は生徒が解に到達するまでの試行錯誤を見たいとは思わないでし
+        ょう。先生は簡潔な最高の解を見たいのです。良い生徒はこれを知っ
+        ており、そして最終解の前の中間作業を提出することは決してないの
+        です*
+
+        *カーネル開発でもこれは同じです。メンテナ達とレビューア達は、
+        問題を解決する解の背後になる思考プロセスを見たいとは思いません。
+        彼らは単純であざやかな解決方法を見たいのです。"*
+
+あざやかな解を説明するのと、コミュニティと共に仕事をし、未解決の仕事を
+議論することのバランスをキープするのは難しいかもしれません。ですから、
+開発プロセスの早期段階で改善のためのフィードバックをもらうようにするの
+も良いですが、変更点を小さい部分に分割して全体ではまだ完成していない仕
+事を(部分的に)取り込んでもらえるようにすることも良いことです。
+
+また、でき上がっていないものや、"将来直す" ようなパッチを、本流に含め
+てもらうように送っても、それは受け付けられないことを理解してください。
+
+あなたの変更を正当化する
+------------------------
+
+あなたのパッチを分割するのと同時に、なぜその変更を追加しなければならな
+いかを Linux コミュニティに知らせることはとても重要です。新機能は必要
+性と有用性で正当化されなければなりません。
+
+あなたの変更を説明する
+----------------------
+
+あなたのパッチを送付する場合には、メールの中のテキストで何を言うかにつ
+いて、特別に注意を払ってください。この情報はパッチの ChangeLog に使わ
+れ、いつも皆がみられるように保管されます。これは次のような項目を含め、
+パッチを完全に記述するべきです -
+
+  - なぜ変更が必要か
+  - パッチ全体の設計アプローチ
+  - 実装の詳細
+  - テスト結果
+
+これについて全てがどのようにあるべきかについての詳細は、以下のドキュメ
+ントの ChangeLog セクションを見てください -
+
+  "The Perfect Patch"
+      https://www.ozlabs.org/~akpm/stuff/tpp.txt
+
+これらはどれも、実行することが時にはとても困難です。これらの例を完璧に
+実施するには数年かかるかもしれません。これは継続的な改善のプロセスであ
+り、多くの忍耐と決意を必要とするものです。でも諦めないで、実現は可能で
+す。多数の人がすでにできていますし、彼らも最初はあなたと同じところから
+スタートしたのですから。
+
+
+
+
+----------
+
+Paolo Ciarrocchi に感謝、彼は彼の書いた "Development Process"
+(https://lwn.net/Articles/94386/) セクションをこのテキストの原型にする
+ことを許可してくれました。Rundy Dunlap と Gerrit Huizenga はメーリング
+リストでやるべきこととやってはいけないことのリストを提供してくれました。
+以下の人々のレビュー、コメント、貢献に感謝。
+Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers,
+Vojtech Pavlik, Jan Kara, Josh Boyer, Kees Cook, Andrew Morton, Andi
+Kleen, Vadim Lobanov, Jesper Juhl, Adrian Bunk, Keri Harris, Frans Pop,
+David A. Wheeler, Junio Hamano, Michael Kerrisk, と Alex Shepard
+彼らの支援なしでは、このドキュメントはできなかったでしょう。
+
+
+
+Maintainer: Greg Kroah-Hartman <greg@kroah.com>

linux-7.2.3/Documentation/translations/ja_JP/process/submit-checklist.rst

@@ -0,0 +1,163 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. Translated by Akira Yokosawa <akiyks@gmail.com>
+
+.. An old translation of this document of a different origin was at
+   Documentation/translations/ja_JP/SubmitChecklist, which can be found
+   in the pre-v6.14 tree if you are interested.
+   Please note that this translation is independent of the previous one.
+
+======================================
+Linux カーネルパッチ投稿チェックリスト
+======================================
+
+.. note:: 【訳註】
+   この文書は、
+   Documentation/process/submit-checklist.rst
+   の翻訳です。
+   免責条項については、
+   :ref:`免責条項の抄訳 <translations_ja_JP_disclaimer>` および、
+   :ref:`Disclaimer (英語版) <translations_disclaimer>` を参照してください。
+
+以下は、カーネルパッチの投稿時に、そのスムーズな受け入れのために心がける
+べき基本的な事項です。
+
+これは、 Documentation/process/submitting-patches.rst およびその他の
+Linux カーネルパッチ投稿に関する文書を踏まえ、それを補足するものです。
+
+.. note:: 【訳註】
+   可能な項目については、パッチもしくはパッチ内の更新を暗黙の主語として、
+   その望ましい状態を表す文体とします。その他、原義を損なわない範囲で
+   係り結びを調整するなど、簡潔で把握しやすい箇条書きを目指します。
+
+
+コードのレビュー
+================
+
+1) 利用する機能について、その機能を定義・宣言しているファイルを
+   ``#include`` している。
+   他のヘッダーファイル経由での取り込みに依存しない。
+
+2) Documentation/process/coding-style.rst に詳述されている一般的なスタイル
+   についてチェック済み。
+
+3) メモリバリアー (例, ``barrier()``, ``rmb()``, ``wmb()``) について、
+   そのすべてに、作用と目的、及び必要理由についての説明がソースコード内の
+   コメントとして記述されている。
+
+
+Kconfig 変更のレビュー
+======================
+
+1) 新規の、もしくは変更された ``CONFIG`` オプションについて、それが関係する
+   コンフィグメニューへの悪影響がない。また、
+   Documentation/kbuild/kconfig-language.rst の
+   "Menu attributes: default value" に記載の例外条件を満たす場合を除き、
+   そのデフォルトが無効になっている。
+
+2) 新規の ``Kconfig`` オプションにヘルプテキストがある。
+
+3) 妥当な ``Kconfig`` の組み合わせについて注意深くレビューされている。
+   これをテストでやり切るのは困難で、知力が決め手となる。
+
+ドキュメンテーションの作成
+==========================
+
+1) グローバルなカーネル API が  :ref:`kernel-doc <kernel_doc>` の形式で
+   ドキュメント化されている (静的関数には求められないが、付けてもよい)。
+
+2) 新規 ``/proc`` エントリーが、すべて ``Documentation/`` 以下に記載されて
+   いる。
+
+3) 新規カーネル・ブート・パラメータが、すべて
+   ``Documentation/admin-guide/kernel-parameters.rst`` に記載されている。
+
+4) 新規モジュール・パラメータが、すべて ``MODULE_PARM_DESC()`` によって記述
+   されている。
+
+5) 新規ユーザースペース・インターフェースが、すべて ``Documentation/ABI/``
+   以下に記載されている。詳しくは、 Documentation/admin-guide/abi.rst
+   (もしくは ``Documentation/ABI/README``) を参照。
+   ユーザースペース・インターフェースを変更するパッチは、
+   linux-api@vger.kernel.org にも CC すべし。
+
+6) なんらかの ioctl を追加するパッチは、
+   ``Documentation/userspace-api/ioctl/ioctl-number.rst``
+   の更新を伴う。
+
+ツールによるコードのチェック
+============================
+
+1) スタイル・チェッカー (``scripts/checkpatch.pl``) によって、犯しがちな
+   パッチ・スタイルの違反がないことを確認済み。
+   指摘される違反を残す場合は、それを正当化できること。
+
+2) sparse により入念にチェック済み。
+
+3) ``make checkstack`` で指摘される問題があれば、それが修正済み。
+   ``checkstack`` は問題点を明示的には指摘しないが、 スタック消費が
+   512 バイトを越える関数は見直しの候補。
+
+コードのビルド
+==============
+
+1) 以下の条件でクリーンにビルドできる。
+
+   a) 適用可能な、および ``=y``, ``=m``, ``=n`` を変更した ``CONFIG``
+      オプションでのビルド。
+      ``gcc`` およびリンカーからの警告・エラーがないこと。
+
+   b) ``allnoconfig`` と ``allmodconfig`` がパス
+
+   c) ``O=builddir`` を指定してのビルド
+
+   d) Documentation/ 以下の変更に関して、ドキュメントのビルドで新たな警告や
+      エラーが出ない。
+      ``make htmldocs`` または ``make pdfdocs`` でビルドし、問題があれば修正。
+
+2) ローカルのクロス・コンパイル・ツール、その他のビルド環境 (訳註: build farm)
+   を使って、複数の CPU アーキテクチャ向けにビルドできる。
+   特に、ワードサイズ (32 ビットと 64 ビット) やエンディアン (ビッグとリトル)
+   の異なるアーキテクチャを対象とするテストは、表現可能数値範囲・データ整列・
+   エンディアンなどについての誤った仮定に起因する様々な移植上の問題を捕える
+   のに効果的。
+
+3) 新規に追加されたコードについて (``make KCFLAGS=-W`` を使って)
+   ``gcc -W`` でコンパイル。
+   これは多くのノイズを伴うが、
+   ``warning: comparison between signed and unsigned``
+   の類いのバグをあぶり出すのに効果的。
+
+4) 変更されるソースコードが、下記の ``Kconfig`` シンボルに関連するカーネル
+   API や機能に依存 (もしくは利用) する場合、それらの ``Kconfig`` シンボルが、
+   無効、および (可能なら) ``=m`` の場合を組み合わせた複数のビルドを
+   (全部まとめてではなく、いろいろなランダムの組み合わせで) テスト済み。
+
+   ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``,
+   ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``,
+   ``CONFIG_NET``, ``CONFIG_INET=n`` (ただし、後者は ``CONFIG_NET=y``
+   との組み合わせ)。
+
+コードのテスト
+==============
+
+1) ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``,
+   ``CONFIG_SLUB_DEBUG``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``,
+   ``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``,
+   ``CONFIG_PROVE_RCU`` および ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` をすべて
+   同時に有効にしてのテスト済み。
+
+2) ``CONFIG_SMP`` と ``CONFIG_PREEMPT`` が有効と無効の場合について、ビルドと
+   ランタイムのテスト済み。
+
+3) lockdep の機能をすべて有効にしての実行で、すべてのコード経路が確認済み。
+
+4) 最低限、slab と ページ・アロケーションの失敗に関する誤り注入
+   (訳註: fault injection) によるチェック済み。
+   詳しくは、 Documentation/fault-injection/index.rst を参照。
+   新規のコードが多い場合は、サブシステム対象の誤り注入を追加するのが望ましい
+   可能性あり。
+
+5) linux-next の最新タグに対するテストにより、他でキューイングされている
+   パッチや、VM、VFS、その他のサブシステム内のすべての変更と組み合わせての
+   動作を確認済み。

linux-7.2.3/Documentation/translations/ja_JP/process/submitting-patches.rst

@@ -0,0 +1,404 @@
+.. _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`` の
+「コミットログ」としてそのまま取り込める形で書けば、メンテナは
+助かります。詳細は原文の該当節 ("The canonical patch format") を
+参照してください。
+
+.. TODO: Convert to file-local cross-reference when the destination is
+   translated.
+
+1 つのパッチでは 1 つの問題だけを解決してください。記述が長くなり
+始めたら、パッチを分割すべきサインです。詳細は `変更を分割する`_ を
+参照してください。
+
+
+パッチまたはパッチシリーズを投稿／再投稿する際は、その完全な
+説明と、それを正当化する理由を含めてください。単に「これはパッチ
+（シリーズ）のバージョン N です」とだけ書くのは避けてください。
+サブシステムメンテナが以前のパッチバージョンや参照先 URL をさかのぼって
+パッチ記述を探し、それをパッチに補うことを期待してはいけません。
+つまり、パッチ（シリーズ）とその説明は、それだけで完結しているべき
+です。これはメンテナとレビューアの双方に有益です。レビューアの
+中には、以前のパッチバージョンを受け取っていない人もいるでしょう。
+
+変更内容は、あたかもコードベースに対してその振る舞いを変えるように
+命令するかの如く、（訳補: 英語の）命令形で記述してください。たとえば、
+"[This patch] makes xyzzy do frotz" や
+"[I] changed xyzzy to do frotz" のような言い回しを避け、
+"make xyzzy 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 つ以上のパッチに分けてください。
+変更に API の更新と、その新しい API を使う新しいドライバが
+含まれるなら、それらは 2 つのパッチに分けてください。
+
+一方、多数のファイルに対して単一の変更を行う場合は、それらを
+1 つのパッチにまとめてください。つまり、1 つの論理的な変更は
+1 つのパッチに含めるべきです。
+
+覚えておくべき点は、各パッチがレビューアに理解しやすく、
+検証できる変更であるべきだということです。各パッチは、
+それ自体の妥当性で正当化できなければなりません。
+
+変更を完成させるために、あるパッチが別のパッチに依存するなら、
+それでも構いません。単に、パッチの説明に
+**"this patch depends on patch X"** と記してください。
+
+変更を一連のパッチに分ける際は、シリーズ中の各パッチを
+適用した後でも、カーネルが正しくビルドされ、正常に動作することを
+特に注意して確認してください。問題の追跡に ``git bisect`` を
+使う開発者は、あなたのパッチシリーズを任意の地点で分割する
+ことがあります。途中でバグを持ち込めば、彼らに感謝されることは
+ないでしょう。
+
+パッチセットをこれ以上小さくできないなら、一度に投稿するのは
+15 個程度までにして、レビューと統合を待ってください。
+
+
+変更のスタイルを確認する
+------------------------
+
+パッチに基本的なスタイル違反がないか確認してください。詳細は
+Documentation/process/coding-style.rst を参照してください。
+これを怠ると、単にレビューアの時間を無駄にするだけでなく、
+パッチはおそらく読まれもせずに却下されます。
+
+大きな例外が 1 つあります。コードをあるファイルから別の
+ファイルへ移動する場合です。このときは、コードを移動する
+その同じパッチの中で、移動したコードを一切変更してはいけません。
+そうすることで、コードの移動という行為と、あなたの変更とを
+明確に区別できます。これは実際の差分のレビューを大いに助け、
+ツールがコード自体の履歴をより適切に追跡できるようにします。
+
+提出前に、パッチスタイルチェッカー
+(``scripts/checkpatch.pl``) でパッチを確認してください。
+ただし、スタイルチェッカーは指針として見るべきであり、
+人間の判断に取って代わるものではないことに注意してください。
+違反があっても、その方がコードの見栄えがよいなら、
+そのままにしておくのが最善でしょう。
+
+チェッカーは 3 つのレベルで報告します:
+
+ - ERROR: 間違っている可能性が非常に高いもの
+ - WARNING: 慎重なレビューを要するもの
+ - CHECK: 検討を要するもの
+
+パッチに残した違反については、すべて理由を説明できなければ
+なりません。
+
+
+パッチの宛先を選択する
+----------------------
+
+各パッチでは、そのコードを保守する適切なサブシステムメンテナと
+メーリングリストを、必ず Cc に入れてください。誰がその
+メンテナかは、MAINTAINERS ファイルとソースコードの改訂履歴を
+調べて確認してください。この段階では ``scripts/get_maintainer.pl``
+が非常に役立ちます（パッチへのパスを引数として
+``scripts/get_maintainer.pl`` に渡してください）。作業中の
+サブシステムのメンテナが見つからない場合は、Andrew Morton
+(akpm@linux-foundation.org) が最後の手段となるメンテナです。
+
+すべてのパッチでは、デフォルトで linux-kernel@vger.kernel.org を
+使うべきですが、このリストの流量が多いため、目を通さなくなった
+開発者も少なくありません。とはいえ、無関係なメーリングリストや
+無関係な人々にスパムを送らないでください。
+
+カーネル関連のメーリングリストの多くは kernel.org で運営されており、
+その一覧は https://subspace.kernel.org で確認できます。ただし、
+他所で運営されているカーネル関連のメーリングリストもあります。
+
+Linux カーネルに採用されるすべての変更の最終的な裁定者は
+Linus Torvalds です。彼のメールアドレスは
+<torvalds@linux-foundation.org> です。Linus は大量のメールを
+受け取っており、現時点では彼に直接届くパッチはごくわずかなので、
+通常は彼にメールを送ることを極力避けてください。
+
+悪用可能なセキュリティバグを修正するパッチがあるなら、
+そのパッチを security@kernel.org に送ってください。深刻なバグに
+ついては、ディストリビュータがユーザーにパッチを配布できるよう、
+短期間の embargo が検討される場合があります。そのような場合、
+そのパッチを公開メーリングリストに送るべきではありません。
+Documentation/process/security-bugs.rst も参照してください。
+
+リリース済みカーネルの深刻なバグを修正するパッチは、次のような行を
+パッチの sign-off 欄に入れることで、stable メンテナへ向けてください::
+
+  Cc: stable@vger.kernel.org
+
+これはメールの受信者ではないことに注意してください。また、
+この文書に加えて Documentation/process/stable-kernel-rules.rst も
+読んでください。
+
+変更がユーザーランドとカーネルのインターフェースに影響する場合は、
+MAINTAINERS ファイルに記載されている MAN-PAGES メンテナに
+man-pages パッチ、少なくとも変更の通知を送って、情報が
+マニュアルページに反映されるようにしてください。ユーザー空間 API の
+変更は、linux-api@vger.kernel.org にも Cc してください。
+
+MIME・リンク・圧縮・添付なし、プレーンテキストのみ
+----------------------------------------------------
+
+Linus や他のカーネル開発者は、あなたが投稿する変更を読み、
+コメントできる必要があります。カーネル開発者が標準的な
+メールツールを使ってあなたの変更を「引用」し、コードの特定の
+箇所についてコメントできることが重要です。
+
+このため、すべてのパッチはメール本文中に ``inline`` で投稿すべきです。
+これを行う最も簡単な方法は ``git send-email`` を使うことであり、
+強く推奨されます。``git send-email`` の対話型チュートリアルは
+https://git-send-email.io で利用できます。
+
+``git send-email`` を使わないことを選ぶ場合:
+
+.. warning::
+
+  パッチをコピー＆ペーストする場合は、エディタの word-wrap によって
+  パッチが壊れないよう注意してください。
+
+圧縮の有無にかかわらず、パッチを MIME 添付ファイルとして添付しては
+いけません。多くの一般的なメールアプリケーションは、MIME 添付
+ファイルを常にプレーンテキストとして送信するとは限らず、あなたの
+コードにコメントできなくなります。MIME 添付ファイルは Linus が
+処理するのにも少し余分な時間がかかるため、MIME 添付された変更が
+受け入れられる可能性を下げます。
+
+例外:  メーラがパッチを壊してしまう場合は、誰かから MIME を使って
+再送するよう求められることがあります。
+
+パッチを変更せずに送信するようメールクライアントを設定するための
+ヒントについては、Documentation/process/email-clients.rst を参照してください。
+
+
+レビューコメントに返答する
+--------------------------
+
+あなたのパッチには、ほぼ確実に、パッチを改善する方法について
+レビューアからコメントが付きます。それは、あなたのメールへの返信という
+形で届きます。それらのコメントには必ず返答してください。レビューアを
+無視することは、こちらも無視されるためのよい方法です。コメントに
+答えるには、単にそのメールへ返信すれば構いません。コード変更に
+つながらないレビューコメントや質問であっても、次のレビューアが状況を
+よりよく理解できるように、ほぼ確実にコメントまたは changelog エントリに
+反映すべきです。
+
+どのような変更を行うのかをレビューアに必ず伝え、時間を割いてくれた
+ことに感謝してください。コードレビューは疲れる、時間のかかる作業であり、
+レビューアが不機嫌になることもあります。そのような場合であっても、
+丁寧に返答し、指摘された問題に対応してください。次の版を送るときは、
+cover letter または個々のパッチに ``patch changelog`` を追加し、前回の
+投稿との差分を説明してください。詳細は原文の該当節
+("The canonical patch format") を参照してください。
+
+.. TODO: Convert to file-local cross-reference when the destination is
+   translated.
+
+あなたのパッチにコメントした人には、パッチの Cc リストに追加して、
+新しい版を知らせてください。
+
+メールクライアントとメーリングリストでの作法についての推奨事項は、
+Documentation/process/email-clients.rst を参照してください。
+
+メール議論では不要な引用を削った interleaved replies を使う
+------------------------------------------------------------
+
+Linux カーネル開発の議論では、top-posting は強く非推奨とされています。
+Interleaved replies、または ``inline`` replies を使うと、会話の流れを
+ずっと追いやすくなります。詳細は次を参照してください:
+https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
+
+メーリングリストでは、よく次のように引用されます::
+
+  A: http://en.wikipedia.org/wiki/Top_post
+  Q: Where do I find info about this thing called top-posting?
+  A: Because it messes up the order in which people normally read text.
+  Q: Why is top-posting such a bad thing?
+  A: Top-posting.
+  Q: What is the most annoying thing in e-mail?
+
+同様に、返信に関係のない不要な引用はすべて削ってください。
+そうすることで、返答を見つけやすくなり、時間と容量を節約できます。
+詳細は次を参照してください: http://daringfireball.net/2007/07/on_top ::
+
+  A: No.
+  Q: Should I include quotations after my reply?
+
+
+落胆しない、そして急がない
+--------------------------
+
+変更を投稿した後は、辛抱強く待ってください。レビューアは忙しい人たちであり、
+あなたのパッチをすぐに見られるとは限りません。
+
+かつては、パッチが何のコメントもなく虚空へ消えていくこともありましたが、
+現在の開発プロセスはそれよりも円滑に機能しています。数週間以内、
+通常は 2〜3 週間以内にコメントを受け取るはずです。そうならない場合は、
+パッチを正しい場所へ送ったか確認してください。再投稿したりレビューアに
+ping したりする前に、少なくとも 1 週間は待ってください。merge window の
+ような忙しい時期には、さらに長く待つ方がよい場合もあります。
+
+数週間後に、subject line に "RESEND" を追加して、パッチまたは
+パッチシリーズを再送しても構いません::
+
+   [PATCH Vx RESEND] sub/sys: Condensed patch summary
+
+パッチまたはパッチシリーズの修正版を投稿する場合は、"RESEND" を
+追加しないでください。"RESEND" は、前回の投稿から一切変更していない
+パッチまたはパッチシリーズを再送する場合にのみ使います。

linux-7.2.3/Documentation/translations/ja_JP/stable_api_nonsense.txt

@@ -0,0 +1,263 @@
+NOTE:
+This is a version of Documentation/process/stable-api-nonsense.rst into Japanese.
+This document is maintained by IKEDA, Munehiro <m-ikeda@ds.jp.nec.com>
+and the JF Project team <http://www.linux.or.jp/JF/>.
+If you find any difference between this document and the original file
+or a problem with the translation,
+please contact the maintainer of this file or JF project.
+
+Please also note that the purpose of this file is to be easier to read
+for non English (read: Japanese) speakers and is not intended as a
+fork. So if you have any comments or updates of this file, please try
+to update the original English file first.
+
+Last Updated: 2007/07/18
+==================================
+これは、
+linux-2.6.22-rc4/Documentation/process/stable-api-nonsense.rst の和訳
+です。
+翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ >
+翻訳日 ： 2007/06/11
+原著作者: Greg Kroah-Hartman < greg at kroah dot com >
+翻訳者 ： 池田 宗広 < m-ikeda at ds dot jp dot nec dot com >
+校正者 ： Masanori Kobayashi さん < zap03216 at nifty dot ne dot jp >
+          Seiji Kaneko さん < skaneko at a2 dot mbn dot or dot jp >
+==================================
+
+
+
+Linux カーネルのドライバインターフェース
+（あなたの質問すべてに対する回答とその他諸々）
+
+Greg Kroah-Hartman <greg at kroah dot com>
+
+
+この文書は、なぜ Linux ではバイナリカーネルインターフェースが定義
+されていないのか、またはなぜ不変のカーネルインターフェースを持たな
+いのか、ということを説明するために書かれた。ここでの話題は「カーネ
+ル内部の」インターフェースについてであり、ユーザー空間とのインター
+フェースではないことを理解してほしい。カーネルとユーザー空間とのイ
+ンターフェースとはアプリケーションプログラムが使用するものであり、
+つまりシステムコールのインターフェースがこれに当たる。これは今まで
+長きに渡り、かつ今後も「まさしく」不変である。私は確か 0.9 か何か
+より前のカーネルを使ってビルドした古いプログラムを持っているが、そ
+れは最新の 2.6 カーネルでもきちんと動作する。ユーザー空間とのイン
+ターフェースは、ユーザーとアプリケーションプログラマが不変性を信頼
+してよいものの一つである。
+
+
+要旨
+----
+
+あなたは不変のカーネルインターフェースが必要だと考えているかもしれ
+ないが、実際のところはそうではない。あなたは必要としているものが分
+かっていない。あなたが必要としているものは安定して動作するドライバ
+であり、それはドライバがメインのカーネルツリーに含まれる場合のみ得
+ることができる。ドライバがメインのカーネルツリーに含まれていると、
+他にも多くの良いことがある。それは、Linux をより強固で、安定な、成
+熟したオペレーティングシステムにすることができるということだ。これ
+こそ、そもそもあなたが Linux を使う理由のはずだ。
+
+
+はじめに
+--------
+
+カーネル内部のインターフェース変更を心配しなければならないドライバ
+を書きたいなどというのは、変わり者だけだ。この世界のほとんどの人は、
+そのようなドライバがどんなインターフェースを使っているかなど知らな
+いし、そんなドライバのことなど全く気にもかけていない。
+
+
+まず初めに、クローズソースとか、ソースコードの隠蔽とか、バイナリの
+みが配布される使い物にならない代物[訳注(1)]とか、実体はバイナリ
+コードでそれを読み込むためのラッパー部分のみソースコードが公開され
+ているとか、その他用語は何であれ GPL の下にソースコードがリリース
+されていないカーネルドライバに関する法的な問題について、私は「いか
+なる議論も」行うつもりがない。法的な疑問があるのならば、プログラマ
+である私ではなく、弁護士に相談して欲しい。ここでは単に、技術的な問
+題について述べることにする。（法的な問題を軽視しているわけではない。
+それらは実際に存在するし、あなたはそれをいつも気にかけておく必要が
+ある）
+
+訳注(1)
+「使い物にならない代物」の原文は "blob"
+
+
+さてここでは、バイナリカーネルインターフェースについてと、ソースレ
+ベルでのインターフェースの不変性について、という二つの話題を取り上
+げる。この二つは互いに依存する関係にあるが、まずはバイナリインター
+フェースについて議論を行いやっつけてしまおう。
+
+
+バイナリカーネルインターフェース
+--------------------------------
+
+もしソースレベルでのインターフェースが不変ならば、バイナリインター
+フェースも当然のように不変である、というのは正しいだろうか？正しく
+ない。Linux カーネルに関する以下の事実を考えてみてほしい。
+  - あなたが使用するＣコンパイラのバージョンによって、カーネル内部
+    の構造体の配置構造は異なったものになる。また、関数は異なった方
+    法でカーネルに含まれることになるかもしれない（例えばインライン
+    関数として扱われたり、扱われなかったりする）。個々の関数がどの
+    ようにコンパイルされるかはそれほど重要ではないが、構造体のパデ
+    ィングが異なるというのは非常に重要である。
+  - あなたがカーネルのビルドオプションをどのように設定するかによっ
+    て、カーネルには広い範囲で異なった事態が起こり得る。
+      - データ構造は異なるデータフィールドを持つかもしれない
+      - いくつかの関数は全く実装されていない状態になり得る
+        （例：SMP向けではないビルドでは、いくつかのロックは中身が
+          カラにコンパイルされる）
+      - カーネル内のメモリは、異なった方法で配置され得る。これはビ
+        ルドオプションに依存している。
+  - Linux は様々な異なるプロセッサアーキテクチャ上で動作する。
+    あるアーキテクチャ用のバイナリドライバを、他のアーキテクチャで
+    正常に動作させる方法はない。
+
+
+ある特定のカーネル設定を使用し、カーネルをビルドしたのと正確に同じ
+Ｃコンパイラを使用して単にカーネルモジュールをコンパイルするだけで
+も、あなたはこれらいくつもの問題に直面することになる。ある特定の
+Linux ディストリビューションの、ある特定のリリースバージョン用にモ
+ジュールを提供しようと思っただけでも、これらの問題を引き起こすには
+十分である。にも関わらず Linux ディストリビューションの数と、サ
+ポートするディストリビューションのリリース数を掛け算し、それら一つ
+一つについてビルドを行ったとしたら、今度はリリースごとのビルドオプ
+ションの違いという悪夢にすぐさま悩まされることになる。また、ディス
+トリビューションの各リリースバージョンには、異なるハードウェア（プ
+ロセッサタイプや種々のオプション）に対応するため、何種類かのカーネ
+ルが含まれているということも理解して欲しい。従って、ある一つのリ
+リースバージョンだけのためにモジュールを作成する場合でも、あなたは
+何バージョンものモジュールを用意しなければならない。
+
+
+信じて欲しい。このような方法でサポートを続けようとするなら、あなた
+はいずれ正気を失うだろう。遠い昔、私はそれがいかに困難なことか、身
+をもって学んだのだ・・・
+
+
+不変のカーネルソースレベルインターフェース
+------------------------------------------
+
+メインカーネルツリーに含まれていない Linux カーネルドライバを継続
+してサポートしていこうとしている人たちとの議論においては、これは極
+めて「引火性の高い」話題である。[訳注(2)]
+
+訳注(2)
+「引火性の高い」の原文は "volatile"。
+volatile には「揮発性の」「爆発しやすい」という意味の他、「変わり
+やすい」「移り気な」という意味がある。
+「（この話題は）爆発的に激しい論争を巻き起こしかねない」ということ
+を、「（カーネルのソースレベルインターフェースは）移ろい行くもので
+ある」ということを連想させる "volatile" という単語で表現している。
+
+
+Linux カーネルの開発は継続的に速いペースで行われ、決して歩みを緩め
+ることがない。その中でカーネル開発者達は、現状のインターフェースに
+あるバグを見つけ、より良い方法を考え出す。彼らはやがて、現状のイン
+ターフェースがより正しく動作するように修正を行う。その過程で関数の
+名前は変更されるかもしれず、構造体は大きく、または小さくなるかもし
+れず、関数の引数は検討しなおされるかもしれない。そのような場合、引
+き続き全てが正常に動作するよう、カーネル内でこれらのインターフェー
+スを使用している個所も全て同時に修正される。
+
+
+具体的な例として、カーネル内の USB インターフェースを挙げる。USB
+サブシステムはこれまでに少なくとも３回の書き直しが行われ、その結果
+インターフェースが変更された。これらの書き直しはいくつかの異なった
+問題を修正するために行われた。
+  - 同期的データストリームが非同期に変更された。これにより多数のド
+    ライバを単純化でき、全てのドライバのスループットが向上した。今
+    やほとんど全ての USB デバイスは、考えられる最高の速度で動作し
+    ている。
+  - USB ドライバが USB サブシステムのコアから行う、データパケット
+    用のメモリ確保方法が変更された。これに伴い、いくつもの文書化さ
+    れたデッドロック条件を回避するため、全ての USB ドライバはより
+    多くの情報を USB コアに提供しなければならないようになっている。
+
+
+このできごとは、数多く存在するクローズソースのオペレーティングシス
+テムとは全く対照的だ。それらは長期に渡り古い USB インターフェース
+をメンテナンスしなければならない。古いインターフェースが残ることで、
+新たな開発者が偶然古いインターフェースを使い、正しくない方法で開発
+を行ってしまう可能性が生じる。これによりシステムの安定性は危険にさ
+らされることになる。
+
+
+上に挙げたどちらの例においても、開発者達はその変更が重要かつ必要で
+あることに合意し、比較的楽にそれを実行した。もし Linux がソースレ
+ベルでインターフェースの不変性を保証しなければならないとしたら、新
+しいインターフェースを作ると同時に、古い、問題のある方を今後ともメ
+ンテナンスするという余計な仕事を USB の開発者にさせなければならな
+い。Linux の USB 開発者は、自分の時間を使って仕事をしている。よっ
+て、価値のない余計な仕事を報酬もなしに実行しろと言うことはできない。
+
+
+セキュリティ問題も、Linux にとっては非常に重要である。ひとたびセキ
+ュリティに関する問題が発見されれば、それは極めて短期間のうちに修正
+される。セキュリティ問題の発生を防ぐための修正は、カーネルの内部イ
+ンターフェースの変更を何度も引き起こしてきた。その際同時に、変更さ
+れたインターフェースを使用する全てのドライバもまた変更された。これ
+により問題が解消し、将来偶然に問題が再発してしまわないことが保証さ
+れる。もし内部インターフェースの変更が許されないとしたら、このよう
+にセキュリティ問題を修正し、将来再発しないことを保証することなど不
+可能なのだ。
+
+
+カーネルのインターフェースは時が経つにつれクリーンナップを受ける。
+誰も使っていないインターフェースは削除される。これにより、可能な限
+りカーネルが小さく保たれ、現役の全てのインターフェースが可能な限り
+テストされることを保証しているのだ。（使われていないインターフェー
+スの妥当性をテストすることは不可能と言っていいだろう）
+
+
+
+これから何をすべきか
+-----------------------
+
+では、もしメインのカーネルツリーに含まれない Linux カーネルドライ
+バがあったとして、あなたは、つまり開発者は何をするべきだろうか？全
+てのディストリビューションの全てのカーネルバージョン向けにバイナリ
+のドライバを供給することは悪夢であり、カーネルインターフェースの変
+更を追いかけ続けることもまた過酷な仕事だ。
+
+
+答えは簡単。そのドライバをメインのカーネルツリーに入れてしまえばよ
+い。（ここで言及しているのは、GPL に従って公開されるドライバのこと
+だということに注意してほしい。あなたのコードがそれに該当しないなら
+ば、さよなら。幸運を祈ります。ご自分で何とかしてください。Andrew
+と Linus からのコメント＜Andrew と Linus のコメントへのリンクをこ
+こに置く＞をどうぞ）ドライバがメインツリーに入れば、カーネルのイン
+ターフェースが変更された場合、変更を行った開発者によってドライバも
+修正されることになるだろう。あなたはほとんど労力を払うことなしに、
+常にビルド可能できちんと動作するドライバを手に入れることができる。
+
+
+ドライバをメインのカーネルツリーに入れると、非常に好ましい以下の効
+果がある。
+  - ドライバの品質が向上する一方で、（元の開発者にとっての）メンテ
+    ナンスコストは下がる。
+  - あなたのドライバに他の開発者が機能を追加してくれる。
+  - 誰かがあなたのドライバにあるバグを見つけ、修正してくれる。
+  - 誰かがあなたのドライバにある改善点を見つけてくれる。
+  - 外部インターフェースが変更されドライバの更新が必要になった場合、
+    誰かがあなたの代わりに更新してくれる。
+  - ドライバを入れてくれとディストロに頼まなくても、そのドライバは
+    全ての Linux ディストリビューションに自動的に含まれてリリース
+    される。
+
+
+Linux では、他のどのオペレーティングシステムよりも数多くのデバイス
+が「そのまま」使用できるようになった。また Linux は、どのオペレー
+ティングシステムよりも数多くのプロセッサアーキテクチャ上でそれらの
+デバイスを使用することができるようにもなった。このように、Linux の
+開発モデルは実証されており、今後も間違いなく正しい方向へと進んでい
+くだろう。:)
+
+
+
+------
+
+この文書の初期の草稿に対し、Randy Dunlap, Andrew Morton, David
+Brownell, Hanna Linder, Robert Love, Nishanth Aravamudan から査読
+と助言を頂きました。感謝申し上げます。
+

linux-7.2.3/Documentation/translations/ja_JP/stable_kernel_rules.txt

@@ -0,0 +1,84 @@
+NOTE:
+This is Japanese translated version of "Documentation/process/stable-kernel-rules.rst".
+This one is maintained by Tsugikazu Shibata <tshibata@ab.jp.nec.com>
+and JF Project team <www.linux.or.jp/JF>.
+If you find difference with original file or problem in translation,
+please contact maintainer of this file or JF project.
+
+Please also note that purpose of this file is easier to read for non
+English natives and do no intended to fork. So, if you have any
+comment or update of this file, please try to update Original(English)
+file at first.
+
+==================================
+これは、
+linux-2.6.29/Documentation/process/stable-kernel-rules.rst
+の和訳です。
+
+翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ >
+翻訳日： 2009/1/14
+翻訳者： Tsugikazu Shibata <tshibata at ab dot jp dot nec dot com>
+校正者： 武井伸光さん、<takei at webmasters dot gr dot jp>
+         かねこさん (Seiji Kaneko) <skaneko at a2 dot mbn dot or dot jp>
+         小林 雅典さん (Masanori Kobayasi) <zap03216 at nifty dot ne dot jp>
+         野口さん (Kenji Noguchi) <tokyo246 at gmail dot com>
+         神宮信太郎さん <jin at libjingu dot jp>
+==================================
+
+ずっと知りたかった Linux 2.6 -stable リリースの全て
+
+"-stable" ツリーにどのような種類のパッチが受け入れられるか、どのような
+ものが受け入れられないか、についての規則-
+
+ - 明らかに正しく、テストされているものでなければならない。
+ - 文脈(変更行の前後)を含めて 100 行より大きくてはいけない。
+ - ただ一個のことだけを修正しているべき。
+ - 皆を悩ませている本物のバグを修正しなければならない。("これはバグで
+   あるかもしれないが..." のようなものではない)
+ - ビルドエラー(CONFIG_BROKENになっているものを除く), oops, ハング、デー
+   タ破壊、現実のセキュリティ問題、その他 "ああ、これはダメだね"という
+   ようなものを修正しなければならない。短く言えば、重大な問題。
+ - 新しい device ID とクオークも受け入れられる。
+ - どのように競合状態が発生するかの説明も一緒に書かれていない限り、
+   "理論的には競合状態になる"ようなものは不可。
+ - いかなる些細な修正も含めることはできない。(スペルの修正、空白のクリー
+   ンアップなど)
+ - Documentation/process/submitting-patches.rst の規則に従ったものでなければならない。
+ - パッチ自体か同等の修正が Linus のツリーに既に存在しなければならない。
+　 Linus のツリーでのコミットID を -stable へのパッチ投稿の際に引用す
+   ること。
+
+-stable ツリーにパッチを送付する手続き-
+
+ - 上記の規則に従っているかを確認した後に、stable@vger.kernel.org にパッチ
+   を送る。
+ - 送信者はパッチがキューに受け付けられた際には ACK を、却下された場合
+   には NAK を受け取る。この反応は開発者たちのスケジュールによって、数
+   日かかる場合がある。
+ - もし受け取られたら、パッチは他の開発者たちと関連するサブシステムの
+   メンテナーによるレビューのために -stable キューに追加される。
+ - パッチに stable@vger.kernel.org のアドレスが付加されているときには、それ
+   が Linus のツリーに入る時に自動的に stable チームに email される。
+ - セキュリティパッチはこのエイリアス (stable@vger.kernel.org) に送られるべ
+   きではなく、代わりに security@kernel.org のアドレスに送られる。
+
+レビューサイクル-
+
+ - -stable メンテナがレビューサイクルを決めるとき、パッチはレビュー委
+   員会とパッチが影響する領域のメンテナ(提供者がその領域のメンテナで無
+   い限り)に送られ、linux-kernel メーリングリストにCCされる。
+ - レビュー委員会は 48時間の間に ACK か NAK を出す。
+ - もしパッチが委員会のメンバから却下されるか、メンテナ達やメンバが気付
+   かなかった問題が持ちあがり、linux-kernel メンバがパッチに異議を唱え
+   た場合には、パッチはキューから削除される。
+ - レビューサイクルの最後に、ACK を受けたパッチは最新の -stable リリー
+   スに追加され、その後に新しい -stable リリースが行われる。
+ - セキュリティパッチは、通常のレビューサイクルを通らず、セキュリティ
+   カーネルチームから直接 -stable ツリーに受け付けられる。
+   この手続きの詳細については kernel security チームに問い合わせること。
+
+レビュー委員会-
+
+ - この委員会は、このタスクについて活動する多くのボランティアと、少数の
+   非ボランティアのカーネル開発者達で構成されている。
+