コードの提供にあたっての要求事項
コード自体およびパッケージの作者に対して、
いくつかの要求事項があります。
-
標準コーディング規約への合致
新しいパッケージの作成か、既存のパッケージへの付加かに係わらず、
PEAR にコードを提供する場合は、
標準コーディング規約
に合致している必要があります。
標準コーディング規約というものが良いものかどうかについては
多くの議論がありましたが、結局良いものであるという結論に達し、
議論を打ち切りました。みなさんもこの決定を尊重してくださるようお願いします。
基本的な標準コーディング規約を変更しないでください。
そんなことをしても誰にも見向きもされないでしょう。
PHP_CodeSniffer
を使用すると、PEAR 標準コーディング規約に準拠しているかどうかを簡単に確かめることができます。
-
適切なライセンス
各パッケージのライセンスは、認められているオープンソースライセンスの
いずれかでなければなりません。ライセンスについてよくわからない場合は
修正 BSD ライセンス
を選択しましょう。PEAR Group では
ライセンスに関するお知らせ
を公開しており、この件についての詳細を説明しています。
-
公開されているリポジトリからコードが取得できること
パッケージの最新版のソースコードが、公開されている
SCM (Source
Code Management: ソースコード管理)
システムから取得できなければなりません。そのようなシステムには、
たとえば svn.php.net にある
SVN サーバ、
Google Code
の Subversion リポジトリや SourceForge のサイトなどがあります。
Google Code や SourceForge は、利用規約に従う限りは自由に使用できます。
svn.php.net への書き込みアクセス権は、そのパッケージが
PEAR パッケージとして承認されてから与えられます。
すべてのパッケージは、公開されているソースリポジトリがなければなりません。
これにより、最新のコードにアクセスしたり
バグ修正や新機能のパッチを提供したりできることになります。
-
拡張可能で、"前方互換な" コード
コードは、
拡張が可能で、新しい機能を将来に容易に追加できるものであるべきだ、
と言うことを常に意識に留めておいてください。
現在のコードとの後方互換性を破壊すること無しに
機能を拡張することが容易でないとしたら、
そのパッケージを PEAR へ投稿する前に、
より良い設計と実装について考えてみるべきです。
この目標を達成するため、ほとんどの PEAR パッケージは
オブジェクト指向プログラミングを使用しています。
継承、多態性、(シングルトン/ファクトリ/コマンドといった)
パターンを使用することで、PEAR パッケージは
より洗練された方法で問題を解決できるようになります。
オブジェクト指向プログラミングについては、
WEB 上にたいへん多くのリソースがありますし、
読書の楽しみを満たしてくれる多くの本も見つけられるでしょう。
お勧めとしては、
サンによる JAVA のホームページ
で読むことのできる「
オブジェクト指向プログラミングの概念
(Object-Oriented Programming Concepts)
」
があります。
-
適切な形式でのドキュメント (プレインテキスト、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 ドキュメントだけでは十分ではないということです。
使用例や使用方法についてのチュートリアルも必要です。
ドキュメントの書き方
についての章に、さらに情報があります。
-
.phpt もしくは
PHPUnit
形式による回帰テスト
バグによるフラストレーションを経験していない開発者はいません。
それはプログラミングにおける紛れも無い真実ですが、
幸運にも、バグを捕まえ消滅させ復活を防ぐためのシステムが存在します。
すなわち、回帰テストをすべての安定版リリースに含めるべきです。
というのも、
もしバグが発生した場合に、パッケージのデバグの助けとなるよう、
ユーザ自身が回帰テストを実行できるようにするためです。
.phpt 形式の回帰テストの例としては、SVN の
PEAR
パッケージがあります。
PHPUnit のテストの例としては、
Auth パッケージを
ご覧ください。
-
提供者(つまり"あなた")は、
パッケージのサポートを行っていく意思があり、
ほんの少しのバグ修正でも次バージョンを
リリースすることを厭わない
もし長期にわたるメンテナンスを行うつもりが無ければ、
コードを提供しても意義はほとんどありません。
PEAR は、PHP のパッケージの標準リポジトリであって、多くの責任が伴います。
メンテナンスとは、
メーリングリスト
においてサポートを提供する以上のことを意味します。
バグ修正を行うだけでなく、パッケージの設計スペックにあうならば、
ユーザからパッケージに対して提案・提供された有用な拡張を
取り入れることも必要です。
また、バグ修正が行われた新バージョンを
定期的にリリースすることも期待されます。
もし、パッケージのメンテナンスが長期間に渡って出来なくなる場合には、
PEAR 開発者メーリングリストにアナウンスし、
別の仮リードメンテナを任命するか、
パッケージが一時的にメンテナンスされない旨を皆に文書で知らせるかして、
さらに可能ならば、サポートとバグ修正を再び開始する大まかな時期についても
知らせることが求められます。
リードメンテナが以後メンテナンスする意思がなく、
リードメンテナを引き継ぐ人もいない場合は、
コードが PEAR から削除されることがあります。