Requirements for contributing code

We are making certain demands on both the code and the maintainers
of packages:

Code must conform 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 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.

Code must be appropriately licensed.

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.

Code must be available in a public code repository.

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.

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.

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.

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
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 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
PEAR package in SVN. For examples of
PHPUnit tests, see the Auth
package.

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
lists:

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 as the
maintainer.