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 the decision has been made that they are absolutely necessary. There is no sense in discussing about this.

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 PHP License. The PEAR Group has issued a License Announcement, which provides further details concerning this topic.

3. Code must be available in public code repository.

   The latest revision of the package's source code has to be available in a public SCM (Software Configuration Management) system such as the CVS server at cvs.php.net, the Subversion repository of Google Code, or at sites such as SourceForge. Hosting at Google Code or SourceForge is freely availabe under their terms of use at any time. Write access to cvs.php.net is available once the package has been accepted as a PEAR package.

   The main reason for this requirement is that there needs to be a way for both users and fellow PEAR developers to get access to the latest (probably yet unreleased) version of the code in order to track down bugs and/or provide patches for these.

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.

   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.

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.

   Note: 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 PFC DB package. 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.

   Warning

   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.