PEAR is driven by an open
source 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.
We are making certain demands on both the code and the maintainers
Code must be conforming to the Coding Standards.
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 the decision has
been made that they are absolutely necessary. There is no sense
in discussing about this.
Extensible and "forward-compatible" code.
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.
In this context it may be helpful to become familiar with the
basics of object oriented programming. Eventhough PHP 4 does not
come with full object oriented support yet, the knowledge will
possibly help you in maintaining an 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 Object-Oriented Programming
Concepts on Sun's Java
Homepage for a quick start.
Documentation in an appropriate format (plain text, docbook)
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
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 the
peardoc/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 PFC
DB package. For examples of
PHPUnit tests, see the Auth
The contributor ("you") must be willing to provide support
for the package and must be willing to release future versions that at
the very least fix bugs.
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 mailing
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.
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