cvs: phpdoc /en/pear pear.xml standards.xml
| From: | Stig Bakken | Date: | Sat, 04 Aug 2001 22:20:47 +0000 |
| Subject: | cvs: phpdoc /en/pear pear.xml standards.xml | ||
| Groups: | php.doc | ||
| Request: | Send a blank email to phpdoc+get-969336748@lists.php.net to get a copy of this message | ||
ssb Sat Aug 4 18:20:47 2001 EDT
Modified files:
/phpdoc/en/pear pear.xml standards.xml
Log:
* some more pear docs
* added cvs tags to pear coding guidelines
Index: phpdoc/en/pear/pear.xml diff -u phpdoc/en/pear/pear.xml:1.7 phpdoc/en/pear/pear.xml:1.8 --- phpdoc/en/pear/pear.xml:1.7 Sat Aug 4 14:07:05 2001 +++ phpdoc/en/pear/pear.xml Sat Aug 4 18:20:47 2001 @@ -1,5 +1,5 @@ <reference id="pear.reference"> -<!-- $Revision: 1.7 $ --> +<!-- $Revision: 1.8 $ --> <title>PEAR Reference Manual</title> <titleabbrev>PEAR</titleabbrev> @@ -38,52 +38,71 @@ </listitem> </itemizedlist> </para> - <refsect2> - <title>PEAR "destructors"</title> - <simpara> - If you inherit <classname>PEAR</classname> in a class called - <replaceable>ClassName</replaceable>, you can define a method in - it called called _<replaceable>ClassName</replaceable> (the - class name with an underscore prepended) that will be invoked - when the request is over. This is not a destructor in the sense - that you can "delete" an object and have the destructor called, - but in the sense that PHP gives you a callback in the object - when it is done executing. See <link - linkend="example.pear.destructors">the example</link> below. - </simpara> - </refsect2> - <refsect2> - <title>PEAR Error Handling</title> - <simpara> - PEAR's base class also provides a way of passing around more - complex errors than a &true;/false value or a numeric code. A - PEAR error is an object that is either an instance of the class - <classname>PEAR_Error</classname>, or some class inheriting - <classname>PEAR_Error</classname>. - </simpara> - <simpara> - One of the design criteria of PEAR's errors is that it should - not force a particular type of output on the user, it should be - possible to handle errors without any output at all if that is - desireable. This makes it possible to handle errors gracefully, - also when your output format is different from HTML (for example - WML or some other XML format). - </simpara> - <simpara> - The error object can be configured to do a number of things when - it is created, such as printing an error message, printing the - message and exiting, raising an error with PHP's - <function>trigger_error</function> function, invoke a callback, - or none of the above. This is typically specified in - <classname>PEAR_Error</classname>'s constructor, but all of the - parameters are optional, and you can set up defaults for errors - generated from each object based on the - <classname>PEAR</classname> class. See the <link - linkend="example.pear.error1">PEAR error examples</link> for how - to use it and the <classname>PEAR_Error</classname> reference - for the full details. - </simpara> - </refsect2> + </refsect1> + <refsect1 id="pear.destructors"> + <title>PEAR "destructors"</title> + <simpara> + If you inherit <classname>PEAR</classname> in a class called + <replaceable>ClassName</replaceable>, you can define a method in + it called called _<replaceable>ClassName</replaceable> (the + class name with an underscore prepended) that will be invoked + when the request is over. This is not a destructor in the sense + that you can "delete" an object and have the destructor called, + but in the sense that PHP gives you a callback in the object + when PHP is done executing. See <link + linkend="example.pear.destructors">the example</link> below. + </simpara> + <para> + <warning id="pear.destructors.warning"> + <title>Important!</title> + <para> + In order for destructors to work properly, you must + instantiate your class with the "=& new" operator like + this: + <programlisting role="php"> +$obj =& new MyClass(); +</programlisting> + </para> + <simpara> + If you only use "= new", the object registered in PEAR's + shutdown list will be a copy of the object at the time the + constructor is called, and it will this copy's "destructor" + that will be called upon request shutdown. + </simpara> + </warning> + </para> + </refsect1> + <refsect1 id="pear.error-handling"> + <title>PEAR Error Handling</title> + <simpara> + PEAR's base class also provides a way of passing around more + complex errors than a true/false value or a numeric code. A + PEAR error is an object that is either an instance of the class + <classname>PEAR_Error</classname>, or some class inheriting + <classname>PEAR_Error</classname>. + </simpara> + <simpara> + One of the design criteria of PEAR's errors is that it should not + force a particular type of output on the user, it should be + possible to handle errors without any output at all if that is + desirable. This makes it possible to handle errors gracefully, + also when your output format is different from HTML (for example + WML or some other XML format). + </simpara> + <simpara> + The error object can be configured to do a number of things when + it is created, such as printing an error message, printing the + message and exiting, raising an error with PHP's + <function>trigger_error</function> function, invoke a callback, + or none of the above. This is typically specified in + <classname>PEAR_Error</classname>'s constructor, but all of the + parameters are optional, and you can set up defaults for errors + generated from each object based on the + <classname>PEAR</classname> class. See the <link + linkend="example.pear.error1">PEAR error examples</link> for how + to use it and the <classname>PEAR_Error</classname> reference + for the full details. + </simpara> </refsect1> <refsect1> <title>Examples</title> @@ -137,7 +156,7 @@ } } -$fileobj = new FileContainer("testfile"); +$fileobj =& new FileContainer("testfile"); $fileobj->append("this ends up at the end of the file\n"); // When the request is done and PHP shuts down, $fileobj's @@ -153,6 +172,11 @@ server. So anything printed in a "destructor" gets lost except when PHP is used in command-line mode. Bummer. </simpara> + <simpara> + Also, see the <link + linkend="pear.destructors.warning">warning</link> about how to + instantiate objects if you want to use the destructor. + </simpara> </note> </para> <simpara> @@ -230,6 +254,149 @@ parameter), raiseError uses the default error mode and exits if fsockopen fails. </simpara> + </refsect1> + <refsect1> + <title>Global Variables Used</title> + <para> + The PEAR class uses some global variables to register global + defaults, and an object list used by the "destructors". All of + the global variables associated with the PEAR class have a + <literal>_PEAR_</literal> name prefix. + </para> + <para> + <variablelist> + <varlistentry> + <term>$_PEAR_default_error_mode</term> + <listitem> + <simpara> + If no default error mode is set in an object, this mode will + be used. Must be one of + <constant>PEAR_ERROR_RETURN</constant>, + <constant>PEAR_ERROR_PRINT</constant>, + <constant>PEAR_ERROR_TRIGGER</constant>, + <constant>PEAR_ERROR_DIE</constant> or + <constant>PEAR_ERROR_CALLBACK</constant>. + </simpara> + <para> + Don't set this variable directly, call + <function>PEAR::setErrorHandling</function> as a static + method like this: + <informalexample> + <programlisting role="php"> +PEAR::setErrorHandling(PEAR_ERROR_DIE); +</programlisting> + </informalexample> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>$_PEAR_default_error_options</term> + <listitem> + <simpara> + If the error mode is <constant>PEAR_ERROR_TRIGGER</constant>, + this is the error level (one of + <constant>E_USER_NOTICE</constant>, + <constant>E_USER_WARNING</constant> or + <constant>E_USER_ERROR</constant>). + </simpara> + <para> + Don't set this variable directly, call + <function>PEAR::setErrorHandling</function> as a static + method like this: + <informalexample> + <programlisting role="php"> +PEAR::setErrorHandling(PEAR_ERROR_TRIGGER, E_USER_ERROR); +</programlisting> + </informalexample> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>$_PEAR_default_error_callback</term> + <listitem> + <simpara> + If no <replaceable>options</replaceable> parameter is used + when an error is raised and the error mode is + <constant>PEAR_ERROR_CALLBACK</constant>, the value of this + variable is used as the callback. This means that you can + switch the error mode temporarily and return to callback mode + without specifying the callback function again. A string + value represents a function, a two-element array with an + object at index 0 and a string at index 1 represents a + method. + </simpara> + <para> + Again, don't set this variable directly, call + <function>PEAR::setErrorHandling</function> as a static + method like this: + <informalexample> + <programlisting role="php"> +PEAR::setErrorHandling(PEAR_ERROR_CALLBACK, "my_error_handler"); +</programlisting> + </informalexample> + </para> + <para> + Here is an example of how you can switch back and forth + without specifying the callback function again: + <informalexample> + <programlisting role="php"> +PEAR::setErrorMode(PEAR_ERROR_CALLBACK, "my_function_handler"); +do_some_stuff(); +PEAR::setErrorMode(PEAR_ERROR_DIE); +do_some_critical_stuff(); +PEAR::setErrorMode(PEAR_ERROR_CALLBACK); +// now we're back to using my_function_handler again +</programlisting> + </informalexample> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + <refsect1> + <title>Methods</title> + <refsect2 id="function.pear.pear"> + <title>PEAR::PEAR</title> + <funcsynopsis> + <funcprototype> + <funcdef>PEAR()</funcdef> + <void/> + </funcprototype> + </funcsynopsis> + <para> + This is the PEAR class constructor. Call it from the + constructor of every class inheriting the PEAR class. + <example> + <title>PEAR Class Constructor Example</title> + <programlisting role="php"> +class MyClass extends PEAR +{ + var $foo, $bar; + function MyClass($foo, $bar) + { + $this->PEAR(); + $this->foo = $foo; + $this->bar = $bar; + } +} +</programlisting> + </example> + </para> + </refsect2> + <refsect2 id="function.pear.-pear"> + <title>PEAR::_PEAR</title> + <funcsynopsis> + <funcprototype> + <funcdef>_PEAR()</funcdef> + <void/> + </funcprototype> + </funcsynopsis> + <para> + This is the PEAR class destructor. It is called during request + shutdown. + </para> + </refsect2> </refsect1> </refentry> <refentry id="class.pear-error"> Index: phpdoc/en/pear/standards.xml diff -u phpdoc/en/pear/standards.xml:1.7 phpdoc/en/pear/standards.xml:1.8 --- phpdoc/en/pear/standards.xml:1.7 Thu Aug 2 13:37:51 2001 +++ phpdoc/en/pear/standards.xml Sat Aug 4 18:20:47 2001 @@ -1,4 +1,4 @@ -<!-- $Revision: 1.7 $ --> +<!-- $Revision: 1.8 $ --> <chapter id="pear.standards"> <title>PEAR Coding Standards</title> <note> @@ -108,7 +108,7 @@ <sect1 id="pear.standards.funcdef"> <title>Function Definitions</title> <para> - Function declaractions follow the "one &true; brace" convention: + Function declaractions follow the "one true brace" convention: <programlisting role="php"> function fooFunction($arg1, $arg2 = '') { @@ -239,12 +239,16 @@ </para> </sect1> - <sect1 id="pear.standards.cvstags"> - <title>CVS Tags</title> + <sect1 id="pear.standards.cvs"> + <title>Using CVS</title> + <simpara> + This section applies only to packages using CVS at cvs.php.net. + </simpara> <para> - Include the $Id$ CVS vendor tag in each file. As each file + Include the $Id$ CVS keyword in each file. As each file is edited, add this tag if it's not yet present (or replace existing forms such as "Last Modified:", etc.). +<!-- <note> <simpara> We have a custom $Horde tag in Horde cvs to track our versions @@ -253,6 +257,86 @@ control system, etc...] </simpara> </note> +--> + </para> + <para> + The rest of this section assumes that you have basic knowledge + about CVS tags and branches. + </para> + <para> + CVS tags are used to label which revisions of the files in your + package belong to a given release. Below is a list of the + required and suggested CVS tags: + + <variablelist> + <varlistentry> + <term>RELEASE_<replaceable>n_n</replaceable></term> + <listitem> + <simpara> + (required) Used for tagging a release. If you don't use it, + there's no way to go back and retrieve your package from the + CVS server in the state it was in at the time of the release. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>QA_<replaceable>n_n</replaceable></term> + <listitem> + <simpara> + (branch, optional) If you feel you need to roll out a + release candidate before releasing, it's a good idea to make a + branch for it so you can isolate the release and apply only + those critical fixes before the actual release. Meanwhile, + normal development may continue on the main trunk. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>MAINT_<replaceable>n_n</replaceable></term> + <listitem> + <simpara> + (branch, optional) If you need to make "micro-releases" (for + example 1.2.1 and so on after 1.2, you can use a branch for + that too, if your main trunk is very active and you want only + minor changes between your micro-releases. + </simpara> + </listitem> + </varlistentry> + </variablelist> + Only the RELEASE tag is required, the rest are recommended for + your convenience. + </para> + <para> + Below is an example of how to tag the 1.2 release of the + "Money_Fast" package: + <informalexample> + <screen><prompt>$ </prompt><command>cd pear/Money_Fast</command> +<prompt>$ </prompt><command>cvs tag RELEASE_1_2</command> +<computeroutput>T Fast.php +T README +T package.xml +</computeroutput> +</screen> + </informalexample> + By doing this you make it possible for the PEAR web site to take + you through the rest of your release process. + </para> + <para> + Here's an example of how to create a QA branch: + <informalexample> + <screen><prompt>$ </prompt><command>cvs tag QA_2_0_BP</command> +... +<prompt>$ </prompt><command>cvs rtag -b -r QA_2_0_BP QA_2_0</command> +<prompt>$ </prompt><command>cvs update -r QA_2_0</command> +<prompt>$ </prompt><command>cvs tag RELEASE_2_0RC1</command> +...and then the actual release, from the same branch: +<prompt>$ </prompt><command>cvs tag RELEASE_2_0</command> +</screen> + </informalexample> + The "QA_2_0_BP" tag is a "branch point" tag, which is the start + point of the tag. It's always a good idea to start a CVS branch + from such branch points. MAINT branches may use the RELEASE tag + as their branch point. </para> </sect1> @@ -266,14 +350,14 @@ <sect1 id="pear.standards.constants"> <title>Naming Constants</title> <para> - Constants should always be uppercase, with underscores to seperate + Constants should always be all-uppercase, with underscores to seperate words. Prefix constant names with the name of the class/package they are used in. For example, the constants used by the <literal>DB::</literal> package all begin with "<literal>DB_</literal>". </para> </sect1> - + </chapter> <!-- Keep this comment at the end of the file Local variables:
Index: phpdoc/en/pear/pear.xml diff -u phpdoc/en/pear/pear.xml:1.7 phpdoc/en/pear/pear.xml:1.8 --- phpdoc/en/pear/pear.xml:1.7 Sat Aug 4 14:07:05 2001 +++ phpdoc/en/pear/pear.xml Sat Aug 4 18:20:47 2001 @@ -1,5 +1,5 @@ <reference id="pear.reference"> -<!-- $Revision: 1.7 $ --> +<!-- $Revision: 1.8 $ --> <title>PEAR Reference Manual</title> <titleabbrev>PEAR</titleabbrev> @@ -38,52 +38,71 @@ </listitem> </itemizedlist> </para> - <refsect2> - <title>PEAR "destructors"</title> - <simpara> - If you inherit <classname>PEAR</classname> in a class called - <replaceable>ClassName</replaceable>, you can define a method in - it called called _<replaceable>ClassName</replaceable> (the - class name with an underscore prepended) that will be invoked - when the request is over. This is not a destructor in the sense - that you can "delete" an object and have the destructor called, - but in the sense that PHP gives you a callback in the object - when it is done executing. See <link - linkend="example.pear.destructors">the example</link> below. - </simpara> - </refsect2> - <refsect2> - <title>PEAR Error Handling</title> - <simpara> - PEAR's base class also provides a way of passing around more - complex errors than a &true;/false value or a numeric code. A - PEAR error is an object that is either an instance of the class - <classname>PEAR_Error</classname>, or some class inheriting - <classname>PEAR_Error</classname>. - </simpara> - <simpara> - One of the design criteria of PEAR's errors is that it should - not force a particular type of output on the user, it should be - possible to handle errors without any output at all if that is - desireable. This makes it possible to handle errors gracefully, - also when your output format is different from HTML (for example - WML or some other XML format). - </simpara> - <simpara> - The error object can be configured to do a number of things when - it is created, such as printing an error message, printing the - message and exiting, raising an error with PHP's - <function>trigger_error</function> function, invoke a callback, - or none of the above. This is typically specified in - <classname>PEAR_Error</classname>'s constructor, but all of the - parameters are optional, and you can set up defaults for errors - generated from each object based on the - <classname>PEAR</classname> class. See the <link - linkend="example.pear.error1">PEAR error examples</link> for how - to use it and the <classname>PEAR_Error</classname> reference - for the full details. - </simpara> - </refsect2> + </refsect1> + <refsect1 id="pear.destructors"> + <title>PEAR "destructors"</title> + <simpara> + If you inherit <classname>PEAR</classname> in a class called + <replaceable>ClassName</replaceable>, you can define a method in + it called called _<replaceable>ClassName</replaceable> (the + class name with an underscore prepended) that will be invoked + when the request is over. This is not a destructor in the sense + that you can "delete" an object and have the destructor called, + but in the sense that PHP gives you a callback in the object + when PHP is done executing. See <link + linkend="example.pear.destructors">the example</link> below. + </simpara> + <para> + <warning id="pear.destructors.warning"> + <title>Important!</title> + <para> + In order for destructors to work properly, you must + instantiate your class with the "=& new" operator like + this: + <programlisting role="php"> +$obj =& new MyClass(); +</programlisting> + </para> + <simpara> + If you only use "= new", the object registered in PEAR's + shutdown list will be a copy of the object at the time the + constructor is called, and it will this copy's "destructor" + that will be called upon request shutdown. + </simpara> + </warning> + </para> + </refsect1> + <refsect1 id="pear.error-handling"> + <title>PEAR Error Handling</title> + <simpara> + PEAR's base class also provides a way of passing around more + complex errors than a true/false value or a numeric code. A + PEAR error is an object that is either an instance of the class + <classname>PEAR_Error</classname>, or some class inheriting + <classname>PEAR_Error</classname>. + </simpara> + <simpara> + One of the design criteria of PEAR's errors is that it should not + force a particular type of output on the user, it should be + possible to handle errors without any output at all if that is + desirable. This makes it possible to handle errors gracefully, + also when your output format is different from HTML (for example + WML or some other XML format). + </simpara> + <simpara> + The error object can be configured to do a number of things when + it is created, such as printing an error message, printing the + message and exiting, raising an error with PHP's + <function>trigger_error</function> function, invoke a callback, + or none of the above. This is typically specified in + <classname>PEAR_Error</classname>'s constructor, but all of the + parameters are optional, and you can set up defaults for errors + generated from each object based on the + <classname>PEAR</classname> class. See the <link + linkend="example.pear.error1">PEAR error examples</link> for how + to use it and the <classname>PEAR_Error</classname> reference + for the full details. + </simpara> </refsect1> <refsect1> <title>Examples</title> @@ -137,7 +156,7 @@ } } -$fileobj = new FileContainer("testfile"); +$fileobj =& new FileContainer("testfile"); $fileobj->append("this ends up at the end of the file\n"); // When the request is done and PHP shuts down, $fileobj's @@ -153,6 +172,11 @@ server. So anything printed in a "destructor" gets lost except when PHP is used in command-line mode. Bummer. </simpara> + <simpara> + Also, see the <link + linkend="pear.destructors.warning">warning</link> about how to + instantiate objects if you want to use the destructor. + </simpara> </note> </para> <simpara> @@ -230,6 +254,149 @@ parameter), raiseError uses the default error mode and exits if fsockopen fails. </simpara> + </refsect1> + <refsect1> + <title>Global Variables Used</title> + <para> + The PEAR class uses some global variables to register global + defaults, and an object list used by the "destructors". All of + the global variables associated with the PEAR class have a + <literal>_PEAR_</literal> name prefix. + </para> + <para> + <variablelist> + <varlistentry> + <term>$_PEAR_default_error_mode</term> + <listitem> + <simpara> + If no default error mode is set in an object, this mode will + be used. Must be one of + <constant>PEAR_ERROR_RETURN</constant>, + <constant>PEAR_ERROR_PRINT</constant>, + <constant>PEAR_ERROR_TRIGGER</constant>, + <constant>PEAR_ERROR_DIE</constant> or + <constant>PEAR_ERROR_CALLBACK</constant>. + </simpara> + <para> + Don't set this variable directly, call + <function>PEAR::setErrorHandling</function> as a static + method like this: + <informalexample> + <programlisting role="php"> +PEAR::setErrorHandling(PEAR_ERROR_DIE); +</programlisting> + </informalexample> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>$_PEAR_default_error_options</term> + <listitem> + <simpara> + If the error mode is <constant>PEAR_ERROR_TRIGGER</constant>, + this is the error level (one of + <constant>E_USER_NOTICE</constant>, + <constant>E_USER_WARNING</constant> or + <constant>E_USER_ERROR</constant>). + </simpara> + <para> + Don't set this variable directly, call + <function>PEAR::setErrorHandling</function> as a static + method like this: + <informalexample> + <programlisting role="php"> +PEAR::setErrorHandling(PEAR_ERROR_TRIGGER, E_USER_ERROR); +</programlisting> + </informalexample> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>$_PEAR_default_error_callback</term> + <listitem> + <simpara> + If no <replaceable>options</replaceable> parameter is used + when an error is raised and the error mode is + <constant>PEAR_ERROR_CALLBACK</constant>, the value of this + variable is used as the callback. This means that you can + switch the error mode temporarily and return to callback mode + without specifying the callback function again. A string + value represents a function, a two-element array with an + object at index 0 and a string at index 1 represents a + method. + </simpara> + <para> + Again, don't set this variable directly, call + <function>PEAR::setErrorHandling</function> as a static + method like this: + <informalexample> + <programlisting role="php"> +PEAR::setErrorHandling(PEAR_ERROR_CALLBACK, "my_error_handler"); +</programlisting> + </informalexample> + </para> + <para> + Here is an example of how you can switch back and forth + without specifying the callback function again: + <informalexample> + <programlisting role="php"> +PEAR::setErrorMode(PEAR_ERROR_CALLBACK, "my_function_handler"); +do_some_stuff(); +PEAR::setErrorMode(PEAR_ERROR_DIE); +do_some_critical_stuff(); +PEAR::setErrorMode(PEAR_ERROR_CALLBACK); +// now we're back to using my_function_handler again +</programlisting> + </informalexample> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + <refsect1> + <title>Methods</title> + <refsect2 id="function.pear.pear"> + <title>PEAR::PEAR</title> + <funcsynopsis> + <funcprototype> + <funcdef>PEAR()</funcdef> + <void/> + </funcprototype> + </funcsynopsis> + <para> + This is the PEAR class constructor. Call it from the + constructor of every class inheriting the PEAR class. + <example> + <title>PEAR Class Constructor Example</title> + <programlisting role="php"> +class MyClass extends PEAR +{ + var $foo, $bar; + function MyClass($foo, $bar) + { + $this->PEAR(); + $this->foo = $foo; + $this->bar = $bar; + } +} +</programlisting> + </example> + </para> + </refsect2> + <refsect2 id="function.pear.-pear"> + <title>PEAR::_PEAR</title> + <funcsynopsis> + <funcprototype> + <funcdef>_PEAR()</funcdef> + <void/> + </funcprototype> + </funcsynopsis> + <para> + This is the PEAR class destructor. It is called during request + shutdown. + </para> + </refsect2> </refsect1> </refentry> <refentry id="class.pear-error"> Index: phpdoc/en/pear/standards.xml diff -u phpdoc/en/pear/standards.xml:1.7 phpdoc/en/pear/standards.xml:1.8 --- phpdoc/en/pear/standards.xml:1.7 Thu Aug 2 13:37:51 2001 +++ phpdoc/en/pear/standards.xml Sat Aug 4 18:20:47 2001 @@ -1,4 +1,4 @@ -<!-- $Revision: 1.7 $ --> +<!-- $Revision: 1.8 $ --> <chapter id="pear.standards"> <title>PEAR Coding Standards</title> <note> @@ -108,7 +108,7 @@ <sect1 id="pear.standards.funcdef"> <title>Function Definitions</title> <para> - Function declaractions follow the "one &true; brace" convention: + Function declaractions follow the "one true brace" convention: <programlisting role="php"> function fooFunction($arg1, $arg2 = '') { @@ -239,12 +239,16 @@ </para> </sect1> - <sect1 id="pear.standards.cvstags"> - <title>CVS Tags</title> + <sect1 id="pear.standards.cvs"> + <title>Using CVS</title> + <simpara> + This section applies only to packages using CVS at cvs.php.net. + </simpara> <para> - Include the $Id$ CVS vendor tag in each file. As each file + Include the $Id$ CVS keyword in each file. As each file is edited, add this tag if it's not yet present (or replace existing forms such as "Last Modified:", etc.). +<!-- <note> <simpara> We have a custom $Horde tag in Horde cvs to track our versions @@ -253,6 +257,86 @@ control system, etc...] </simpara> </note> +--> + </para> + <para> + The rest of this section assumes that you have basic knowledge + about CVS tags and branches. + </para> + <para> + CVS tags are used to label which revisions of the files in your + package belong to a given release. Below is a list of the + required and suggested CVS tags: + + <variablelist> + <varlistentry> + <term>RELEASE_<replaceable>n_n</replaceable></term> + <listitem> + <simpara> + (required) Used for tagging a release. If you don't use it, + there's no way to go back and retrieve your package from the + CVS server in the state it was in at the time of the release. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>QA_<replaceable>n_n</replaceable></term> + <listitem> + <simpara> + (branch, optional) If you feel you need to roll out a + release candidate before releasing, it's a good idea to make a + branch for it so you can isolate the release and apply only + those critical fixes before the actual release. Meanwhile, + normal development may continue on the main trunk. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>MAINT_<replaceable>n_n</replaceable></term> + <listitem> + <simpara> + (branch, optional) If you need to make "micro-releases" (for + example 1.2.1 and so on after 1.2, you can use a branch for + that too, if your main trunk is very active and you want only + minor changes between your micro-releases. + </simpara> + </listitem> + </varlistentry> + </variablelist> + Only the RELEASE tag is required, the rest are recommended for + your convenience. + </para> + <para> + Below is an example of how to tag the 1.2 release of the + "Money_Fast" package: + <informalexample> + <screen><prompt>$ </prompt><command>cd pear/Money_Fast</command> +<prompt>$ </prompt><command>cvs tag RELEASE_1_2</command> +<computeroutput>T Fast.php +T README +T package.xml +</computeroutput> +</screen> + </informalexample> + By doing this you make it possible for the PEAR web site to take + you through the rest of your release process. + </para> + <para> + Here's an example of how to create a QA branch: + <informalexample> + <screen><prompt>$ </prompt><command>cvs tag QA_2_0_BP</command> +... +<prompt>$ </prompt><command>cvs rtag -b -r QA_2_0_BP QA_2_0</command> +<prompt>$ </prompt><command>cvs update -r QA_2_0</command> +<prompt>$ </prompt><command>cvs tag RELEASE_2_0RC1</command> +...and then the actual release, from the same branch: +<prompt>$ </prompt><command>cvs tag RELEASE_2_0</command> +</screen> + </informalexample> + The "QA_2_0_BP" tag is a "branch point" tag, which is the start + point of the tag. It's always a good idea to start a CVS branch + from such branch points. MAINT branches may use the RELEASE tag + as their branch point. </para> </sect1> @@ -266,14 +350,14 @@ <sect1 id="pear.standards.constants"> <title>Naming Constants</title> <para> - Constants should always be uppercase, with underscores to seperate + Constants should always be all-uppercase, with underscores to seperate words. Prefix constant names with the name of the class/package they are used in. For example, the constants used by the <literal>DB::</literal> package all begin with "<literal>DB_</literal>". </para> </sect1> - + </chapter> <!-- Keep this comment at the end of the file Local variables: