<?xml version="1.0" encoding="iso-8859-1"?>

 <chapter id="chapter-cvs">
  <title>Working with CVS</title>

  <para>
   The PHP documentation is maintained using <ulink
   url="&url.cvs;">CVS</ulink> (<emphasis>Concurrent
   Versions System</emphasis>). CVS allows the documentation
   contributors to make changes to the different files that make up
   the PHP documentation without stepping on each other's toes.
  </para>
  
  <para>
   A CVS system contains a central server, where all the files
   are stored. A CVS server can host many repositories,
   the name of the repository used by the PHP Documentation
   people is <literal>phpdoc</literal>. To access this
   server, you need a CVS client program on your system.
  </para>
  
  <para>
   When you decide to work on a file, you need to check
   it out (~download the file). Then you can make modifications
   on the file on your local copy. If you are ready, you
   need to commit the changes (~upload the new file). The CVS
   client asks for your short comment about why this commit
   was neccesary. You can give here a summary about what was
   changed. The CVS server stores the history of files with
   these commit messages. Everybody can then see what was
   modified by you, because all modifications generate a diff
   posted to the <link linkend="chapter-maillist">mailing
   list</link>, and the history is also viewable with a CVS
   client or the web interface at
   <ulink url="&url.php.cvs;">&url.php.cvs;</ulink>. You can
   also delete a file or add one with your CVS client,
   if you see it is needed.
  </para>

  <para>
   This section is not intended to be a CVS tutorial, only a quick
   walkthough to help you get started checking out out the
   <literal>phpdoc</literal> tree and commiting your changes.
   The complete CVS documentation and can be found at <ulink
   url="&url.cvs;">&url.cvs;</ulink>.
  </para>

  <para>
   CVS tutorials can be found at:
   <itemizedlist>
    <listitem>
     <simpara><ulink url="&url.cvstut1;">&url.cvstut1;</ulink></simpara>
    </listitem>
    <listitem>
     <simpara><ulink url="&url.cvstut2;">&url.cvstut2;</ulink></simpara>
    </listitem>
   </itemizedlist>
  </para>
  
  <para>
   You can also type <literal>man cvs</literal> anytime
   you would like to get help about your CVS client. This
   brings up a help text called a "manpage".
  </para>

  <sect1 id="cvs-account">
   <title>Obtaining a CVS Account</title>
   
   <para>
    First, before you can actually make documentation changes, you
    need write access to the <ulink url="&url.php.cvs;">cvs.php.net</ulink>
    CVS repository. You can always checkout a module anonymously,
    but you can not commit changes unless you have an account.
    If you only would like to check files out, you can use
    the read only user name and password. See
    <ulink url="&url.php.anoncvs;">&url.php.anoncvs;</ulink>
    for more information.
   </para>

   <para>
    Also note, that if you have a CVS account on our server,
    you may have no write access to the <literal>phpdoc</literal>
    module. The Karma system controls who have access to what
    repository, so if you have a CVS account but have no Karma
    to write to <literal>phpdoc</literal>, please ask for Karma
    at <ulink url="mailto:&email.group.php;">&email.group.php;</ulink>.
    Note, that who has Karma to write to the PHP source tree,
    has Karma to <literal>phpdoc</literal> as well.
   </para>

   <para>
    Obtaining a CVS account at php.net isn't difficult, but you need
    to do two things:
    <itemizedlist>
     <listitem>
      <simpara>
       Send mail to <ulink
       url="mailto:&email.group.php;">&email.group.php;</ulink>.
       Explain what you would like to do with the CVS account
       (contribute to the PHP documentation). Also give a little
       information and background about yourself so the developers
       understand where you are coming from.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Once someone from the development team responds to your e-mail,
       you will need to go to <ulink
       url="&url.php.cvsaccount;">&url.php.cvsaccount;</ulink> and fill
       out the formal request form.
      </simpara>
     </listitem>

    </itemizedlist>
   </para>

   <para>
    Both of the above steps and other information about CVS accounts
    at cvs.php.net can be found on the same page as the request form,
    <ulink url="&url.php.cvsaccount;">&url.php.cvsaccount;</ulink>.
    Note that this it not an automated process. If you receive no
    reponse after days, do not hesitate to post your request again.
   </para>

  </sect1> 

  <sect1 id="cvs-login">
   <title>CVS Login</title>
   <para>
    Now that you have write access to the CVS repository, let's setup
    a few variables in your <filename>.cvsrc</filename> file, add a
    <literal>CVSROOT</literal> environment variable and
    login to the CVS repository.
   </para>

   <para>
    If you don't already have a <filename>.cvsrc</filename> file in
    your home directory, create one now and add the following lines to
    it. Note that if you use Cygwin, your home directory opens
    first, when running the bash shell (it is the home/username
    directory under your cygwin install directory).
    <informalexample>
     <programlisting>
