<?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 modules,
   the name of the main module used by the PHP Documentation
   people is <literal>phpdoc</literal>. There are other
   modules used for translations, each named after the
   language code of the translation (eg. <literal>phpdoc-de</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
   to 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 provide a short summary here 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 one of the <link linkend="chapter-maillist">mailing
   lists</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
   walkthrough to help you get started checking out the
   <literal>phpdoc</literal> and your translation's tree and commiting
   your changes. The complete CVS documentation can be found
   at <ulink url="&url.cvs;">&url.cvs;</ulink>.
  </para>

  <para>
   CVS tutorials faqs and even a complete book 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>
    <listitem>
     <simpara><ulink url="&url.cvs.faq;">CVS Faq</ulink></simpara>
    </listitem>
    <listitem>
     <simpara><ulink url="&url.cvs.book;">The CVS Book</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". <literal>cvs
   --help</literal> can also help you.
  </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>
    and/or to your translation's module. The Karma system controls
    who have access to what module, so if you have a CVS account
    but have no Karma to write, 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 a mail to the PHP Group
    and ask for consideration.
   </para>

  </sect1> 

  <sect1 id="cvs-login">
   <title>CVS Login</title>
   <para>
    Now that you have write access to the CVS module, 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. Also don't
     forget to change the <parameter>username</parameter>
     part to your CVS user name.
    </para>
   </note>
   
   <para>
    If you have 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>). You can work for months
    without logging in again, as this file will remain there with
    the same content, leaving you logged in.
   </para>

  </sect1>

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

   <para>
    Now it's time to checkout the <parameter>phpdoc</parameter>
    module first. 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. Be prepared to wait for a long time for this to complete,
    as the module contains many small files.
   </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>
   
   <para>
    If you would like to work with a translation group, checking
    out the <filename>phpdoc</filename> module is not enough (though
    required), as it only contains the files needed for building the
    manual, and the English version of the source files. There are
    other modules for translations, named after the language
    code of the translation, with the pattern:
    <literal>phpdoc-LANGCODE-dir</literal>. LANGCODE is most of the time
    a two letter code, but there can be exceptions. So if you would
    like to work for the Italian translation group, you need to check
    out the <filename>phpdoc-it-dir</filename> module too. The place where
    you should check out this module is strictly defined. You should
    check out any translation's module <emphasis>under</emphasis> the
    <filename>phpdoc</filename> directory you have created above with
    your previous checkout. So go to the <filename>phpdoc</filename>
    folder and issue a command like:
    <informalexample>
     <programlisting>
$ cvs checkout <parameter>phpdoc-it-dir</parameter>
     </programlisting>
    </informalexample>
   </para>
   <para>
    Substitute the "it" part with your language code. You can
    check out any number of translations as you need, and you need not
    check out any translation if you would not like to work with it. To
    work with the English files, no translation module needs to be checked
    out.
   </para>
   <note>
    <title>Note: Brazilian Portuguese</title>
    <para>
     The format of this translations name differs from the rest in that it's
     called <literal>pt_BR</literal>.
    </para>
   </note>
   <para>
    You also have the ability of checking out the complete build
    infrastructure and all the languages. You can do this with:
    <informalexample>
     <programlisting>
$ cvs checkout <parameter>phpdoc-all</parameter>
     </programlisting>
    </informalexample>
    The result of this command will be a phpdoc-all folder with all the
    stuff you requested.
   </para>
  </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
    <filename>phpdoc</filename> 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>
   
   <note>
    <para>
     If you have also checked out any translation modules, those
     will also be updated with the command shown above, so there
     is no need to separately update your checked out translation
     modules.
    </para>
   </note>

   <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/language/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 explanation of the new ..blah.. feature' <parameter>file1</parameter> <optional><parameter>file2</parameter></optional>
     </programlisting>
    </informalexample>
   </para>
   
   <para>
    Sometimes it is more convenient to omit 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 that you can't express on one line
    using <parameter>-m</parameter>, choose this way.
   </para>

   <para>
    For more information on the conventions used in the XML files
    that you commit, see <xref linkend="chapter-conventions" />.
   </para>
   
   <note>
    <para>
     Please check twice, that you commit changes in the human language
     the file is written in. The <filename>phpdoc</filename> module itself
     only contains English files, so do not commit any files in other
     languages, unless others agreed on the <link linkend="chapter-maillist">mailing
     list</link>. The translation modules should not contain manual
     content XML files with only English text in them, as this makes
     translations harder to maintain, so do not commit any English only
     files to translation trees. If you are not sure you won't make a
     mistake with committing, please ask on the appropriate
     <link linkend="chapter-maillist">mailing list</link>.
    </para>
   </note>
  </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 schedules 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 delete the file from your
    local copy of the CVS module, and issue the
    following command:
    <informalexample>
     <programlisting>
$ cvs remove <parameter>file1</parameter> <optional><parameter>file2</parameter></optional>
     </programlisting>
    </informalexample>
   </para>
   
   <para>
    This only schedules 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
-->