Requirements for contributing code

There are certain requirements both for the code and for the author of a package in PEAR:

1. 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 the coding 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. 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 there is no easy way to extend the functionality of your code without breaking backwards compatibility with existing code, you should consider implementing a better design before proposing the package for inclusion in PEAR.

   It may be helpful in this context to become familiar with the basic of object oriented programming. Eventhough PHP does not come with full object oriented support yet, the knowledge will possibly help you in maintaining a 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 over there on Sun's Java Homepage.

3. 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 XML DocBook for use with PEAR. 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

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

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