cvs -z3
update -d -P
checkout -P
diff -u
     </programlisting>
    </informalexample>
   </para>

   <para>
    Each time you issue commands to the CVS repository, you have to
    specify the repository's cvsroot directory like this:
    <informalexample>
     <programlisting>
$ cvs -d :pserver:<parameter>username</parameter>@cvs.php.net:/repository checkout <parameter>phpdoc</parameter>
     </programlisting>
    </informalexample>
   </para>

   <para>
    Instead of telling <command>cvs</command> where the repository is
    each time, you can set a default CVS repository in your <literal
    >CVSROOT</literal> environment variable.
   </para>

   <para>
    For <literal>sh</literal> and <literal>bash</literal>
    users add the following to your <filename>.bashrc</filename>
    or <filename>.profile</filename> file.
    <informalexample>
     <programlisting>
CVSROOT=:pserver:<parameter>username</parameter>@cvs.php.net:/repository
export CVSROOT
     </programlisting>
    </informalexample>
   </para>

   <para>
    For <literal>csh</literal> and <literal>tcsh</literal>
    users add the following to your <filename>.cshrc</filename>
    or <filename>.tcshrc</filename> file.
    <informalexample>
     <programlisting>
setenv CVSROOT :pserver:<parameter>username</parameter>@cvs.php.net:/repository
     </programlisting>
    </informalexample>
   </para>

   <note>
    <para>
     The <literal>CVSROOT</literal> environment variable
     won't be set until the next time you log in.
    </para>
   </note>
   
   <para>
    If you use Windows, use your regular way to add the new
    environment variable, according to the Windows version
    you are using (use the <command>set</command> command
    on Windows 9x, or the Dialog box for setting environment
    variables on Windows 2000).
   </para>

   <para>
    Now that you have the prep work out of they way, you will need to
    login to the CVS repository. Issue the following command:
    <informalexample>
     <programlisting>
$ cvs login
     </programlisting>
    </informalexample>
   </para>

   <para>
    Or, if you don't have your <literal>CVSROOT</literal>
    set, make sure you supply the correct <literal>cvsroot</literal>:
    <informalexample>
     <programlisting>
$ cvs -d :pserver:<parameter>username</parameter>@cvs.php.net:/repository login
     </programlisting>
    </informalexample>
   </para>

   <para>
    Change the <parameter>username</parameter> above to your own
    CVS user name. You will be asked to supply your password. Once
    you successfully login to the CVS respository, your encrypted
    password is stored in the <filename>.cvspass</filename> file
    in your home directory. You won't need to log back into the
    same repository again unless you delete that file (or
    issue a <literal>cvs logout</literal>).
   </para>

  </sect1>

  <sect1 id="cvs-checkout">
   <title>Checking Out a Module</title> 

   <para>
    Now it's time to checkout the <parameter>phpdoc</parameter>
    module. Incidently, a module is a collection of source
    directories and files. Usually it's simply a directory tree in
    the CVS repository.
   </para>

   <para>
    <command>cd</command> to a directory you wish to store the
    <literal>phpdoc</literal> tree under. Wherever you decide to
    put it, a <filename>phpdoc</filename> directory will be created
    there. Issue the following command:
    <informalexample>
     <programlisting>
$ cvs checkout <parameter>phpdoc</parameter>
     </programlisting>
    </informalexample>
   </para>

   <para>
    After some status information about the checkout scrolls by, you
    should have a full working copy of the <literal>phpdoc</literal>
    module.
   </para>

   <note>
    <para>
     You are not completely free to decide where this
     <filename>phpdoc</filename> directory should be. See the
     <link linkend="chapter-tools">Tools and Setup Instructions</link>
     section for more precise information about whether the
     place of this <filename>phpdoc</filename> directory
     is restricted on your system or not.
    </para>
   </note>
   
  </sect1>

  <sect1 id="cvs-update">
   <title>Updating the Tree</title> 

   <para>
    It's a good idea from time to time to update your copy of the
    <parameter>phpdoc</parameter> tree so that you always have the
    latest copy. Currently, changes to the tree are made daily so you
    should always update your copy before making changes yourself.
   </para>

   <para>
    To update your copy, <command>cd</command> to the
    <filename>phpdoc</filename> directory and issue the following
    command:
    <informalexample>
     <programlisting>
