第 19 章 コードの提供

目次
コードの提供にあたっての要求事項
コードの提供方法の実際
ドキュメントの書き方の実際

PEAR は、オープンソース 開発者のコミュニティーによって運営されています。 ですから、誰でも、本プロジェクトにコードを提供することができます。 それは、まったく新しいパッケージの作成でも、 既存のパッケージに対する改良であってもかまいません。 長い年月を経て、PEAR ではいくつかの約束事ができあがってきました。 中にはまだ発展途上のものもありますが、すでに確定しているものもあります。 このドキュメントでは、それらの決まりごとについて説明します。 PEAR に参加するには、これに従う必要があります。

コードの提供にあたっての要求事項

コード自体およびパッケージの作者に対して、 いくつかの要求事項があります。

  1. 標準コーディング規約への合致

    新しいパッケージの作成か、既存のパッケージへの付加かに係わらず、 PEAR にコードを提供する場合は、 標準コーディング規約 に合致している必要があります。 標準コーディング規約というものが良いものかどうかについては 多くの議論がありましたが、結局良いものであるという結論に達し、 議論を打ち切りました。みなさんもこの決定を尊重してくださるようお願いします。 基本的な標準コーディング規約を変更しないでください。 そんなことをしても誰にも見向きもされないでしょう。

    PHP_CodeSniffer を使用すると、PEAR 標準コーディング規約に準拠しているかどうかを簡単に確かめることができます。

  2. 適切なライセンス

    各パッケージのライセンスは、認められているオープンソースライセンスの いずれかでなければなりません。ライセンスについてよくわからない場合は 修正 BSD ライセンス を選択しましょう。PEAR Group では ライセンスに関するお知らせ を公開しており、この件についての詳細を説明しています。

  3. 公開されているリポジトリからコードが取得できること

    パッケージの最新版のソースコードが、公開されている SCM (Source Code Management: ソースコード管理) システムから取得できなければなりません。そのようなシステムには、 例えば cvs.php.net にある CVS サーバ、Google Code の Subversion リポジトリや SourceForge のサイトなどがあります。 Google Code や SourceForge は、利用規約に従う限りは自由に使用できます。 cvs.php.net への書き込みアクセス権は、そのパッケージが PEAR パッケージとして承認されてから与えられます。

    すべてのパッケージは、公開されているソースリポジトリがなければなりません。 これにより、最新のコードにアクセスしたり バグ修正や新機能のパッチを提供したりできることになります。

  4. 拡張可能で、"前方互換な" コード

    コードは、 拡張が可能で、新しい機能を将来に容易に追加できるものであるべきだ、 と言うことを常に意識に留めておいてください。 現在のコードとの後方互換性を破壊すること無しに 機能を拡張することが容易でないとしたら、 そのパッケージを PEAR へ投稿する前に、 より良い設計と実装について考えてみるべきです。

    この目標を達成するため、ほとんどの PEAR パッケージは オブジェクト指向プログラミングを使用しています。 継承、多態性、(シングルトン/ファクトリ/コマンドといった) パターンを使用することで、PEAR パッケージは より洗練された方法で問題を解決できるようになります。 オブジェクト指向プログラミングについては、 WEB 上にたいへん多くのリソースがありますし、 読書の楽しみを満たしてくれる多くの本も見つけられるでしょう。 お勧めとしては、 サンによる JAVA のホームページ で読むことのできる「 オブジェクト指向プログラミングの概念 (Object-Oriented Programming Concepts) 」 があります。

  5. 適切な形式でのドキュメント (プレインテキスト、docbook)

    コードには、次の形式の内のいずれかの適切なドキュメントが付属している 必要 があります。

    ドキュメントを Docbook XML で書き、マークアップが適切なら、 そのドキュメントは、あなたが今読まれている 公式 PEAR マニュアル に 簡単に付け加えることが出来ます。

    注意 2003年8月以降、 phpDocumentor は、 コード中に書かれた API のドキュメントや 外部チュートリアル文書を、 PEAR で使用する XML DocBookに変換すること出来ます。 PhpDocumentor バージョン 1.2.2以降が必要です。 PhpDocumentor をインストールするには、 pear install phpDocumentor とします。 ソースコードから DocBook 出力を作成するには XML:DocBook/peardoc2:default コンバータを使ってください。 出力は、直接peardoc/lang/package ディレクトリ(ここで lang は en や fr 等)に生成されます。

    注意して欲しいのは、API ドキュメントだけでは十分ではないということです。 使用例や使用方法についてのチュートリアルも必要です。 ドキュメントの書き方 についての章に、さらに情報があります。

  6. .phpt もしくは PHPUnit 形式による回帰テスト

    バグによるフラストレーションを経験していない開発者はいません。 それはプログラミングにおける紛れも無い真実ですが、 幸運にも、バグを捕まえ消滅させ復活を防ぐためのシステムが存在します。 すなわち、回帰テストをすべての安定版リリースに含めるべきです。 というのも、 もしバグが発生した場合に、パッケージのデバグの助けとなるよう、 ユーザ自身が回帰テストを実行できるようにするためです。 .phpt 形式の回帰テストの例としては、CVS の PEAR パッケージがあります。 PHPUnit のテストの例としては、 Auth パッケージを ご覧ください。

  7. 提供者(つまり"あなた")は、 パッケージのサポートを行っていく意思があり、 ほんの少しのバグ修正でも次バージョンを リリースすることを厭わない

    もし長期にわたるメンテナンスを行うつもりが無ければ、 コードを提供しても意義はほとんどありません。 PEAR は、PHP のパッケージの標準リポジトリであって、多くの責任が伴います。 メンテナンスとは、 メーリングリスト においてサポートを提供する以上のことを意味します。

    バグ修正を行うだけでなく、パッケージの設計スペックにあうならば、 ユーザからパッケージに対して提案・提供された有用な拡張を 取り入れることも必要です。 また、バグ修正が行われた新バージョンを 定期的にリリースすることも期待されます。 もし、パッケージのメンテナンスが長期間に渡って出来なくなる場合には、 PEAR 開発者メーリングリストにアナウンスし、 別の仮リードメンテナを任命するか、 パッケージが一時的にメンテナンスされない旨を皆に文書で知らせるかして、 さらに可能ならば、サポートとバグ修正を再び開始する大まかな時期についても 知らせることが求められます。

    警告

    リードメンテナが以後メンテナンスする意思がなく、 リードメンテナを引き継ぐ人もいない場合は、 コードが PEAR から削除されることがあります。