cvs: peardoc / manual.xml.in /en/chapters group.xml
| From: | Martin Jansen | Date: | Sat, 16 Dec 2006 12:23:03 +0000 |
| Subject: | cvs: peardoc / manual.xml.in /en/chapters group.xml | ||
| Groups: | php.pear.doc | ||
| Request: | Send a blank email to pear-doc+get-9097@lists.php.net to get a copy of this message | ||
mj Sat Dec 16 12:23:03 2006 UTC
Added files:
/peardoc/en/chapters group.xml
Modified files:
/peardoc manual.xml.in
Log:
* Added a first bunch of PEAR Group documents to the manual.
# Bug #4852
http://cvs.php.net/viewvc.cgi/peardoc/manual.xml.in?r1=1.45&r2=1.46&diff_format=u Index: peardoc/manual.xml.in diff -u peardoc/manual.xml.in:1.45 peardoc/manual.xml.in:1.46 --- peardoc/manual.xml.in:1.45 Mon Oct 30 22:56:28 2006 +++ peardoc/manual.xml.in Sat Dec 16 12:23:03 2006 @@ -38,6 +38,7 @@ &chapters.standards; &chapters.contributing; &chapters.faq; + &chapters.group; </part> <part id="guide-newmaint"> http://cvs.php.net/viewvc.cgi/peardoc/en/chapters/group.xml?view=markup&rev=1.1 Index: peardoc/en/chapters/group.xml +++ peardoc/en/chapters/group.xml <?xml version="1.0" encoding="iso-8859-1" ?> <!-- $Revision: 1.1 $ --> <chapter id="group"> <title>PEAR Group Administrative Documentations</title> <para> One of the jobs of the <ulink url="&url.pear.group;">PEAR Group</ulink> is to issue administrative documents about diverse topics in PEAR. This chapter contains all of them. </para> <!-- http://pear.php.net/group/docs/20031114-pds.php --> <sect1 id="group.directory_structure"> <title>Package Directory Structure</title> <abstract> <para> This document was issued on 4th November 2003 and describes which directory structure must be used in PEAR packages. The goal of this document is to unify the directory naming in CVS and after installations. </para> </abstract> <para> Let's assume we have a package <literal>The_Package_Name</literal> that contains one or more sub-classes (eg. <literal>The_Package_Name_Module</literal>), with some documentation (perhaps a <filename>README</filename>, copies of <acronym>RFC</acronym>s, etc.), a battery of test scripts (unit tests, regression tests, etc.), and it uses some data files (localization strings, etc.), the dir tree would look like: </para> <screen> The_Package_Name |-- Name (contains Module.php) |-- data |-- docs | `-- examples |-- misc |-- scripts `-- tests </screen> <para> <literal>Name</literal> refers to the last part of the <literal>The_Package_Name</literal>, all subclasses of the main class, should be put in there or subdirectories of it. You can refer to http://cvs.php.net/cvs.php/pear/Cache_Lite/ - the directory <literal>Lite</literal> as an example (this basically documents what we currently do anyway). </para> <para> The <filename>data</filename> and <filename>misc</filename> directories are optional, because it will not make sense to have them for every single package in PEAR. </para> <para> The directories that are required are <filename>docs/examples</filename> and <filename>tests</filename>. A package may have no extra documentation, but it should have at least one example. There must also be some basics test to be able to verify that the package is working. The preferred type of testing script system to use is PHPUnit or .phpt. But for now we would be content with any sort of test script. </para> <para> Files in <filename>scripts</filename> will be installed into a directory available in <varname>$PATH</varname>, such as <filename>/usr/local/bin</filename>. </para> <para> Anything that does not fit any of the above categories is placed into the <filename>misc</filename> directory. </para> <para> Maintainers are expected to modify their existing packages to match this new standard. </para> </sect1> <!-- http://pear.php.net/group/docs/20040402-la.php --> <sect1 id="group.licenses"> <title>License Announcement</title> <abstract> <simpara> This document was issued on 02 April 2004 and was revised on 08 January 2006 when adding the MIT License. It lists the licenses that PEAR packages can be released under. </simpara> </abstract> <para> The PEAR Group would like to announce the following refinement of the <link linkend="faq">current license FAQ entry</link>. </para> <para> Vote result: 5 (+1), 0 (-1), 3 (+0) </para> <para> The current list allows a great number of licenses which vary greatly. This means that users may have to learn the in's and out's of alot of licenses. Also some of the license choices impose comparitively high restrictions to the standard PHP license (GPL, QPL ..). As PEAR aims to extend the functionality provided by PHP users of PHP should fairly safely be able to also use any PEAR package without licensing worries, be it for commercial or non commercial, closed or opensource use. </para> <para> Therefore with this announcement the license choices are reduced to the following short list: </para> <itemizedlist> <listitem> <simpara> PHP License </simpara> </listitem> <listitem> <simpara> Apache License </simpara> </listitem> <listitem> <simpara> LGPL </simpara> </listitem> <listitem> <simpara> BSD style </simpara> </listitem> <listitem> <simpara> MIT License </simpara> </listitem> </itemizedlist> <para> Other licenses may be accepted on a case by case basis, but will have to fit the above criterias. This decision has been made to simplify the current situation, and as with all decisions is open to be refined in the future using the RFC proposal methodology. </para> <para> All packages, which are already part of PEAR as of now, which use other licenses, do not need to follow this regulation. </para> <note> <para> In the meantime the FAQ entry linked above has also been updated to reflect the decisions from this document. </para> </note> </sect1> <!-- http://pear.php.net/group/docs/20031114-bbr.php --> <sect1 id="group.bc"> <title>New guidelines for BC breaking releases</title> <abstract> <simpara> This document has been published on 14th November 2003 and describes how releases that break backwards compatibility (BC) have to be handled. </simpara> </abstract> <para> The goal is to make it possible to be able to run multiple major versions in one script. </para> <para> For this reason new major versions (BC break or when the maintainer feels it makes sense as a result of dramatic feature additions or rewrites) require a new package using the following naming convention in the following order of preference (where 'Foo' is the package name and 'X' the major version number): </para> <orderedlist> <listitem> <simpara>FooX</simpara> </listitem> <listitem> <simpara>FoovX</simpara> </listitem> <listitem> <simpara>Foo_vX</simpara> </listitem> </orderedlist> <para> The choice should be made based on preventing current and future misleading or ambiguous names. This means good care should be taken in making the right choice for the package. Obviously the first two allow for some ambiguity (is DB2 a package for IBM's DB2 or just the major version 2 of DB? - is IPv4 a package for IPv4 or is it the 4th major release if IP?). They don't break the idea of "_" mapping to directories (the class DB_NestedSet implies that there is a nestedset.php in the DB dir). The last one prevents any ambiguity but it's the least visually pleasing and also breaks the '_' to directory mapping and is therefore the last choice. </para> <para> We also came to the conclusion that the pear installer should not be clever about the relationship between two major releases aside from printing out notices about the fact that there is a newer major version when a user installs an earlier one. However all major versions of a package will be listed on one package home. This is especially important in order to not break tutorials that cover older major releases (tutorial xyz for major version 1 simply says 'pear install Foo' - if the system would then install 'Foo2' the user might be in for an unpleasant surprise). </para> <para> Therefore, new major versions are for all intents and purposes new packages with the above mentioned exceptions. The names of these new packages are derived using one of the above mentioned naming conventions. </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/viewvc.cgi/peardoc/manual.xml.in?r1=1.45&r2=1.46&diff_format=u Index: peardoc/manual.xml.in diff -u peardoc/manual.xml.in:1.45 peardoc/manual.xml.in:1.46 --- peardoc/manual.xml.in:1.45 Mon Oct 30 22:56:28 2006 +++ peardoc/manual.xml.in Sat Dec 16 12:23:03 2006 @@ -38,6 +38,7 @@ &chapters.standards; &chapters.contributing; &chapters.faq; + &chapters.group; </part> <part id="guide-newmaint"> http://cvs.php.net/viewvc.cgi/peardoc/en/chapters/group.xml?view=markup&rev=1.1 Index: peardoc/en/chapters/group.xml +++ peardoc/en/chapters/group.xml <?xml version="1.0" encoding="iso-8859-1" ?> <!-- $Revision: 1.1 $ --> <chapter id="group"> <title>PEAR Group Administrative Documentations</title> <para> One of the jobs of the <ulink url="&url.pear.group;">PEAR Group</ulink> is to issue administrative documents about diverse topics in PEAR. This chapter contains all of them. </para> <!-- http://pear.php.net/group/docs/20031114-pds.php --> <sect1 id="group.directory_structure"> <title>Package Directory Structure</title> <abstract> <para> This document was issued on 4th November 2003 and describes which directory structure must be used in PEAR packages. The goal of this document is to unify the directory naming in CVS and after installations. </para> </abstract> <para> Let's assume we have a package <literal>The_Package_Name</literal> that contains one or more sub-classes (eg. <literal>The_Package_Name_Module</literal>), with some documentation (perhaps a <filename>README</filename>, copies of <acronym>RFC</acronym>s, etc.), a battery of test scripts (unit tests, regression tests, etc.), and it uses some data files (localization strings, etc.), the dir tree would look like: </para> <screen> The_Package_Name |-- Name (contains Module.php) |-- data |-- docs | `-- examples |-- misc |-- scripts `-- tests </screen> <para> <literal>Name</literal> refers to the last part of the <literal>The_Package_Name</literal>, all subclasses of the main class, should be put in there or subdirectories of it. You can refer to http://cvs.php.net/cvs.php/pear/Cache_Lite/ - the directory <literal>Lite</literal> as an example (this basically documents what we currently do anyway). </para> <para> The <filename>data</filename> and <filename>misc</filename> directories are optional, because it will not make sense to have them for every single package in PEAR. </para> <para> The directories that are required are <filename>docs/examples</filename> and <filename>tests</filename>. A package may have no extra documentation, but it should have at least one example. There must also be some basics test to be able to verify that the package is working. The preferred type of testing script system to use is PHPUnit or .phpt. But for now we would be content with any sort of test script. </para> <para> Files in <filename>scripts</filename> will be installed into a directory available in <varname>$PATH</varname>, such as <filename>/usr/local/bin</filename>. </para> <para> Anything that does not fit any of the above categories is placed into the <filename>misc</filename> directory. </para> <para> Maintainers are expected to modify their existing packages to match this new standard. </para> </sect1> <!-- http://pear.php.net/group/docs/20040402-la.php --> <sect1 id="group.licenses"> <title>License Announcement</title> <abstract> <simpara> This document was issued on 02 April 2004 and was revised on 08 January 2006 when adding the MIT License. It lists the licenses that PEAR packages can be released under. </simpara> </abstract> <para> The PEAR Group would like to announce the following refinement of the <link linkend="faq">current license FAQ entry</link>. </para> <para> Vote result: 5 (+1), 0 (-1), 3 (+0) </para> <para> The current list allows a great number of licenses which vary greatly. This means that users may have to learn the in's and out's of alot of licenses. Also some of the license choices impose comparitively high restrictions to the standard PHP license (GPL, QPL ..). As PEAR aims to extend the functionality provided by PHP users of PHP should fairly safely be able to also use any PEAR package without licensing worries, be it for commercial or non commercial, closed or opensource use. </para> <para> Therefore with this announcement the license choices are reduced to the following short list: </para> <itemizedlist> <listitem> <simpara> PHP License </simpara> </listitem> <listitem> <simpara> Apache License </simpara> </listitem> <listitem> <simpara> LGPL </simpara> </listitem> <listitem> <simpara> BSD style </simpara> </listitem> <listitem> <simpara> MIT License </simpara> </listitem> </itemizedlist> <para> Other licenses may be accepted on a case by case basis, but will have to fit the above criterias. This decision has been made to simplify the current situation, and as with all decisions is open to be refined in the future using the RFC proposal methodology. </para> <para> All packages, which are already part of PEAR as of now, which use other licenses, do not need to follow this regulation. </para> <note> <para> In the meantime the FAQ entry linked above has also been updated to reflect the decisions from this document. </para> </note> </sect1> <!-- http://pear.php.net/group/docs/20031114-bbr.php --> <sect1 id="group.bc"> <title>New guidelines for BC breaking releases</title> <abstract> <simpara> This document has been published on 14th November 2003 and describes how releases that break backwards compatibility (BC) have to be handled. </simpara> </abstract> <para> The goal is to make it possible to be able to run multiple major versions in one script. </para> <para> For this reason new major versions (BC break or when the maintainer feels it makes sense as a result of dramatic feature additions or rewrites) require a new package using the following naming convention in the following order of preference (where 'Foo' is the package name and 'X' the major version number): </para> <orderedlist> <listitem> <simpara>FooX</simpara> </listitem> <listitem> <simpara>FoovX</simpara> </listitem> <listitem> <simpara>Foo_vX</simpara> </listitem> </orderedlist> <para> The choice should be made based on preventing current and future misleading or ambiguous names. This means good care should be taken in making the right choice for the package. Obviously the first two allow for some ambiguity (is DB2 a package for IBM's DB2 or just the major version 2 of DB? - is IPv4 a package for IPv4 or is it the 4th major release if IP?). They don't break the idea of "_" mapping to directories (the class DB_NestedSet implies that there is a nestedset.php in the DB dir). The last one prevents any ambiguity but it's the least visually pleasing and also breaks the '_' to directory mapping and is therefore the last choice. </para> <para> We also came to the conclusion that the pear installer should not be clever about the relationship between two major releases aside from printing out notices about the fact that there is a newer major version when a user installs an earlier one. However all major versions of a package will be listed on one package home. This is especially important in order to not break tutorials that cover older major releases (tutorial xyz for major version 1 simply says 'pear install Foo' - if the system would then install 'Foo2' the user might be in for an unpleasant surprise). </para> <para> Therefore, new major versions are for all intents and purposes new packages with the above mentioned exceptions. The names of these new packages are derived using one of the above mentioned naming conventions. </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 -->