第 15 章 コードの提供

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

PEAR は、オープンソース 志向の開発者コミュニティーによって運営されています。 ですから、誰でも、本プロジェクトにコードを提供することができます。 それは、まったく新しいパッケージの作成でも、 既存のパッケージに対する改良であってもかまいません。 PEAR ではさらに、パッケージの品質を非常に高いレベルに保持することも目標としています。 そのため、コードの提供にあたっては、次に示す要求事項があります。

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

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

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

    新しいパッケージの作成か、既存のパッケージへの付加かに係わらず、 PEAR にコードを提供する場合は、 標準コーディング規約 に合致している必要があります。 標準コーディング規約というものが良いものかどうかについては 多くの議論がありましたが、絶対に必要なものであるとの決定に達しました。 さらに議論する意義はありません。

  2. 適切なライセンス

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

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

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

    この条件を指定する理由は、利用者や PEAR 開発者たちが 最新の (おそらくまだリリースされていない) コードにアクセスできる必要があることです。 それにより、バグの調査やパッチの提供が可能となります。

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

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

    それに関連しては、 オブジェクト指向プログラミングの基礎をよく理解することが有用でしょう。 PHP は、完全なオブジェクト指向のサポートには至っていませんが、 その知識はパッケージのコードを将来の拡張が可能な状態に保つ助けとなるでしょう。 オブジェクト指向プログラミングについては、 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 形式の回帰テストの例としては、 PFC DB パッケージがあります。 PHPUnit のテストの例としては、 Auth パッケージを ご覧ください。

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

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

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

    警告

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

レンタルサーバー

SNS