cvs: peardoc /en/guide/newmaint first-package-tips.xml getting-started.xml intro.xml proposal.xml when-to-contribute.xml
| From: | Martin Jansen | Date: | Sat, 27 Mar 2004 09:15:13 +0000 |
| Subject: | cvs: peardoc /en/guide/newmaint first-package-tips.xml getting-started.xml intro.xml proposal.xml when-to-contribute.xml | ||
| Groups: | php.pear.doc | ||
| Request: | Send a blank email to pear-doc+get-3099@lists.php.net to get a copy of this message | ||
mj Sat Mar 27 04:15:13 2004 EDT
Added files:
/peardoc/en/guide/newmaint first-package-tips.xml
getting-started.xml intro.xml
proposal.xml when-to-contribute.xml
Log:
* Adding a first draft of the New Maintainer's Guide.
http://cvs.php.net/co.php/peardoc/en/guide/newmaint/first-package-tips.xml?r=1.1&p=1 Index: peardoc/en/guide/newmaint/first-package-tips.xml +++ peardoc/en/guide/newmaint/first-package-tips.xml http://cvs.php.net/co.php/peardoc/en/guide/newmaint/getting-started.xml?r=1.1&p=1 Index: peardoc/en/guide/newmaint/getting-started.xml +++ peardoc/en/guide/newmaint/getting-started.xml <?xml version="1.0" encoding="iso-8859-1" ?> <!-- $Revision: 1.1 $ --> <chapter id="newmaint.getting-started"> <docinfo> <author> <firstname>Martin</firstname> <surname>Jansen</surname> </author> <date>$Date: 2004/03/27 09:15:12 $</date> </docinfo> <title>Getting started with the community</title> <titleabbrev>Getting started</titleabbrev> <simpara> Once you have discovered, if your code fits into PEAR, you should get started with the PEAR community. In this chapter we will provide several ways, in which you can establish a first contact with the other PEAR developers, which will hopefully be your future open source fellows. Additionally we will tell you the different places, at which you can find more information about the inner workings and rules of PEAR. </simpara> <sect1 id="newmaint.getting-started.communication"> <title>Communication to other PEAR developers</title> <titleabbrev>Communication</titleabbrev> <para> <emphasis>Mailing lists</emphasis> naturally are the most important way to communicate in projects like PEAR. We are running a number of public mailing lists, which are listed on the <ulink url="&url.pear.support;">PEAR website</ulink>. For starters the PEAR developers mailing list <emphasis><ulink url="&email.pear.dev;">&email.pear.dev;</ulink></emphasis> is of major importance for you: This mailing list is the place where the maintainers of the packages get together to discuss various aspects of their packages and where new packages are discussed. </para> <para> If you would like to get started with maintaining packages in PEAR, you are expected to be subscribed to this mailing list. </para> <note> <simpara> During your first steps in the PEAR community, you may stumble across the term <quote>pear-dev</quote>, which describes the PEAR developers mailing list in PEAR's lingo. </simpara> </note> <para> Some people enjoy communicating via <emphasis>IRC channels</emphasis>. We are running the channel <emphasis>#pear</emphasis> in the server network of <ulink url="&url.efnet;">EFnet</ulink>. At this channel some of the most active PEAR developers hang out regularly. However for serious inquiries or discussions, you should mail to the developers mailing list. </para> </sect1> <sect1 id="newmaint.getting-started.docs"> <title>More written information</title> <titleabbrev>More information</titleabbrev> <para> In unsteady intervals, the PEAR Group publishes so called <ulink url="http://pear.php.net/group/">Administrative Documents</ulink>, in which decisions by the PEAR Group are described. You are expected to read those documents before starting serious contributions to PEAR, because they contain important information about the inner workings of PEAR. The developers mailing list will be informed, when new documents are added, so you do not need to visit the site frequently. </para> <para> This manual contains the <link linkend="guide-developers">Developer Guide</link>, which provides valueable information as well. </para> </sect1> <sect1 id="newmaint.getting-started.hierarchy"> <title>The hierarchy in PEAR</title> <simpara> TBD </simpara> </sect1> </chapter> <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t sgml-parent-document:nil sgml-default-dtd-file:"../../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 --> http://cvs.php.net/co.php/peardoc/en/guide/newmaint/intro.xml?r=1.1&p=1 Index: peardoc/en/guide/newmaint/intro.xml +++ peardoc/en/guide/newmaint/intro.xml <?xml version="1.0" encoding="iso-8859-1" ?> <!-- $Revision: 1.1 $ --> <chapter id="newmaint.intro"> <docinfo> <author> <firstname>Martin</firstname> <surname>Jansen</surname> </author> <date>$Date: 2004/03/27 09:15:12 $</date> </docinfo> <title>Introduction</title> <simpara> If you are planning to contribute code in form of a new package to the PEAR project, this guide will take you by the hand and provide you with all necessary information. </simpara> <simpara> We will start right away by describing the cases in which it makes sense to contribute and in which not. After we have ensured that the package, you are wanting to contribute, fits into PEAR, we will describe how to get started with the community. Once you are confident about the inner workings of the PEAR developer community, we will explain how you can start the formal process of proposing a new package and we will give some tips for making your first package as successful as possible. </simpara> </chapter> <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t sgml-parent-document:nil sgml-default-dtd-file:"../../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 --> http://cvs.php.net/co.php/peardoc/en/guide/newmaint/proposal.xml?r=1.1&p=1 Index: peardoc/en/guide/newmaint/proposal.xml +++ peardoc/en/guide/newmaint/proposal.xml <?xml version="1.0" encoding="iso-8859-1" ?> <!-- $Revision: 1.1 $ --> <chapter id="newmaint.proposal"> <docinfo> <author> <firstname>Martin</firstname> <surname>Jansen</surname> </author> <author> <firstname>Tobias</firstname> <surname>Schlitt</surname> </author> <date>$Date: 2004/03/27 09:15:12 $</date> </docinfo> <title>The formal proposition process</title> <titleabbrev>Proposing</titleabbrev> <simpara> In the early times of PEAR, all new packages were proposed by an informal email to the <ulink url="mailto:&email.pear.dev;">PEAR developers list</ulink>. Over the time the number of new proposals increased quite dramatically, and thus it became very hard to manually keep track of all the concurrent proposals. </simpara> <simpara> Because of that we have set up a web-based proposal handling system, which is integrated tightly into the <ulink url="&url.pear;">PEAR website</ulink>. This system is called PEPr. (Pronounced like the spice.) PEPr stands for <quote>PEar Proposal system</quote>. </simpara> <simpara> In this chapter of the <link linkend="guide-newmaint">New Maintainers' Guide</link> we are going to describe the requirements and the workflow for a PEPr-based proposal. After that we will provide you with information, on how to actually start a proposal, and finally you will learn, what you are expected to do once the proposal is finished. </simpara> <simpara> After reading this chapter, you will will be able to start a proposal for your code right away. </simpara> <sect1 id="newmaint.proposal.requirements"> <title>Requirements for a proposal</title> <simpara> The following enumeration lists the most important things that need to be done/available <emphasis>before</emphasis> starting a new proposal. </simpara> <itemizedlist> <listitem> <simpara> Finding a name for the package </simpara> <simpara> It is obvious that each package needs to have a unique name. To get a <quote>feeling</quote> for proper package names, you should browse the <ulink url="&url.pear.package.browse;">list of existing packages</ulink>. </simpara> </listitem> <listitem> <simpara> Finding a category for the package </simpara> <simpara> Similar to each package having a unique name, it has to be placed in one of the categories, which are listed in the <ulink url="&url.pear.package.browse;">package browser</ulink> as well. </simpara> </listitem> <listitem> <simpara> Writing a package description </simpara> </listitem> <listitem> <simpara> Choosing a licence for the package </simpara> </listitem> <listitem> <simpara> Writing examples and documentation </simpara> </listitem> <listitem> <simpara> Packaging the source code into a archive file </simpara> </listitem> </itemizedlist> </sect1> <sect1 id="newmaint.proposal.step2"> <title>Step 2: Initiating a discussion</title> <titleabbrev>Step 2</titleabbrev> <simpara> Before starting the proposal process in PEPr, a thread should be started for each new package on the developers mailing list. We are preferring this intermediate step for the sake of convenience, because we feel that it is easier and more comfortable for us to hit a single key in our mail client to join a discussion, than to open a browser window and looking for the right page on the website. </simpara> <simpara> By discussing about the package with the PEAR developers, you will easily be able to find out, if </simpara> <itemizedlist> <listitem> <simpara> there are technical issues with the package/code </simpara> </listitem> <listitem> <simpara> a package with similar functionality already exists </simpara> </listitem> <listitem> <simpara> there are people working on something similar, so you can join forces </simpara> </listitem> <listitem> <simpara> etc. </simpara> </listitem> </itemizedlist> <simpara> By reading between the lines, you should also be able to find out, if you will be able to gather enough positive votes in the formal proposal process. </simpara> <simpara> Be aware that people will scrutinize your code. Also please note that PEAR is an international project with people coming from different cultural backgrounds. Because of that most people in the community are not native english speakers; do not worry if your English is not perfect and, most importantly, be aware that sometimes misunderstandings may happen. So it is important that everybody involved tries to be as clear as possible. </simpara> <simpara> Once you feel that you have addressed all questions/suggestions/critics, which were raised during the mailing list discussion, you can go ahead with starting the formal voting process. </simpara> </sect1> <sect1 id="newmaint.proposal.step3"> <title>Step 3: Using PEPr</title> <titleabbrev>Step 3</titleabbrev> <para> The way to handle proposals inside the community has been automated in 2003 to ensure the quality of the packages even before a package is proposed and to take away some work from the active package maintainers. To be able to use the proposal tool (<ulink url="&url.pear.pepr;">PEPr</ulink>), you have to apply to a PEAR website account <ulink url="&url.pear.account.new;">here</ulink>. After that you can open a new proposal using the "<ulink url="http://pear.php.net/pepr/pepr-proposal-edit.php">New package proposal</ulink>" link on your left. </para> <para> The process of a package proposal is divided into 4 stages: "Draft", "Proposal", "Call for Votes" and "Finished". Every proposal has to run through all of these stages. Inside each stage (except the draft stage) an email is send to you (the proposer) and the PEAR development mailinglist (<ulink url="mailto:&email.pear.dev;">&email.pear.dev;</ulink>) for any action. A good idea is to <ulink url="&url.pear.support;">subscribe</ulink> to this mailinglist to get a better picture of what the community process is like. </para> <para> <orderedlist> <listitem> <simpara> Creating a draft </simpara> <para> At first your proposal is a draft. This simply means you can edit it, view it and it is shown up on the PEPr overview page as a draft. This stage is for you to play around with PEPr, to shape your proposal nicely and to prepare it for the proposal process. You can switch to the next stage when ever you want to publish your proposal and get feedback from the PEAR community. </para> </listitem> <listitem> <simpara> Moving to the Proposal stage </simpara> <para> After switching to the stage Proposal you have a real proposal. Either through email or through PEPr itself the community will give you hints and ask questions about the proposed package. Generally it is a good idea to follow these suggestions, but sometimes people in the community will have different visions for your package, which should be sorted out during this stage. After a week of comments you may switch to the next phase. You should only switch to the next stage, if you are sure that the PEAR community will accept your package. </para> </listitem> <listitem> <simpara> Calling for votes </simpara> <para> The next stage is the voting stage, during which you may not change your proposal anymore. You may not edit nor delete the proposal from now on. During the proposal stage "Call for Votes" every active PEAR maintainer may give 1 vote on the proposal. Votes are given using the numbers -1, 0 and +1, where -1 means "I'm against this package to be added to PEAR in the current form", +1 says "I'm in favour of getting this package into PEAR in the current form" and 0 means "I have looked at your package, but I am undecided". The time to vote for a package is 7 days (working and non working days). If after this time less than 5 votes have been cast, the developers get another 7 days to cast their votes. After this time the voting is ended, whether there are 5 votes or not. </para> <para> Votes on proposals can be bound to a condition. These conditional votes indicate that you have to fulfil a certain condition the voters expect to be fulfilled. If there are conditional votes you are expected to read and follow them! The conditions on a vote will be provided in the votes comment. Each (conditional and none conditional comments) may have comments. Reading those is always a good idea! </para> </listitem> <listitem> <simpara> Proposal Finished </simpara> <para> Now your proposal is finished. To determine if the proposal was successful or not, the sum of all votes is computed. If the result is greater or equal to 5 the proposal has been accepted. Otherwise we are sorry to say, that the community has decided to reject it. Have a look at their comments during proposal and vote stage to find out why. Maybe you can rework your package and propose it again, but please do not try to hand in a proposal the same way twice. </para> <para> If your proposal has been accepted, you may put your package into PEAR. If this is your first proposal, please contact the <ulink url="&url.pear.group;">PEAR group</ulink> (at <ulink url="mailto:pear-group@php.net">pear-group@php.net</ulink>) to get your current PEAR web account upgraded to a full featured developer account. After that, you can register your package and upload releases. </para> </listitem> </orderedlist> </para> </sect1> <sect1 id="newmaint.proposal.proposalproperties"> <title>Properties of a proposal in PEPr</title> <titleabbrev>Proposal properties</titleabbrev> <para> A package proposal consists of several parts. You have to choose a name and a category for your proposal. In most cases your preferred, or a similar category, is available for selection in <ulink url="&url.pear.pepr;">PEPr</ulink>. Only if this is not the case you may propose a new category. You have to provide a description of your package. This description can (and should) contain not only a detailed description on what the packages purpose is, but even how, why and for what purpose you developed it. You can use so called <ulink url="http://pear.php.net/pepr/pepr-bbcode-help.php">BBCode</ulink> to format your proposal description and make it look pretty to the PEAR developers. </para> <para> Next thing is to provide a list of PEAR internal and external (not desired!) dependencies. External dependencies may exist to 3rd party programs, as long as they are not written in PHP itself. However, there can always be exceptions made on a case by case basis. In general your package may depend on a Unix or Win32 application (e.g. give a PHP interface to the dir command) but not on another ones PHP scripts (e.g. another database layer or a complete application). In the last case, you should try to cut those dependencies or replace the dependency with PEAR packages. </para> <para> Beyond that you should provide minimum 2 links to better communicate to the community how your package works. The links can have one of 5 types: PEAR package (recommended), source files (recommended, .phps is preferred), example, example source files (.phps is preferred) and documentation. The more material you provide for your proposal, the better feedback and more opinions you will get about it. More documentation the better! </para> <para> In general you may not edit or delete your proposal after you left the Proposal stage. In urgent cases you can contact the PEAR community on <ulink url="mailto:&email.pear.dev;"> pear-dev@lists.php.net</ulink> to reach a PEAR web administrator to do a change. This is heavily discouraged however! You should have made everything clear to the community during the Proposal stage to ensure a hassle free voting process. Even if the voting has a negative result, this is no reason to delete it. </para> </sect1> </chapter> <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t sgml-parent-document:nil sgml-default-dtd-file:"../../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 --> http://cvs.php.net/co.php/peardoc/en/guide/newmaint/when-to-contribute.xml?r=1.1&p=1 Index: peardoc/en/guide/newmaint/when-to-contribute.xml +++ peardoc/en/guide/newmaint/when-to-contribute.xml <?xml version="1.0" encoding="iso-8859-1" ?> <!-- $Revision: 1.1 $ --> <chapter id="newmaint.when-to-contribute"> <docinfo> <author> <firstname>Martin</firstname> <surname>Jansen</surname> </author> <date>$Date: 2004/03/27 09:15:12 $</date> </docinfo> <title>When to contribute (and when not to contribute)</title> <titleabbrev>When to contribute</titleabbrev> <simpara> Here we describe the cases, in which it makes sense to contribute code to PEAR and in which it does not make sense to do so. This description is by no means complete. So if you are unsure, if the kind of code, which you are planning to contribute, can generally be included into PEAR, get in contact with the <ulink url="mailto:&email.pear.dev;">developers mailinglist</ulink>. </simpara> <sect1 id="newmaint.when-to-contribute.good"> <title>Cases in which it makes sense to contribute</title> <simpara> As you might have already noticed, while browsing the list of <ulink url="&url.pear.package.browse;">existing packages</ulink>, the PEAR packages provide a (often abstract) solution for a general problem. Thus your code will most likely fit into PEAR, if it solves a problem that will not only occur in one (e.g. your) specific application, but that occurs in a lot of (web) applications. Examples are: </simpara> <itemizedlist> <listitem> <simpara> Implementations of Network protocols </simpara> </listitem> <listitem> <simpara> Object oriented wrappers that provide easy access to otherwise complicated or less intuitive PHP extensions. </simpara> </listitem> <listitem> <simpara> Parsing different XML dialects. </simpara> <para> The PEAR packages that provide XML parsing functionalities can be found in the category browser. (XXX: Add link here.) </para> </listitem> </itemizedlist> <simpara> No matter which area is covered by a package, the <acronym>API</acronym> should be as abstract as possible (while not becoming too complex), so that it can be utilized painlessly in as much use cases as possible. </simpara> </sect1> <sect1 id="newmaint.when-to-contribute.bad"> <title>Cases in which it does <emphasis>not</emphasis> make sense to contribute</title> <simpara> A rough rule of thumb is that code, which solves a problem that exists in one or only very few projects, is not convenient for inclusion into PEAR, because most people will not benefit from it. </simpara> <simpara> This however does not mean that <quote>niche software</quote> cannot be included in PEAR. In the Math section we have a number of elaborate packages that solve different kinds of algebraic problems. While those problems do not occur in average applications, the packages are very abstract and scientific projects benefit a lot. </simpara> <simpara> Apart from code that does not fit into PEAR because of a lack of abstractness, there is another type of code that currently cannot be contribued to PEAR: Full web applications. </simpara> <simpara> Despite the fact that the "A" in PEAR stands for "Application" there is a simple reason why applications are not yet supported: Until now nobody has gotten around to make the infrastructure like the PEAR installer capable of handling packages that provide complete web applications. </simpara> <simpara> When the situation changes, this site will be updated. </simpara> </sect1> </chapter> <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t sgml-parent-document:nil sgml-default-dtd-file:"../../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 -->
http://cvs.php.net/co.php/peardoc/en/guide/newmaint/first-package-tips.xml?r=1.1&p=1 Index: peardoc/en/guide/newmaint/first-package-tips.xml +++ peardoc/en/guide/newmaint/first-package-tips.xml http://cvs.php.net/co.php/peardoc/en/guide/newmaint/getting-started.xml?r=1.1&p=1 Index: peardoc/en/guide/newmaint/getting-started.xml +++ peardoc/en/guide/newmaint/getting-started.xml <?xml version="1.0" encoding="iso-8859-1" ?> <!-- $Revision: 1.1 $ --> <chapter id="newmaint.getting-started"> <docinfo> <author> <firstname>Martin</firstname> <surname>Jansen</surname> </author> <date>$Date: 2004/03/27 09:15:12 $</date> </docinfo> <title>Getting started with the community</title> <titleabbrev>Getting started</titleabbrev> <simpara> Once you have discovered, if your code fits into PEAR, you should get started with the PEAR community. In this chapter we will provide several ways, in which you can establish a first contact with the other PEAR developers, which will hopefully be your future open source fellows. Additionally we will tell you the different places, at which you can find more information about the inner workings and rules of PEAR. </simpara> <sect1 id="newmaint.getting-started.communication"> <title>Communication to other PEAR developers</title> <titleabbrev>Communication</titleabbrev> <para> <emphasis>Mailing lists</emphasis> naturally are the most important way to communicate in projects like PEAR. We are running a number of public mailing lists, which are listed on the <ulink url="&url.pear.support;">PEAR website</ulink>. For starters the PEAR developers mailing list <emphasis><ulink url="&email.pear.dev;">&email.pear.dev;</ulink></emphasis> is of major importance for you: This mailing list is the place where the maintainers of the packages get together to discuss various aspects of their packages and where new packages are discussed. </para> <para> If you would like to get started with maintaining packages in PEAR, you are expected to be subscribed to this mailing list. </para> <note> <simpara> During your first steps in the PEAR community, you may stumble across the term <quote>pear-dev</quote>, which describes the PEAR developers mailing list in PEAR's lingo. </simpara> </note> <para> Some people enjoy communicating via <emphasis>IRC channels</emphasis>. We are running the channel <emphasis>#pear</emphasis> in the server network of <ulink url="&url.efnet;">EFnet</ulink>. At this channel some of the most active PEAR developers hang out regularly. However for serious inquiries or discussions, you should mail to the developers mailing list. </para> </sect1> <sect1 id="newmaint.getting-started.docs"> <title>More written information</title> <titleabbrev>More information</titleabbrev> <para> In unsteady intervals, the PEAR Group publishes so called <ulink url="http://pear.php.net/group/">Administrative Documents</ulink>, in which decisions by the PEAR Group are described. You are expected to read those documents before starting serious contributions to PEAR, because they contain important information about the inner workings of PEAR. The developers mailing list will be informed, when new documents are added, so you do not need to visit the site frequently. </para> <para> This manual contains the <link linkend="guide-developers">Developer Guide</link>, which provides valueable information as well. </para> </sect1> <sect1 id="newmaint.getting-started.hierarchy"> <title>The hierarchy in PEAR</title> <simpara> TBD </simpara> </sect1> </chapter> <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t sgml-parent-document:nil sgml-default-dtd-file:"../../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 --> http://cvs.php.net/co.php/peardoc/en/guide/newmaint/intro.xml?r=1.1&p=1 Index: peardoc/en/guide/newmaint/intro.xml +++ peardoc/en/guide/newmaint/intro.xml <?xml version="1.0" encoding="iso-8859-1" ?> <!-- $Revision: 1.1 $ --> <chapter id="newmaint.intro"> <docinfo> <author> <firstname>Martin</firstname> <surname>Jansen</surname> </author> <date>$Date: 2004/03/27 09:15:12 $</date> </docinfo> <title>Introduction</title> <simpara> If you are planning to contribute code in form of a new package to the PEAR project, this guide will take you by the hand and provide you with all necessary information. </simpara> <simpara> We will start right away by describing the cases in which it makes sense to contribute and in which not. After we have ensured that the package, you are wanting to contribute, fits into PEAR, we will describe how to get started with the community. Once you are confident about the inner workings of the PEAR developer community, we will explain how you can start the formal process of proposing a new package and we will give some tips for making your first package as successful as possible. </simpara> </chapter> <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t sgml-parent-document:nil sgml-default-dtd-file:"../../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 --> http://cvs.php.net/co.php/peardoc/en/guide/newmaint/proposal.xml?r=1.1&p=1 Index: peardoc/en/guide/newmaint/proposal.xml +++ peardoc/en/guide/newmaint/proposal.xml <?xml version="1.0" encoding="iso-8859-1" ?> <!-- $Revision: 1.1 $ --> <chapter id="newmaint.proposal"> <docinfo> <author> <firstname>Martin</firstname> <surname>Jansen</surname> </author> <author> <firstname>Tobias</firstname> <surname>Schlitt</surname> </author> <date>$Date: 2004/03/27 09:15:12 $</date> </docinfo> <title>The formal proposition process</title> <titleabbrev>Proposing</titleabbrev> <simpara> In the early times of PEAR, all new packages were proposed by an informal email to the <ulink url="mailto:&email.pear.dev;">PEAR developers list</ulink>. Over the time the number of new proposals increased quite dramatically, and thus it became very hard to manually keep track of all the concurrent proposals. </simpara> <simpara> Because of that we have set up a web-based proposal handling system, which is integrated tightly into the <ulink url="&url.pear;">PEAR website</ulink>. This system is called PEPr. (Pronounced like the spice.) PEPr stands for <quote>PEar Proposal system</quote>. </simpara> <simpara> In this chapter of the <link linkend="guide-newmaint">New Maintainers' Guide</link> we are going to describe the requirements and the workflow for a PEPr-based proposal. After that we will provide you with information, on how to actually start a proposal, and finally you will learn, what you are expected to do once the proposal is finished. </simpara> <simpara> After reading this chapter, you will will be able to start a proposal for your code right away. </simpara> <sect1 id="newmaint.proposal.requirements"> <title>Requirements for a proposal</title> <simpara> The following enumeration lists the most important things that need to be done/available <emphasis>before</emphasis> starting a new proposal. </simpara> <itemizedlist> <listitem> <simpara> Finding a name for the package </simpara> <simpara> It is obvious that each package needs to have a unique name. To get a <quote>feeling</quote> for proper package names, you should browse the <ulink url="&url.pear.package.browse;">list of existing packages</ulink>. </simpara> </listitem> <listitem> <simpara> Finding a category for the package </simpara> <simpara> Similar to each package having a unique name, it has to be placed in one of the categories, which are listed in the <ulink url="&url.pear.package.browse;">package browser</ulink> as well. </simpara> </listitem> <listitem> <simpara> Writing a package description </simpara> </listitem> <listitem> <simpara> Choosing a licence for the package </simpara> </listitem> <listitem> <simpara> Writing examples and documentation </simpara> </listitem> <listitem> <simpara> Packaging the source code into a archive file </simpara> </listitem> </itemizedlist> </sect1> <sect1 id="newmaint.proposal.step2"> <title>Step 2: Initiating a discussion</title> <titleabbrev>Step 2</titleabbrev> <simpara> Before starting the proposal process in PEPr, a thread should be started for each new package on the developers mailing list. We are preferring this intermediate step for the sake of convenience, because we feel that it is easier and more comfortable for us to hit a single key in our mail client to join a discussion, than to open a browser window and looking for the right page on the website. </simpara> <simpara> By discussing about the package with the PEAR developers, you will easily be able to find out, if </simpara> <itemizedlist> <listitem> <simpara> there are technical issues with the package/code </simpara> </listitem> <listitem> <simpara> a package with similar functionality already exists </simpara> </listitem> <listitem> <simpara> there are people working on something similar, so you can join forces </simpara> </listitem> <listitem> <simpara> etc. </simpara> </listitem> </itemizedlist> <simpara> By reading between the lines, you should also be able to find out, if you will be able to gather enough positive votes in the formal proposal process. </simpara> <simpara> Be aware that people will scrutinize your code. Also please note that PEAR is an international project with people coming from different cultural backgrounds. Because of that most people in the community are not native english speakers; do not worry if your English is not perfect and, most importantly, be aware that sometimes misunderstandings may happen. So it is important that everybody involved tries to be as clear as possible. </simpara> <simpara> Once you feel that you have addressed all questions/suggestions/critics, which were raised during the mailing list discussion, you can go ahead with starting the formal voting process. </simpara> </sect1> <sect1 id="newmaint.proposal.step3"> <title>Step 3: Using PEPr</title> <titleabbrev>Step 3</titleabbrev> <para> The way to handle proposals inside the community has been automated in 2003 to ensure the quality of the packages even before a package is proposed and to take away some work from the active package maintainers. To be able to use the proposal tool (<ulink url="&url.pear.pepr;">PEPr</ulink>), you have to apply to a PEAR website account <ulink url="&url.pear.account.new;">here</ulink>. After that you can open a new proposal using the "<ulink url="http://pear.php.net/pepr/pepr-proposal-edit.php">New package proposal</ulink>" link on your left. </para> <para> The process of a package proposal is divided into 4 stages: "Draft", "Proposal", "Call for Votes" and "Finished". Every proposal has to run through all of these stages. Inside each stage (except the draft stage) an email is send to you (the proposer) and the PEAR development mailinglist (<ulink url="mailto:&email.pear.dev;">&email.pear.dev;</ulink>) for any action. A good idea is to <ulink url="&url.pear.support;">subscribe</ulink> to this mailinglist to get a better picture of what the community process is like. </para> <para> <orderedlist> <listitem> <simpara> Creating a draft </simpara> <para> At first your proposal is a draft. This simply means you can edit it, view it and it is shown up on the PEPr overview page as a draft. This stage is for you to play around with PEPr, to shape your proposal nicely and to prepare it for the proposal process. You can switch to the next stage when ever you want to publish your proposal and get feedback from the PEAR community. </para> </listitem> <listitem> <simpara> Moving to the Proposal stage </simpara> <para> After switching to the stage Proposal you have a real proposal. Either through email or through PEPr itself the community will give you hints and ask questions about the proposed package. Generally it is a good idea to follow these suggestions, but sometimes people in the community will have different visions for your package, which should be sorted out during this stage. After a week of comments you may switch to the next phase. You should only switch to the next stage, if you are sure that the PEAR community will accept your package. </para> </listitem> <listitem> <simpara> Calling for votes </simpara> <para> The next stage is the voting stage, during which you may not change your proposal anymore. You may not edit nor delete the proposal from now on. During the proposal stage "Call for Votes" every active PEAR maintainer may give 1 vote on the proposal. Votes are given using the numbers -1, 0 and +1, where -1 means "I'm against this package to be added to PEAR in the current form", +1 says "I'm in favour of getting this package into PEAR in the current form" and 0 means "I have looked at your package, but I am undecided". The time to vote for a package is 7 days (working and non working days). If after this time less than 5 votes have been cast, the developers get another 7 days to cast their votes. After this time the voting is ended, whether there are 5 votes or not. </para> <para> Votes on proposals can be bound to a condition. These conditional votes indicate that you have to fulfil a certain condition the voters expect to be fulfilled. If there are conditional votes you are expected to read and follow them! The conditions on a vote will be provided in the votes comment. Each (conditional and none conditional comments) may have comments. Reading those is always a good idea! </para> </listitem> <listitem> <simpara> Proposal Finished </simpara> <para> Now your proposal is finished. To determine if the proposal was successful or not, the sum of all votes is computed. If the result is greater or equal to 5 the proposal has been accepted. Otherwise we are sorry to say, that the community has decided to reject it. Have a look at their comments during proposal and vote stage to find out why. Maybe you can rework your package and propose it again, but please do not try to hand in a proposal the same way twice. </para> <para> If your proposal has been accepted, you may put your package into PEAR. If this is your first proposal, please contact the <ulink url="&url.pear.group;">PEAR group</ulink> (at <ulink url="mailto:pear-group@php.net">pear-group@php.net</ulink>) to get your current PEAR web account upgraded to a full featured developer account. After that, you can register your package and upload releases. </para> </listitem> </orderedlist> </para> </sect1> <sect1 id="newmaint.proposal.proposalproperties"> <title>Properties of a proposal in PEPr</title> <titleabbrev>Proposal properties</titleabbrev> <para> A package proposal consists of several parts. You have to choose a name and a category for your proposal. In most cases your preferred, or a similar category, is available for selection in <ulink url="&url.pear.pepr;">PEPr</ulink>. Only if this is not the case you may propose a new category. You have to provide a description of your package. This description can (and should) contain not only a detailed description on what the packages purpose is, but even how, why and for what purpose you developed it. You can use so called <ulink url="http://pear.php.net/pepr/pepr-bbcode-help.php">BBCode</ulink> to format your proposal description and make it look pretty to the PEAR developers. </para> <para> Next thing is to provide a list of PEAR internal and external (not desired!) dependencies. External dependencies may exist to 3rd party programs, as long as they are not written in PHP itself. However, there can always be exceptions made on a case by case basis. In general your package may depend on a Unix or Win32 application (e.g. give a PHP interface to the dir command) but not on another ones PHP scripts (e.g. another database layer or a complete application). In the last case, you should try to cut those dependencies or replace the dependency with PEAR packages. </para> <para> Beyond that you should provide minimum 2 links to better communicate to the community how your package works. The links can have one of 5 types: PEAR package (recommended), source files (recommended, .phps is preferred), example, example source files (.phps is preferred) and documentation. The more material you provide for your proposal, the better feedback and more opinions you will get about it. More documentation the better! </para> <para> In general you may not edit or delete your proposal after you left the Proposal stage. In urgent cases you can contact the PEAR community on <ulink url="mailto:&email.pear.dev;"> pear-dev@lists.php.net</ulink> to reach a PEAR web administrator to do a change. This is heavily discouraged however! You should have made everything clear to the community during the Proposal stage to ensure a hassle free voting process. Even if the voting has a negative result, this is no reason to delete it. </para> </sect1> </chapter> <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t sgml-parent-document:nil sgml-default-dtd-file:"../../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 --> http://cvs.php.net/co.php/peardoc/en/guide/newmaint/when-to-contribute.xml?r=1.1&p=1 Index: peardoc/en/guide/newmaint/when-to-contribute.xml +++ peardoc/en/guide/newmaint/when-to-contribute.xml <?xml version="1.0" encoding="iso-8859-1" ?> <!-- $Revision: 1.1 $ --> <chapter id="newmaint.when-to-contribute"> <docinfo> <author> <firstname>Martin</firstname> <surname>Jansen</surname> </author> <date>$Date: 2004/03/27 09:15:12 $</date> </docinfo> <title>When to contribute (and when not to contribute)</title> <titleabbrev>When to contribute</titleabbrev> <simpara> Here we describe the cases, in which it makes sense to contribute code to PEAR and in which it does not make sense to do so. This description is by no means complete. So if you are unsure, if the kind of code, which you are planning to contribute, can generally be included into PEAR, get in contact with the <ulink url="mailto:&email.pear.dev;">developers mailinglist</ulink>. </simpara> <sect1 id="newmaint.when-to-contribute.good"> <title>Cases in which it makes sense to contribute</title> <simpara> As you might have already noticed, while browsing the list of <ulink url="&url.pear.package.browse;">existing packages</ulink>, the PEAR packages provide a (often abstract) solution for a general problem. Thus your code will most likely fit into PEAR, if it solves a problem that will not only occur in one (e.g. your) specific application, but that occurs in a lot of (web) applications. Examples are: </simpara> <itemizedlist> <listitem> <simpara> Implementations of Network protocols </simpara> </listitem> <listitem> <simpara> Object oriented wrappers that provide easy access to otherwise complicated or less intuitive PHP extensions. </simpara> </listitem> <listitem> <simpara> Parsing different XML dialects. </simpara> <para> The PEAR packages that provide XML parsing functionalities can be found in the category browser. (XXX: Add link here.) </para> </listitem> </itemizedlist> <simpara> No matter which area is covered by a package, the <acronym>API</acronym> should be as abstract as possible (while not becoming too complex), so that it can be utilized painlessly in as much use cases as possible. </simpara> </sect1> <sect1 id="newmaint.when-to-contribute.bad"> <title>Cases in which it does <emphasis>not</emphasis> make sense to contribute</title> <simpara> A rough rule of thumb is that code, which solves a problem that exists in one or only very few projects, is not convenient for inclusion into PEAR, because most people will not benefit from it. </simpara> <simpara> This however does not mean that <quote>niche software</quote> cannot be included in PEAR. In the Math section we have a number of elaborate packages that solve different kinds of algebraic problems. While those problems do not occur in average applications, the packages are very abstract and scientific projects benefit a lot. </simpara> <simpara> Apart from code that does not fit into PEAR because of a lack of abstractness, there is another type of code that currently cannot be contribued to PEAR: Full web applications. </simpara> <simpara> Despite the fact that the "A" in PEAR stands for "Application" there is a simple reason why applications are not yet supported: Until now nobody has gotten around to make the infrastructure like the PEAR installer capable of handling packages that provide complete web applications. </simpara> <simpara> When the situation changes, this site will be updated. </simpara> </sect1> </chapter> <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t sgml-parent-document:nil sgml-default-dtd-file:"../../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 -->