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

 <chapter xml:id="chapter-svn" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Working with SVN</title>

  <para>
   The PHP documentation is maintained using <link
   xlink:href="&url.svn;">SVN</link> (<emphasis>Subversion</emphasis>).
   SVN 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 SVN system contains a central server, where all the files
   are stored. A SVN server can host many modules,
   the name of the main module used by the PHP Documentation
   people is <literal>doc-base</literal> which contains the
   base (like the tools to validate the DocBook, this HOWTO, etc.). 
   And then there are other modules for each language, each named after the
   language code (eg. <literal>de</literal> for German).
   To access this server, you need a SVN 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 SVN
   client asks for your short comment about why this commit
   was necessary. You can provide a short summary here about what
   was changed. The SVN 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 SVN
   client or the web interface at
   <link xlink:href="&url.php.svn;">&url.php.svn;</link>. You can
   also delete a file or add one with your SVN client,
   if you see it is needed.
  </para>

  <para>
   This section is not intended to be a SVN tutorial, only a quick
   walkthrough to help you get started checking out the
   <literal>phpdoc</literal> and your translation's tree and committing
   your changes. The complete SVN documentation can be found
   at <link xlink:href="&url.svn;">&url.svn;</link>.
  </para>

  <para>
   SVN tutorials faqs and even a complete book can be found at:
   <itemizedlist>
    <listitem>
     <simpara><link xlink:href="&url.svntut1;">&url.svntut1;</link></simpara>
    </listitem>
    <listitem>
     <simpara><link xlink:href="&url.svn.faq;">SVN Faq</link></simpara>
    </listitem>
    <listitem>
     <simpara><link xlink:href="&url.svn.book;">The SVN Book</link></simpara>
    </listitem>
   </itemizedlist>
  </para>
  
  <para>
   You can also type <literal>man svn</literal> anytime
   you would like to get help about your SVN client. This
   brings up a help text called a "manpage". <literal>svn
   --help</literal> can also help you.
  </para>

  <sect1 xml:id="svn-account">
   <title>Obtaining a SVN Account</title>
   
   <para>
    First, before you can actually make documentation changes, you
    need write access to the <link xlink:href="&url.php.svn;">svn.php.net</link>
    SVN 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 simply check
    out the sources anonymously. See the 
    <link xlink:href="&url.php.svn;">php.net SVN page</link>
    for more information.
   </para>

   <para>
    Also note, that if you have a SVN 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 SVN account
    but have no Karma to write, please ask for Karma at
    <link xlink:href="mailto:&email.phpdoc;">&email.phpdoc;</link>.
    Note, that who has Karma to write to the PHP source tree,
    has Karma to <literal>phpdoc</literal> as well.
   </para>

   <para>
    Obtaining a SVN account at php.net isn't difficult, but you need
    to do two things:
    <itemizedlist>
     <listitem>
      <simpara>
       First, send an mail to <link
       xlink:href="mailto:&email.phpdoc;">&email.phpdoc;</link>.
       Explain what you would like to do with the SVN 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 <link
       xlink:href="&url.php.svnaccount;">&url.php.svnaccount;</link> and fill
       out the formal request form.
      </simpara>
     </listitem>
    </itemizedlist>
   </para>

   <para>
    Both of the above steps and other information about SVN accounts
    at svn.php.net can be found on the same page as the request form,
    <link xlink:href="&url.php.svnaccount;">&url.php.svnaccount;</link>.
    Note that this it not an automated process. If you receive no
    response after days, do not hesitate to post a mail to the PHP Group
    and ask for consideration.
   </para>

  </sect1> 

  <sect1 xml:id="svn-login">
   <title>SVN Login</title>
   <para>
    Now that you have write access to the SVN module, let's setup
    a few variables in your <filename>.subversion/config</filename> file:
   </para>
   
   <!-- TODO: Talk about why we want this stuff. -->

   <para>
    If you don't already have a <filename>.subversion/config</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>
[auto-props]
*.c = svn:eol-style=native;svn:keywords=Id Rev Revision
*.cpp = svn:eol-style=native;svn:keywords=Id Rev Revision
*.h = svn:eol-style=native;svn:keywords=Id Rev Revision
*.m = svn:eol-style=native;svn:keywords=Id Rev Revision
*.dsp = svn:eol-style=CRLF
*.dsw = svn:eol-style=CRLF
*.sh = svn:eol-style=native;svn:executable;svn:keywords=Id Rev Revision
*.txt = svn:eol-style=native;svn:keywords=Id Rev Revision
*.png = svn:mime-type=image/png
*.jpg = svn:mime-type=image/jpeg
Makefile = svn:eol-style=native
*.php = svn:eol-style=native;svn:keywords=Id Rev Revision
*.xml = svn:eol-style=native;svn:keywords=Id Rev Revision
*.sql = svn:eol-style=native;svn:keywords=Id Rev Revision
*.tpl = svn:eol-style=native;svn:keywords=Id Rev Revision
*.am = svn:eol-style=native;svn:keywords=Id Rev Revision
*.in = svn:eol-style=native;svn:keywords=Id Rev Revision
*.m4 = svn:eol-style=native;svn:keywords=Id Rev Revision
*.s = svn:eol-style=native;svn:keywords=Id Rev Revision
     </programlisting>
    </informalexample>
   </para>

   <para>
    Each time you issue commands to the SVN repository, you have to
    specify the repository's svnroot directory. The following uses
    SVN externals to checkout the English version of the PHP manual
    into a directory named <filename>phpdoc</filename>
    <informalexample>
     <programlisting>
