cvs: peardoc /ja/guide/developers contributing.xml

elf Fri Oct 31 06:20:11 2003 EDT Modified files: /peardoc/ja/guide/developers contributing.xml Log: o more transration. thanks haruki.

Index: peardoc/ja/guide/developers/contributing.xml diff -u peardoc/ja/guide/developers/contributing.xml:1.1 peardoc/ja/guide/developers/contributing.xml:1.2 --- peardoc/ja/guide/developers/contributing.xml:1.1 Mon Oct 27 09:01:05 2003 +++ peardoc/ja/guide/developers/contributing.xml Fri Oct 31 06:20:11 2003 @@ -1,461 +1,509 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!-- $Revision: 1.1 $ --> -<!-- Sync: 1.15 --> -<!-- - WORK IN PROGRESS, THERE IS PROBABLY LITTLE POINT IN TRANSLATING - THIS DOCUMENT YET. - --> - <chapter id="developers.contributing"> - <title>自分のコードの寄与</title> - <titleabbrev>Contributing</titleabbrev> - - <para> - PEAR is driven by a <ulink url="http://www.opensource.org/">open - source</ulink> oriented developer community. Thus there is a chance - for everybody to contribute code (in form of a new package or as an - improvement for an existing package) to the project. However PEAR - aims to keep the quality of the packages at a very high - level. Because of that there are certain requirements for - contributions, which are listed below. - </para> - - <sect1 id="developers.contributing.requirements"> - <title>コードを寄与するための必要条件</title> - <titleabbrev>Requirements</titleabbrev> - - <simpara> - There are certain requirements both for the code and for the author of a - package in PEAR: - </simpara> - - <para> - <orderedlist> - <listitem> - <simpara> - コーディング標準に一致すること - </simpara> - <para> - If you want to contribute your code to PEAR in form of a new - package or as an addition to an existing package, it has to be - compliant to a set of <link linkend="standards">coding - standards</link>. There have been numerous discussions about - whether the coding standards are good or not and the decision has - been made that they are absolutely necessary. There is no sense - in discussing about this. - </para> - </listitem> - - <listitem> - <simpara> - 拡張可能で、 <quote>過去への互換性をもつ</quote> コード - </simpara> - <para> - Always keep in mind that your code should be extensible and that - it has to be easy to add new features in the future. If there is no - easy way to extend the functionality of your code without breaking backwards - compatibility with existing code, you should consider implementing a - better design before proposing the package for inclusion in PEAR. - </para> - <para> - It may be helpful in this context to become familiar with the - basic of object oriented programming. Eventhough PHP does not - come with full object oriented support yet, the knowledge will - possibly help you in maintaining a extensible state for your - package code. There are numerous resources about object oriented - programming all around the web and you will also find tons of - books available for your reading pleasure. However we can can - recommend <ulink url="&url.java.oo;">Object-Oriented Programming - Concepts</ulink> over there on <ulink url="&url.java;">Sun's Java - Homepage</ulink>. - </para> - - </listitem> - - <listitem> - <simpara> - 適切なフォーマットでのドキュメント (プレインテキスト, docbook) - </simpara> - <para> - Your code <emphasis>must</emphasis> come with appropriate documentation in one of - the following formats: - <itemizedlist> - <listitem> - <simpara> - <ulink url="&url.docbook.book;">Docbook XML</ulink> - </simpara> - </listitem> - <listitem> - <simpara> - Plain Text - </simpara> - </listitem> - </itemizedlist> - - If you write the documentation in Docbook XML and if the markup - is valid, the documentation can be easily added to the official - <ulink url="&url.pear.manual;">PEAR Manual</ulink>, - which you are reading right now. - </para> - - <note> - <para> - As of August 2003, <ulink url="&url.phpdocumentor;">phpDocumentor</ulink> - is fully capable of converting in-code API documentation and external - tutorials into XML DocBook for use with PEAR. - PhpDocumentor version 1.2.2 or greater is required. Install with - <literal>pear install phpDocumentor</literal>. Use the - XML:DocBook/peardoc2:default converter on your source code to generate - output. The output should be generated directly into the - <literal>peardoc/lang/package</literal> directory, where lang is en, - or fr, etc. - </para> - <para> - Be aware though that only shipping the API documentation does - not suffice! Additionally your package has to come with usage - examples and (even better) tutorials about its usage. More - information can be found in the section describing - <link linkend="developers.contributing.docs">how to write documentation</link> - </para> - </note> - </listitem> - - <listitem> - <simpara> - Regression tests in .phpt or <link linkend="package.php.phpunit">PHPUnit</link> - format - </simpara> - <para> - All developers have experienced the frustration of bugs. They are a fact - of life in programming, but fortunately there are a few systems that can - be used to catch them, kill them, and prevent their return. Regression - tests should be included with every stable release, so that users can - run them if a bug occurs to help you debug the package. Examples of - .phpt regression tests can be found as part of the PFC - <link linkend="package.database.db">DB</link> package. For examples of - PHPUnit tests, see the <link linkend="package.authentication.auth">Auth</link> - package. - </para> - </listitem> - - <listitem> - <simpara> - The contributor (<quote>you</quote>) must be willing to provide support - for the package and must be willing to release future versions that at - the very least fix bugs. - </simpara> - <simpara> - If you are not willing to maintain your code over a long period - of time, it makes little sense to contribute it. PEAR is the - standard repository of PHP packages, and this comes with great - responsibility. Maintaining means more than just providing - support via the various <ulink url="&url.pear.support;">mailing - lists</ulink>: - </simpara> - <simpara> - You must be willing to not only fix bugs, but also integrate useful - enhancements contributed by users of your packages, if they fit the - design specifications of your package. You should expect to release - new versions of your package regularly with bug fixes. If you will be - unable to maintain your package for an extended period of time, it is - expected that you will announce this to the PEAR developer mailing list, - and assign another temporary lead maintainer or publicly document the fact - that your package is temporarily unmaintained, and the approximate date - that users can expect to receive support and bug fixes, if possible. - </simpara> - <warning> - <simpara> - Code can be removed from PEAR if the lead maintainers - are not willing to maintain the code anymore and if there - is no other person that is willing to take over the - maintainership. - </simpara> - </warning> - </listitem> - </orderedlist> - </para> - - </sect1> - - <sect1 id="developers.contributing.howto"> - <title>実際にコードを寄与する方法</title> - <titleabbrev>コードの寄与方法</titleabbrev> - <para> - <orderedlist> - <listitem> - <simpara>Finding an appropriate package name</simpara> - <simpara> - One of the most important tasks while contributing a new package - to PEAR is finding an appropriate name for your package. - </simpara> - <para> - The general syntax for package names is - <literal>&lt;Category&gt;_&lt;Name&gt;</literal>. The value for - <literal>&lt;Category&gt;</literal> should be chosen from a - predefined list of categories that are available in PEAR (e.g. - <quote>HTTP</quote>, <quote>Net</quote>, <quote>HTML</quote>). - The second part is the name of the package (like - <quote>Upload</quote>, <quote>Portscan</quote>, <quote>Table</quote>). - </para> - - <para> - The categories that are currently available in PEAR are - represented by the bold headings at the - <ulink url="&url.pear.package.browse;">Package - Browser</ulink>. If you think that your package does not fit in - any of the existing categories, you can ask the on the mailing - list to create a new category. (PEAR is usually reluctant to do - that.) - </para> - - <para> - Apart from this general syntax, the package names can also contain - more than one category name. An example for this is - <literal>HTML_Template_PHPLIB</literal>: The multiple categories indicate - that the package <literal>PHPLIB</literal> is part of the category - <literal>Template</literal>, that again is part of the <literal>HTML</literal> - category. This naming scheme is necessary here since it's possible - that there are Template systems in PEAR that don't work with HTML but - with another technology. (The cases where more than one - <quote>category</quote> is used are pretty rare.) - </para> - - <para> - If you need further advice or help for finding a name for your - package, you should ask on the <ulink url="mailto:&email.pear.dev;"> - developers mailing list</ulink>. - </para> - - </listitem> - <listitem> - <simpara>PEAR 開発者への発表</simpara> - - <para> - The second step while contributing is to announce your package on - the <ulink url="mailto:&email.pear.dev;">developers mailing list</ulink>. - Usually this announcement will spawn some discussion and the - developers will then start to vote for or against your proposal. - (You are of course urged to join the upcoming discussion.) - Announcing a package does of course not mean that it is already - accepted! That will still take some time and likely some more - efforts from your side. - </para> - <note> - <para> - The following passages are taken from the administrative - document <ulink - url="http://pear.php.net/group/docs/20030904-pph.php">Handling - Package Proposals</ulink>, which describes proposing new - packages in more details. Reading this document should be a - mandatory step for PEAR newbies. - </para> - </note> - - <para> - Only the votes of active members of the PEAR community (must have - a PEAR web account, however the proposer himself is not counted) - are counted, however anyone may vote. Votes require that a final - choiceof package name is specified. - </para> - <para> - The votes are added up, which means that one -1 offsets a - +1. However -1 vote should always be considered to be serious and - may lead to decisions being made on a case by case basis by the - <ulink url="&url.pear.group;">PEAR Group</ulink> who reserves a - veto (it is intended that in the future the PEAR QA team will - assist the PEAR Group in such situations). Therefore a -1 vote - *must* contain a comment explaining that decision, it is - desirable that votes in favour (+1) should also be accompanied - with an explanation when appropriate. - </para> - - <para> - A vote is accepted if the total of all votes exceeds +5. - </para> - - <para> - In case the proposal is not accepted the package can be further - discussed on the list and the proposer may attempt to make - another "call for vote" (it is expected that this is only done - for sensible reasons). - </para> - </listitem> - - <listitem id="developers.contributing.accounts"> - <simpara> - 必要なアカウントの取得 - </simpara> - - <para> - Right now one can distinguish between two types of accounts - related to PEAR: - - <orderedlist> - <listitem> - <simpara>Pear.php.net アカウント</simpara> - - <para> - This account is always necessary for you, if you want to release - your package through PEAR. With this account you have access - to the necessary infrastructure on - <ulink url="&url.pear;">pear.php.net</ulink> in order - to upload and roll new releases.</para> - </listitem> - - <listitem> - <simpara>PHP CVS アカウント</simpara> - - <para> - If you want to administrate your code via - <ulink url="&url.cvs;">CVS</ulink> , you can also - apply for a CVS account to have access to the pear - <abbrev>CVS</abbrev> module on <ulink url="&url.php.cvs;"> - cvs.php.net</ulink>. This makes it easier for other users - to contribute to your code. - </para> - - <para> - If you already have a CVS repository somewhere else (e.g. on - <ulink url="&url.sourceforge;">SourceForge</ulink>), - or if you don't want to maintain your code via CVS, you don't - need the PHP CVS account. It is highly recommended to use some kind - of public repository, so that users can try out any - bug fixes you apply to the code, before a new release is - rolled. - </para> - </listitem> - </orderedlist> - </para> - <para> - To sign up for your pear.php.net account, go to the - <ulink url="&url.pear.account.new;">PEAR account - request page</ulink> and fill out the form there. The <ulink - url="&url.pear.group;">PEAR Group</ulink> will then receive your - request and someone will open your account, if the request sounds - reasonable. You will be notified about that via email. Please - note that you do NOT need a pear.php.net account to download - packages from there. - </para> - <para> - To get a PHP CVS account, go - <ulink url="&url.php.cvs.new;">here</ulink> to sign - up for it. The PHP CVS account has to be approved by the PHP - Group. - </para> - </listitem> - <listitem> - <simpara>パッケージの登録</simpara> - <simpara> - Once you successfully went through the contribution procedure and - got your pear.php.net account, you finish with registering your - package. Registering does not mean that you are going to release - a first version of your package. It just means that some basic - information about the package will be added to the PEAR package - database. - </simpara> - - <para> - The registration process is quite straightforward: Fill out the - form on <ulink url="&url.pear.package.new;">this site</ulink> and - submit the information. After you have done that, the <ulink - url="&url.pear.group;">PEAR Group</ulink> has to finally approve - your submission. This usually happens in a few hours and you will - be notified about it via email. - </para> - <para> - After having registered your package, you can create a first - release, which is described <link - linkend="developers.release">here</link>. - </para> - </listitem> - </orderedlist> - </para> - </sect1> - <sect1 id="developers.contributing.docs"> - <title>How to document code in practice</title> - <titleabbrev>ドキュメント方法</titleabbrev> - <para> - This section of the manual does not deal with the specifics of organizing - documentation in the peardoc standard, but instead with how to organize - documentation logically. To learn about authoring documentation files in - peardoc format, please look in PHP's CVS - <ulink url="&url.php.cvs.peardoc.authoring;">here</ulink>. - </para> - <para> - Follow a few basic rules when documenting a package, and you will have - good documentation. - </para> - <para> - <orderedlist> - <listitem> - <para> - First, every package solves a problem. What is this problem? Try to - figure out what assumptions your end-users might not have about the - problem (they may not realize that this is a problem that needs solving). - For instance, a template package solves the problem of both separating - design from code, and separating business logic from display logic. - If possible, explain the problem in terms that even a beginning programmer - could understand. - </para> - </listitem> - <listitem> - <para> - Next, how does the package uniquely solve the problem? This is something that most - documentation lacks. For example, there are many template engines. All of them - solve the same problem, but none of them do it in the same way. A - block-based template engine does not have any logic at all, whereas - a template like Smarty defines a whole new template language. Some - template engines compile their templates, others don't. What is unique - about your package? Can someone who has never seen the code get a good - idea of how it solves the problem? - </para> - </listitem> - <listitem> - <para> - Last, every publicly accessible aspect of the package must be - thoroughly documented. If your package is a re-usable class, document - every method that users should expect to use. If your package has - constants that are publicly accessible, document their meaning and where - they should be used. Document any interfaces that users must use, such - as a database DSN, command-line arguments for applications, configuration - file contents, or any other non-code element. - </para> - </listitem> - <listitem> - <para> - Include at least 2 code examples: one simple and one complex. This is - obvious, but PEAR packages are designed to be used: show your users how - to use them! :) - </para> - </listitem> - <listitem> - <para> - Last, proofread your documentation. If possible, have someone else who is - not as familiar with your project take a look at the documentation. They - will catch assumptions that you have missed. This is probably the most - important step of all. - </para> - </listitem> - </orderedlist> - </para> - </sect1> - </chapter> - -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-omittag:t -sgml-shorttag:t -sgml-minimize-attributes:nil -sgml-always-quote-attributes:t -sgml-indent-step:1 -sgml-indent-data:t -sgml-parent-document:nil -sgml-default-dtd-file:"../../../manual.ced" -sgml-exposed-tags:nil -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -End: -vim600: syn=xml fen fdm=syntax fdl=2 si -vim: et tw=78 syn=sgml -vi: ts=1 sw=1 ---> +<?xml version="1.0" encoding="utf-8" ?> +<!-- $Revision: 1.2 $ --> +<!-- Sync: 1.15 --> +<!-- + WORK IN PROGRESS, THERE IS PROBABLY LITTLE POINT IN TRANSLATING + THIS DOCUMENT YET. + --> + <chapter id="developers.contributing"> + <title>コードの寄与</title> + <titleabbrev>Contributing</titleabbrev> + + <para> + PEARは、<ulink url="http://www.opensource.org/">open source</ulink>志向の + 開発者コミュニティーによって運営されています。 + したがって、誰でも、本PEARプロジェクトに + （新しいパッケージの作成でも、既存のパッケージに対する改良であっても、） + コードを寄与する機会があります。 + しかしながら、 + PEARは、パッケージの品質を非常に高いレベルに保つことも目標としています。 + そのため、コードの寄与には、以下に示す要求事項があります。 + </para> + + <sect1 id="developers.contributing.requirements"> + <title>コードを寄与するための要求事項</title> + <titleabbrev>要求事項</titleabbrev> + + <simpara> + コード自体およびパッケージ著者の双方に対して、 + PEARではいくつかの要求事項があります。 + </simpara> + + <para> + <orderedlist> + <listitem> + <simpara> + コーディング標準への合致 + </simpara> + <para> + 新しいパッケージの作成か、既存のパッケージへの付加かに係わらず、 + PEARにコードを寄与する場合は、 + <link linkend="standards">コーディング標準</link> + に合致している必要があります。 + コーディング標準というものが良いものかどうかについては + 多くの議論がありましたが、 + 絶対に必要なものであるとの決定に達しました。 + さらに議論しても意義はありません。 + </para> + </listitem> + + <listitem> + <simpara> + 拡張可能で、<quote>前方互換な</quote> コード + </simpara> + <para> + コードは、 + 拡張可能で将来に新しい機能を容易に追加できるものであるべき、 + と言うことを、常に意識に留めておいてください。 + 現在のコードとの後方互換性を破壊することなしに + 機能の拡張が容易でない場合は、より良い設計の実装を、 + パッケージをPEARへ投稿する前に考えてみるべきです。 + </para> + <para> + それに関連しては、 + オブジェクト指向プログラミングの基礎をよく理解することが有用でしょう。 + PHPは完全なオブジェクト指向のサポートには至っていませんが、 + その知識はあなたのパッケージのコードを + 拡張可能な状態に保つ助けとなるでしょう。 + オブジェクト指向プログラミングについては、 + WEB上にたいへん多くのリソースがありますし、 + 読書の楽しみを満たすような多くの本も見つけられるでしょう。 + ただしお勧めは、 + サンによる<ulink url="&url.java;">JAVAのホームページ</ulink> + に記載された + <ulink url="&url.java.oo;"> + オブジェクト指向プログラミングの概念 + （Object-Oriented Programming Concepts） + </ulink> + を読んでみることです。 + </para> + + </listitem> + + <listitem> + <simpara> + 適切な形式でのドキュメント (プレインテキスト, docbook) + </simpara> + <para> + コードには、 + 適切なドキュメントが次の形式のうちのいずれかで付属している + <emphasis>必要</emphasis>があります。 + <itemizedlist> + <listitem> + <simpara> + <ulink url="&url.docbook.book;">Docbook XML</ulink> + </simpara> + </listitem> + <listitem> + <simpara> + プレインテキスト + </simpara> + </listitem> + </itemizedlist> + + ドキュメントをDocbook XMLで書き、マークアップが適切なら、 + そのドキュメントは、あなたが今読まれている + 公式<ulink url="&url.pear.manual;">PEARマニュアルl</ulink>に + 簡単に付け加えることが出来ます。 + </para> + + <note> + <para> + 2003年8月以降、 + <ulink url="&url.phpdocumentor;">phpDocumentor</ulink>は、 + コード中に書かれたAPIのドキュメントや + 外部チュートリアル文書を、 + PEARで使用するXML DocBookに変換すること出来ます。 + PhpDocumentor バージョン 1.2.2以降が必要です。 + インストールは、 + <literal>pear install phpDocumentor</literal>としてください。 + ソースコードから出力を作成するには + XML:DocBook/peardoc2:defaultコンバータを使ってください。 + 出力は、言語はenやfrなどで、 + 直接<literal>peardoc/lang/package</literal>ディレクトリに生成されます。 + </para> + <para> + 注意して欲しいのは、APIドキュメントだけでは十分ではないことです。 + 加えて、使用例や使用法についてのチュートリアルが必要です。 + <link + linkend="developers.contributing.docs">ドキュメントの書き方</link> + についての章に、さらに情報があります。 + </para> + </note> + </listitem> + + <listitem> + <simpara> + .phptもしくは + <link linkend="package.php.phpunit">PHPUnit</link> + 形式による回帰テスト + </simpara> + <para> + バグによるフラストレーションを経験していない開発者はいません。 + それはプログラミングにおける紛れも無い真実ですが、 + 幸運にも、バグを捕まえ消滅させ復活を防ぐためのシステムが存在します。 + 回帰テストを、すべての安定版リリースに含めるべきです。 + というのも、 + もしバグが発生した場合に、パッケージのデバグを助けるために + ユーザがそれを実行できるようにするためです。 + .phpt形式の回帰テストの例として、 + PFC <link linkend="package.database.db">DB</link>パッケージがあります。 + PHPUnitのテストの例としては、 + <link linkend="package.authentication.auth">Auth</link>を + ご覧ください。 + </para> + </listitem> + + <listitem> + <simpara> + 寄与者（つまり<quote>あなた</quote>）は、 + パッケージのサポートを行う意思があり、 + ほんの少しのバグ修正でも次のバージョンをリリースすることを厭わないこと。 + </simpara> + <simpara> + もし長期にわたってのコードのメンテナンスを行うつもりが無ければ、 + 寄与しても意義はほとんどありません。 + PEARは、 + PHPパッケージの標準リポジトリであって、多くの責任が伴います。 + メンテナンスは、いくつかある + <ulink url="&url.pear.support;">メーリングリスト</ulink> + でサポートを提供する以上のことを意味します。 + </simpara> + <simpara> + バグ修正だけでなく、パッケージの設計スペックにあうならば、 + ユーザからパッケージに対して寄与された有用な拡張を取り入れることが必要です。 + 定期的に、 + バグ修正されたパッケージの新バージョンをリリースすることも期待されます。 + もし長期間に渡ってパッケージのメンテナンスが出来なくなった場合には、 + PEAR開発者メーリングリストにアナウンスし、 + 別の仮リードメンテナを任命するか、 + パッケージが一時的にメンテナンスされない旨を皆に文書で知らせるかして、 + 可能ならば、 + サポートとバグ修正を再び提供する大まかな時期も知らせることが求められます。 + </simpara> + <warning> + <simpara> + リードメンテナが以後メンテナンスする意思がなく、 + リードメンテナを引き継ぐ人もいない場合は、 + コードがPEARから削除されることがあります。 + </simpara> + </warning> + </listitem> + </orderedlist> + </para> + + </sect1> + + <sect1 id="developers.contributing.howto"> + <title>寄与方法の実際</title> + <titleabbrev>寄与方法</titleabbrev> + <para> + <orderedlist> + <listitem> + <simpara>適切なパッケージ名称の命名</simpara> + <simpara> + 新パッケージをPEARに寄与するにあたっての最重要な務めの内の１つは、 + パッケージに適切な名称をつけることです。 + </simpara> + <para> + パッケージ名の全体の構文は、 + <literal>&lt;カテゴリ&gt;_&lt;名前&gt;</literal> + となります。 + <literal>&lt;カテゴリ&gt;</literal>は、 + PEARにあるカテゴリの既定義のリストから選ぶべきです + （例、<quote>HTTP</quote>, + <quote>Net</quote>, <quote>HTML</quote>）。 + 2番目の部分は、パッケージの名前です + （例、<quote>Upload</quote>, <quote>Portscan</quote>, <quote>Table</quote>）。 + </para> + + <para> + PEARで現在利用可能なカテゴリは、 + <ulink + url="&url.pear.package.browse;">パッケージブラウザ</ulink> + で太字で表示されています。 + もし、パッケージが既存のカテゴリに当てはまらない場合は、 + メーリングリストで新カテゴリの作成を依頼することが可能です。 + （PEARとしては、 + 新カテゴリの作成は、あまり行いたくは無いですけれども。） + </para> + + <para> + 上記の構文とは異なりますが、パッケージ名は、 + 複数のカテゴリ名を含むこともできます。 + 例えば、<literal>HTML_Template_PHPLIB</literal>を挙げると、 + その複数カテゴリは、パッケージ<literal>PHPLIB</literal>が、 + <literal>Template</literal>カテゴリに含まれ、 + さらに<literal>HTML</literal>カテゴリにも含まれることを示します。 + この命名の仕組みは、 + HTMLで動作しないが他の技術では動作するようなテンプレートシステムが + PEARに存在することが出来るようにするために必要となっています。 + （複数の<quote>category</quote>が使われる場合はたいへん稀ですが。） + </para> + + <para> + パッケージ名をつけるにあたって、さらに助言や助けが必要な場合は、 + <ulink url="mailto:&email.pear.dev;">開発者メーリングリスト</ulink> + で質問してください。 + </para> + + </listitem> + <listitem> + <simpara>PEAR開発者への提案</simpara> + + <para> + 寄与に当たっての第２のステップは、 + <ulink url="mailto:&email.pear.dev;">開発者メーリングリスト</ulink> + でパッケージを提案することです。 + 通常、いくつかの論議が行われ、 + 開発者たちは、あなたの提案に対して投票を始めます。 + （もちろん、あなたもその来るべき論議に加わることが求められます。） + 当然、パッケージの提案が、その許諾を意味するのではありません。 + さらに幾分かの時間がかかり、さらなる努力も要するかも知れません。 + </para> + <note> + <para> + 続く推移は、行政文書 + 「<ulink + url="http://pear.php.net/group/docs/20030904-pph.php">パッケージ提案の扱い</ulink>」 + に従っています。 + そこに、新しいパッケージの投稿について詳しく述べられています。 + PEAR初心者の方は、この書類を読むことは必須でしょう。 + </para> + </note> + + <para> + 投票は誰でも出来ますが、 + PEARコミュニティーの（提案者以外の、PEARのWEBアカウントを持つ） + アクティブメンバーの投票だけがカウントされます。 + 投票に際しては、 + 最終的に選択したパッケージ名が明示されていることが求められます。 + </para> + <para> + 投票は合計されます。 + この合計とは、-1の票は、+1の票を相殺してしまうことを意味します。 + しかし常に、-1の票は、重大なものと考えられ、 + 拒否権を保持する<ulink url="&url.pear.group;">PEARグループ</ulink>が + ケースバイケースの決定をすることになるかもしれません。 + （将来的には、そのような状況ではPEAR QAチームがPEARグループを + 補助することになるだろうということを意図しています。） + ですので、 + -1の票は必ずその決定について説明するコメントを + 付加しなければなりません。 + 好意的な票（+1)については、 + 適切だと思う場合には説明を加えることが望ましいとされています。 + </para> + + <para> + 投票は、票の合計が+5を超えれば、受諾されます。 + </para> + + <para> + 提案が受諾されない場合は、 + そのパッケージについてさらにメーリングリストで議論され、 + 提案者は「投票要求」を再び行うことになるでしょう。 + （これは、それが理にかなっている場合にだけ行われる筈のものです。） + </para> + </listitem> + + <listitem id="developers.contributing.accounts"> + <simpara> + 必要なアカウントの取得 + </simpara> + + <para> + 現在、PEARに関連するアカウントは2タイプあります。 + + <orderedlist> + <listitem> + <simpara>Pear.php.net アカウント</simpara> + + <para> + このアカウントは、 + PEARでパッケージをリリースしたい場合に常に必要となるものです。 + このアカウントを使って、 + アップロードしたり新リリースを出したりするために必要な + <ulink + url="&url.pear;">pear.php.net</ulink>のインフラにアクセスします。 + </para> + </listitem> + + <listitem> + <simpara>PHP CVS アカウント</simpara> + + <para> + <ulink url="&url.cvs;">CVS</ulink>でコードを管理したければ、 + <ulink url="&url.php.cvs;">cvs.php.net</ulink>上の + PEAR <abbrev>CVS</abbrev>モジュールにアクセスする + CVSアカウントを申請できます。 + これにより、 + 他のユーザがあなたのコードに寄与することが容易になります。 + </para> + + <para> + もしCVSリポジトリをすでにどこか別のところ + （例えば、<ulink url="&url.sourceforge;">SourceForge</ulink>） + に持っているか、 + CVSでコードを管理したくなければ、PHP CVSアカウントは必要ありません。 + しかしながら、新リリースを出す前に、 + コードに適用したバグ修正をユーザが試して見ることが出来るように、 + なんらかの公開リポジトリを使うことが強く求められます。 + </para> + </listitem> + </orderedlist> + </para> + <para> + pear.php.netアカウントにサインアップするには、 + <ulink + url="&url.pear.account.new;">PEARアカウント申請ページ</ulink>に行き、 + 書式を埋めてください。 + <ulink url="&url.pear.group;">PEARグループ</ulink>が申請を受け取り、 + 申請が適切であれば、アカウントが開かれます。 + 電子メールで通知されます。 + パッケージをダウンロードするには + pear.php.netアカウントは必要ないことに注意してください。 + </para> + <para> + PHP CVSアカウントは、「<ulink + url="&url.php.cvs.new;">こちら</ulink>」でサインアップしてください。 + PHP CVSアカウントは、PHPグループで承認が行われます。 + </para> + </listitem> + <listitem> + <simpara>パッケージの登録</simpara> + <simpara> + 寄与の手続きがうまく進み、 + pear.php.netアカウントを取得したら、最後は、パッケージの登録です。 + パッケージの登録は、 + パッケージの最初のバージョンのリリースを意味するのではなく、 + PEARパッケージのデータベースに基本的な情報を + いくらか登録することを意味します。 + </simpara> + + <para> + 登録プロセスは、大変簡単です。 + <ulink url="&url.pear.package.new;">このサイト</ulink>にある書式を埋め、 + その情報を送信します。 + その後、<ulink + url="&url.pear.group;">PEARグループ</ulink>が最終的に送信の承認をします。 + 通常、数時間で行われ、電子メールで通知されます。 + </para> + <para> + パッケージを登録したら、最初のリリースを作成できます。 + それについては「<link + linkend="developers.release">こちら</link>」に書かれています。 + </para> + </listitem> + </orderedlist> + </para> + </sect1> + <sect1 id="developers.contributing.docs"> + <title>ドキュメントの書き方の実際</title> + <titleabbrev>ドキュメントの書き方</titleabbrev> + <para> + マニュアルについてのこの章は、 + peardocの標準に基づくドキュメント構成の詳細を + 扱うものではなく、 + どのようにしてドキュメントを論理的に構成するかについて述べるものです。 + peardoc形式でのドキュメントファイルのオーサリングについて学ぶには、 + 「<ulink + url="&url.php.cvs.peardoc.authoring;">こちら</ulink>」のPHPのCVSを + ご覧ください。 + </para> + <para> + パッケージのドキュメントを作成する場合、いくつかの基本的ルールに従うことで、 + 良いドキュメントが得られます。 + </para> + <para> + <orderedlist> + <listitem> + <para> + 初めは、パッケージによってある問題が解決される、ということです。 + その問題とは何でしょうか？ + エンドユーザがその問題について考えてはいないことは何か、 + ということを考慮するように + してみてください。 + （エンドユーザは、その問題が解決すべきことだとは、 + 考えてないかもしれません。） + 例えば、テンプレートのパッケージは、 + コードからのデザインの分離、 + ビジネスロジックからの + ディスプレイロジックの分離という問題を解決するものです。 + 可能ならば、初心のプログラマが理解できるような用語で説明してください。 + </para> + </listitem> + <listitem> + <para> + 次は、 + どのような独自の方法でパッケージはその問題を解決しているか、です。 + ほとんどのドキュメントが、このことを欠いています。 + 例えば、テンプレートエンジンは数多くあり、 + それぞれが同じ問題を解決しようとしていますが、 + 同じ方法では行っていません。 + ブロックベースのテンプレートエンジンは + ロジックをまったく持っていませんが、 + Smartyのようなテンプレートは、 + まったく新しいテンプレート言語を定義しています。 + テンプレートをコンパイルするものもありますし、 + 行わないものもあります。 + 何があなたのパッケージの特徴でしょうか？ + コードをまったく見ていない人が、問題の解決の方法について + 良く理解できるでしょうか？ + </para> + </listitem> + <listitem> + <para> + おしまいに、 + パッケージにパブリックにアクセスできるすべての項目について、 + 完全にドキュメントを作成する必要があります。 + パッケージが再利用可能なクラスであるなら、 + ユーザが使うであろう全メソッドについて + ドキュメント化すべきです。 + パッケージにパブリックにアクセスできる定数があれば、 + それらの意味と使用方法について述べてください。 + ユーザが使わなければならないインターフェイス、例えば、 + データベースDSNやアプリケーションのコマンドラインの引数、 + 設定ファイルでの定数、その他すべての非コードな要素について、 + ドキュメントを作成してください。 + </para> + </listitem> + <listitem> + <para> + 単純なものと複雑なもの、少なくとも２つのコード例を書いてください。 + 当然ですが、PEARパッケージは使ってもらうためにあるので、 + ユーザに使用方法を示してください！ :) + </para> + </listitem> + <listitem> + <para> + 最後は、ドキュメントを校正してください。 + 可能なら、あなたのプロジェクトに親しんでいない他の誰かに、 + ドキュメントを見てもらってください。 + あなたが見落としていた考えを捕らえてくれるかもしれません。 + たぶんこれが最も重要なステップでしょう。 + </para> + </listitem> + </orderedlist> + </para> + </sect1> + </chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-default-dtd-file:"../../../manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +-->