How to contribute code in practice

1. Finding an appropriate package name

   One of the most important tasks during contributing your code to PEAR is finding an appropriate name for your package.

   The general syntax for package names is <Category>_<Name>. The value for <Category> has to be choosen 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“).

   If you think that your package does not fit in any of the existing categories, you can ask to create a new category. Nevertheless our aim is to keep the category structure as simple as possible.

   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.

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

2. Announcing to the PEAR developers

   The second step while contributing is to announce your package on the developers mailing list. Usually this announcement will spawn some discussion and the developers will then start to vote for or against your proposal. (You are of course urged to join the upcoming discussion.) Getting a +1 from a developer means she is in favour of your proposal, while getting a -1 means that the developer doesn't like it. If you finally have five +1's, you can go ahead with step 3.

3. Getting the necessary accounts

   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 pages on pear.php.net in order to upload and roll new releases.

   2. PHP CVS account

      If you want to administrate your code via CVS , you can also apply for a CVS account to have access to the pear CVS module on cvs.php.net. This makes it easier for other users to contribute to your code.

      If you already have a CVS repository somewhere else (e.g. on SourceForge), or if you don't want to maintain your code via CVS, you don't need the PHP CVS account.

   To sign up for your pear.php.net account, go to the PEAR account request page and fill out the form there. The PEAR administrators will then receive your request and they will open your account, if it sounds reasonable for them. 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 CVS account, go here to sign up for it. The PHP CVS account has to be approved by the PHP Group.

4. Bundling releases

   Prerequesite for releasing your code is that your account request for pear.php.net has been accepted.

   Before you can roll out the first release of your package, you need to the register the package itself. To do this, go here and fill out/submit the form. Please choose the name and the category which have been decided in point 1 of this paragraph.

   After having registered your package, you can create a first release:

   The first prerequesite is to create a package definition file: This file is an XML file called package.xml that needs to reside in the root directory of your package.

   To learn about package definition files, please read here.

   After having created this file, just run

   $ pear package

   in the directory that contains the package definition file. This command will create a .tgz file in the same directory. In our example, the complete filename would be Money_Fast-1.0.tgz.

   Now go to this page and upload the tgz file that has been created previously there. This will start the automated release process, which will roll out version 1.0 of the package Money_Fast.