How to contribute code in practice

  1. Finding an appropriate package name

    One of the most important tasks while contributing a new package to PEAR is finding an appropriate name for your package.

    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.

  2. Announcing to the PEAR developers

    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.

    Note: 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 choiceof 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).

  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 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 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. The PHP Group ([email protected]) manage the PHP CVS server, which is used for maintaining PEAR packages. If you already have a PHP CVS account you will ask the PEAR Group for Karma for a given package or set of packages. Please send an email to [email protected] 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 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. 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 CVS account, go here to sign up for it. The PHP CVS account has to be approved by the PHP Group.

  4. Registering the package

    Once you successfully went through the contribution procedure and got your pear.php.net account, you finish with registering your package. Registering does not mean that you are going to release a first version of your package. It just means that some basic information about the package will be added to the PEAR package database.

    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.