How to contribute code in practice

The general syntax for package names is <Category>_<Name>. The value for <Category> should be chosen from a predefined list of categories that are available in PEAR (e.g. "HTTP", "Net", "HTML"). The second part is the name of the package (like "Upload", "Portscan", "Table").

The categories that are currently available in PEAR are represented by the bold headings at the Package Browser. If you think that your package does not fit in any of the existing categories, you can ask the on the mailing list to create a new category. (PEAR is usually reluctant to do that.)

Apart from this general syntax, the package names can also contain more than one category name. An example for this is HTML_Template_PHPLIB: The multiple categories indicate that the package PHPLIB is part of the category Template, that again is part of the HTML category. This naming scheme is necessary here since it's possible that there are Template systems in PEAR that don't work with HTML but with another technology. (The cases where more than one "category" is used are pretty rare.)

If you need further advice or help for finding a name for your package, you should ask on the developers mailing list.

The second step while contributing is to announce your package in PEPr. Usually this announcement will spawn some discussion. After one week you may call for votes with PEPr and the developers will then start to vote for or against your proposal. (You are of course urged to join the upcoming discussion.) Announcing a package does of course not mean that it is already accepted! That will still take some time and likely some more efforts from your side.

The following passages are taken from the administrative document Handling Package Proposals, which describes proposing new packages in more details. Reading this document should be a mandatory step for PEAR newbies.

Only the votes of active members of the PEAR community (must have a PEAR web account, however the proposer himself is not counted) are counted, however anyone may vote. Votes require that a final choice of package name is specified.

The votes are added up, which means that one -1 offsets a +1. However -1 vote should always be considered to be serious and may lead to decisions being made on a case by case basis by the PEAR Group who reserves a veto (it is intended that in the future the PEAR QA team will assist the PEAR Group in such situations). Therefore a -1 vote *must* contain a comment explaining that decision, it is desirable that votes in favour (+1) should also be accompanied with an explanation when appropriate.

A vote is accepted if the total of all votes exceeds +5.

In case the proposal is not accepted the package can be further discussed on the list and the proposer may attempt to make another "call for vote" (it is expected that this is only done for sensible reasons).

Right now one can distinguish between two types of accounts related to PEAR:

1. Pear.php.net account

   This account is always necessary for you, if you want to release your package through PEAR. With this account you have access to the necessary infrastructure on pear.php.net in order to propose, upload and roll new releases. The PEAR Group manages PEAR accounts and pearweb karma levels (i.e.: karma to use the web site to maintain packages).

2. PHP SVN account

   If you want to administrate your code via SVN , you can also apply for a SVN account to have access to the pear SVN module on svn.php.net. This makes it easier for other users to contribute to your code. The PHP Group (group@php.net) manage the PHP SVN server, which is used for maintaining PEAR packages. If you already have a PHP SVN account you will ask the PEAR Group for Karma for a given package or set of packages. Please send an email to pear-group@php.net specifying what packages you need commit access along with credentials (e.g.: the package "lead" email giving you his go or a QA member email announcing you are to be given access).

   If you already have a SVN repository somewhere else (e.g. on SourceForge), or if you don't want to maintain your code via SVN, you don't need the PHP SVN account. It is highly recommended to use some kind of public repository, so that users can try out any bug fixes you apply to the code, before a new release is rolled.

To sign up for your pear.php.net account, go to the PEAR account request page and fill out the form there. The PEAR Group will then receive your request and someone will open your account, if the request sounds reasonable. You will be notified about that via email. Please note that you do NOT need a pear.php.net account to download packages from there.

To get a PHP SVN account, go here to sign up for it. The PHP SVN account has to be approved by the PHP Group.

The registration process is quite straightforward: Fill out the form on this site and submit the information. After you have done that, the PEAR Group has to finally approve your submission. This usually happens in a few hours and you will be notified about it via email.

After having registered your package, you can create a first release, which is described here.