$ svn checkout http://svn.php.net/repository/phpdoc/modules/doc-en phpdoc
     </programlisting>
    </informalexample>
   </para>
  </sect1>

  <sect1 xml:id="svn-checkout">
   <title>Checking Out a SVN Module</title>

   <para>
    Now it's time to checkout the <parameter>phpdoc</parameter>
    module first. Incidentally, a module is a collection of source
    directories and files. Usually it's simply a directory tree in
    the SVN 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>
$ svn checkout http://svn.php.net/repository/phpdoc/modules/doc-en phpdoc
     </programlisting>
    </informalexample>
   </para>
   
   <!-- FIXME: This topic deserves better information. Also, talk about trunk and sparse checkouts. Somewhere. -->
   <note>
    <title>The directory named phpdoc</title>
    <para>
     The above command does create a directory named phpdoc, however, the
     name can be anything you wish. <filename>phpdoc/modules/doc-en</filename>
     is an SVN external that essentially checks out the English sources
     along with the associated tools found in <filename>doc-base</filename>.
     Then, the last segment in the command (<filename>phpdoc</filename>) is
     the local directory name on your hard drive.
    </para>
    <para>
     We refer to the directory as <filename>phpdoc</filename> to keep things
     simple, and default to SVN externals to also keep things simple. It
     actually checks out <filename>en/trunk/</filename> from SVN, as opposed
     to a branch or tag, and renames it to simply <filename>en/</filename>.
    </para>
   </note>

   <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 sources is a little different. Again, using SVN externals we
    simply change phpdoc-en to phpdoc-{langcode} where {langcode} is
    for the desired language. These translations include English so 
    there is no need to checkout both seperately. For example, for Italian:
    <informalexample>
     <programlisting>
$ svn checkout http://svn.php.net/repository/phpdoc/modules/doc-it phpdoc-it
     </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>
$ svn checkout http://svn.php.net/repository/phpdoc/modules/doc-all phpdoc-all
     </programlisting>
    </informalexample>
    The result of this command will be a phpdoc-all folder with all the
    stuff you requested.
   </para>
   <!-- TODO: Mention sparse checkouts, branches and tagging. -->
  </sect1>

  <sect1 xml:id="svn-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>
$ svn 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>
$ svn update file1 file2
     </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>
$ svn update en/language/file1 en/chapters/file2
     </programlisting>
    </informalexample>
   </para>

  </sect1>

  <sect1 xml:id="svn-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>svn</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>
$ svn status
     </programlisting>
    </informalexample>
   </para>

   <para>
    This will generate a list of modified files, new files that
    aren't checked into SVN, and more. Getting the status of individual
    files (and directories) is just as sinple:
    <informalexample>
     <programlisting>
$ svn status file1 file2
     </programlisting>
    </informalexample>
   </para>

   <para>
    <example>
     <title><command>svn status</command> example</title>
     <screen>
$ svn status -v phpdoc/howto/howto.xml

M           289871   289871 philip       howto/vcs.xml
     </screen>
    </example>
   </para>

  </sect1>

  <sect1 xml:id="svn-commit">
   <title>Committing 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 SVN repository.
   </para>

   <para>
    When committing 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 SVN's
    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>
$ svn commit -m 'added explanation of the new ..blah.. feature' file1 file2
     </programlisting>
    </informalexample>
   </para>
   
   <para>
    Sometimes it is more convenient to omit the
    <parameter>-m</parameter> parameter, as this way
    SVN 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>
   <!-- TODO: talk about SVN_EDITOR -->
   <!-- TODO: talk about bug tracker conventions in commit emails -->

   <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 xml:id="svn-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>
$ svn add file1 file2
     </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 xml:id="svn-remove">
   <title>Removing files</title> 

   <para>
    It is sometimes needed to remove files from the
    repository. SVN 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 SVN module, and issue the
    following command:
    <informalexample>
     <programlisting>
$ svn remove file1 file2
     </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>
   
   <!-- TODO: Add info about rename -->
   <!-- TODO: Removing files is rarely recommended, as it loses history. Mention this. Also think about how this differs from CVS Attic -->
   
  </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
-->