$ cvs update
     </programlisting>
    </informalexample>
   </para>

   <para>
    If you only wish to update a particular file or set of files you
    would like to modify, you can pass their filenames along with the
    update command:
    <informalexample>
     <programlisting>
$ cvs update <parameter>file1</parameter> <optional><parameter>file2</parameter></optional>
     </programlisting>
    </informalexample>
   </para>

   <para>
    If the files are located beneath the top level
    <filename>phpdoc</filename> directory, use the relative paths of
    the filenames:
    <informalexample>
     <programlisting>
$ cvs update <parameter>en/functions/file1</parameter> <optional><parameter>en/chapters/file2</parameter></optional>
     </programlisting>
    </informalexample>
   </para>

  </sect1>

  <sect1 id="cvs-status">
   <title>Checking the Status of Files</title>

   <para>
    If you've made several changes to your local copy of
    <literal>phpdoc</literal> and would like to see what files
    have been modified, you can ask <command>cvs</command> what the
    current status of the file or files is.
   </para>

   <para>
    To see the status of all files in the current directory, issue the
    following command:
    <informalexample>
     <programlisting>
$ cvs status -l
     </programlisting>
    </informalexample>
   </para>

   <para>
    This will usually generate a huge list, but you can narrow down
    the status information by supplying <command>cvs</command>
    specific filenames to check the status of:
    <informalexample>
     <programlisting>
$ cvs status <parameter>file1</parameter> <optional><parameter>file2</parameter></optional>
     </programlisting>
    </informalexample>
   </para>

   <para>
    <example>
     <title><command>cvs status</command> example</title>
     <screen>
$ cvs status -l phpdoc/howto/howto.xml     
===================================================================
File: howto.xml         Status: Locally Modified

   Working revision:    1.6
   Repository revision: 1.6     /repository/phpdoc/howto/howto.xml,v
   Sticky Tag:          (none)
   Sticky Date:         (none)
   Sticky Options:      (none)
     </screen>
    </example>
   </para>

  </sect1>

  <sect1 id="cvs-commit">
   <title>Commiting Changes</title> 

   <para>
    Once you have made changes to a file and <emphasis>validated
    your XML</emphasis>, you are ready to commit the changes
    to the CVS repository.
   </para>

   <para>
    When commiting a file or files to the repository, it is polite to
    supply a brief message of what you have changed. You do not need
    to document every single line you changed, that is part of CVS'
    job. However, it is helpful to see a brief summary of what has
    changed from version to version without having to study the file
    itself.
   </para>

   <para>
    To commit a file, issue the following command:
    <informalexample>
     <programlisting>
$ cvs commit -m 'added new blah() function' <parameter>file1</parameter> <optional><parameter>file2</parameter></optional>
     </programlisting>
    </informalexample>
   </para>
   
   <para>
    Sometimes it is more convinient to ommit the
    <parameter>-m</parameter> parameter, as this way
    CVS opens a text editor and you can type in
    your comments there. If you would like to add
    more comments, you can't express on one line
    using <parameter>-m</parameter>, choose this way.
   </para>
  </sect1>

  <sect1 id="cvs-add">
   <title>Adding files or directories</title> 

   <para>
    It is sometimes needed to add files to the English files
    (eg. adding a new appendix), and it is initial for
    translations (adding translated files). To add a file
    you need to put that file to the proper place, where
    you want it to be.
   </para>

   <para>
    To add a file, issue the following command:
    <informalexample>
     <programlisting>
$ cvs add <parameter>file1</parameter> <optional><parameter>file2</parameter></optional>
     </programlisting>
    </informalexample>
   </para>
   
   <para>
    This only shedules the file for addition. To
    complete the addition of the file(s), you need
    to do a commit, as described above.
   </para>
   
   <warning>
    <para>
     Before adding new files, you should choose the new
     file name carefully. There are some limitations to
     file names, because the automatic file name -&gt;
     entity name conversion.
    </para>
   </warning>
  </sect1>

  <sect1 id="cvs-remove">
   <title>Removing files</title> 

   <para>
    It is sometimes needed to remove files from the
    repository. CVS stores the whole history of the
    files, so deleting is not an irreversible step.
    Please be careful when deleting files though.
    A file may be needed for the build process, or
    can store important information for other people.
   </para>

   <para>
    To remove a file, first remove the file from your
    local copy of the CVS repository, and issue the
    following command:
    <informalexample>
     <programlisting>
$ cvs remove <parameter>file1</parameter> <optional><parameter>file2</parameter></optional>
     </programlisting>
    </informalexample>
   </para>
   
   <para>
    This only shedules the file for removing. To
    complete the removing of the file(s), you need
    to do a commit, as described above.
   </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
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"howto.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
-->