We are making certain demands on both the code and the maintainers of packages:
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 Coding Standards. There have been numerous discussions about whether those standards are good or not, and we have arbitrarily decided that they are good and that the discussion is over. Please respect this decision and don't bring up changes to the basic coding standards, or you risk being ignored mercilessly.
Using PHP_CodeSniffer on your code is the most easy way to see if you comply to the PEAR coding standards.
Each package has to be licensed under an accepted OpenSource license. If you are unsure about the license, you should opt for the New BSD License. The PEAR Group has issued a License Announcement, which provides further details concerning this topic.
The latest revision of the package's source code has to be
available in a public SCM
(Source Code Management) system such as the
SVN server at
svn.php.net
, the Subversion repository
of Google Code, or
at sites such as SourceForge. Hosting at
Google Code or SourceForge is freely available under their terms
of use at any time. Write access to svn.php.net is available
once the package has been accepted as a PEAR package.
All packages must have a publicly available source repository in order to honor the need for access in order to provide patches for bugs or new features.
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 it is easily predictable for you that there is no clean way to add new functionality to the codebase without breaking backwards compatibility, you should consider to review the code and to adapt it, before contributing it to PEAR.
To this end, most PEAR packages make use of object oriented programming. Through concepts such as inheritance, polymorphism, patterns like singleton/factory/command, PEAR packages solve problems in elegant ways. 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 Object-Oriented Programming Concepts on Sun's Java Homepage for a quick start.
Your code must come with appropriate documentation in one of the following formats:
If you write the documentation in Docbook XML and if the markup is valid, the documentation can be easily added to the official PEAR Manual, which you are reading right now.
As of August 2003, phpDocumentor is fully capable of converting in-code API documentation and external tutorials into Docbook XML. PhpDocumentor version 1.2.2 or greater is required. Install with
pear install phpDocumentor
. Use the XML:DocBook/peardoc2:default converter on your source code to generate output. The output should be generated directly into thepeardoc/lang/package
directory, where lang is en, or fr, etc.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 how to write documentation
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 PEAR package in SVN. For examples of PHPUnit tests, see the Auth package.
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 as the maintainer.