Requirements for contributing code

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

1. 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.

2. 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.

3. 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.

4. 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.

5. Documentation in an appropriate format (plain text, docbook)

   Your code must come with appropriate documentation in one of the following formats:

   • Docbook XML
   • Plain Text

   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

6. Regression tests in .phpt or PHPUnit format

   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.

7. 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.