<?xml version="1.0" encoding="iso-8859-1"?>
<chapter id="coding_cvs">
  <title>CVS and more.groupware development</title>
  
  <para>more.groupware is developed by many different developers being
    located at different places. To make the source code available and
    manageable, we (like many others) use CVS (Concurrent Versions System,
    <ulink url="http://www.cvshome.org/">http://www.cvshome.org/
  </ulink>
  ).
  This chapter should introduce you to the most basic issues on this.
</para>

<section id="coding_cvs_access">
  <title>Accessing CVS as a developer</title>
  
  <para>If you want to contribute actively, including direct write
    access to the CVS repository, you need to have a sourceforge.net
    account. As soon as we have made you a project member, you can then
    access the CVS repository. This is
    <ulink url="http://sourceforge.net/docman/display_doc.php?docid=768&amp;group_id=1">
    described in detail over at sourceforge.net
  </ulink>
  .But here is a short
  summary for the impatient.
</para>

<section  id="coding_cvs_access_unix">
  <title>CVS/SSH for unix/linux users</title>
  
  <para>You need to have CVS and SSH installed for this to work. Use
    your username and password for your sourceforge.net account in the
    appropriate places.
  </para>
  
  <para>
    <programlisting>export CVS_RSH=ssh
      cvs -d:ext:user@cvs.moregroupware.sourceforge.net:/cvsroot/moregroupware co mgw
    </programlisting>
  </para>
  
  <para>All other actions can later be done inside the created
    directory, without the need for giving the -d option all the
    time. Remember to set the <literal>CVS_RSH</literal> variable all the
    time (e.g. put it in your startup scripts).
  </para>
</section>

<section  id="coding_cvs_access_windows">
  <title>CVS/SSH for windows users (using wincvs)</title>
  
  <para>Use your username and password for your sf.net account in the
    appropriate places.
    <orderedlist>
      <listitem>
        <para>Download WinCVS 1.2 Stable from http://www.wincvs.org/
          and install it.
        </para>
      </listitem>
      
      <listitem>
        <para>Install a command line SSH/Win32 client. Use
          e. g. Alltheweb ftp to find the SSH/Win32 client. Download it and
          unpack it into a folder in your path (e.g. c:\windows). You can use
          this link to do the search directly: <ulink url="http://www.alltheweb.com/search?cat=ftp&amp;cs=utf-8&amp;ftype=4&amp;q=ssh-1.2.14-win32bin.zip">http://www.alltheweb.com/search?cat=ftp&amp;cs=utf-8&amp;ftype=4&amp;q=ssh-1.2.14-win32bin.zip
        </ulink>
        .
      </para>
    </listitem>
    
    <listitem>
      <para>To check out the sources now start WinCVS and
        <orderedlist>
          <listitem>
            <para>go to Menu: Admin/Preferences</para>
          </listitem>
          <listitem>
            <para>
              set CVSROOT to <literal>:ext:user@cvs.moregroupware.sourceforge.net:/cvsroot/moregroupware</literal>
            </para>
          </listitem>
          <listitem>
            <para>set Authentication to SSH server</para>
          </listitem>
          <listitem>
            <para>go to menu: Create/Checkout module...</para>
          </listitem>
          <listitem>
            <para>
              set the module Name to <literal>mgw</literal>
            </para>
          </listitem>
          <listitem>
            <para>select folder you want to have the files in locally</para>
          </listitem>
        </orderedlist>
      </para>
    </listitem>
    
  </orderedlist>
</para>

<para>Committing changes is as easy:
  <orderedlist>
    <listitem>
      <para>Do the updates you want to the MGW file.</para>
    </listitem>
    <listitem>
      <para>Start WinCVS and use the inbuilt file browsing possibilities to find the file you will commit.</para>
    </listitem>
    <listitem>
      <para>Mark the file and choose Modify - Commit Selection to commit it. You should enter a log message to tell other people what you have done.</para>
    </listitem>
    <listitem>
      <para>Choose OK and write in your SF.net password followed by enter in the dos ssh window which pops up.</para>
    </listitem>
    <listitem>
      <para>The file will be submitted and you should get code 0 in the status field if everything went well. </para>
    </listitem>
  </orderedlist>
</para>

</section>

</section>

<section id="coding_cvs_branching">
<title>Branching in CVS</title>

<para>The following informations present an overview what branching in
CVS exactly is. It is not an hands-on documentation, hence there are
no real CVS commands printed, but you will get a picture and then
check the CVS manual :)
</para>

<important>
<para>The information about different branches being
  available for more.gorupware ist not correct (any longer, right
  now). All development takes place on the trunk and there are no stable
  and development releases. This will stay this way until a 1.0 release
  is out. Then we will switch to this approach. Keep this in
  mind!
</para>
</important>

<para>moregroupware right now has one branch and of course one trunk,
the trunk is the main development line, which each CVS project
has. Below something trying to visualize this.
</para>

<para><literallayout>
  _______________    Branch
  /
  /
  -------------------------    Trunk
</literallayout>
</para>

<para>A branch will be split when a major stable release comes out,
for example 0.4.0 or 0.6.0 or 0.8.0 or 1.0.0 or 1.2.0 ...  You can see
that in Moregroupware the second versionnumber indicates wheter it is
a stable release (number is even). Major releases have a 0 in the
third versionnumber. Minor stable releases are for example 0.4.2 or
0.6.8.  A minor release is just a patch on the major release,
increasing one number by each minor release.
</para>

<para>In contrast all second numbers which are odd are the developer
releases.  For example 0.5.0 or 0.7.0 are major developer
releases. 0.5.1 or 0.7.5 were Minor developer releases. So the same
system as for stable releases.
</para>

<para>So why branching when a stable Major release comes out. This is
easy.  Assume you release 0.4.0 and after two weeks some bugs will be
reported.  Normally you would fix the bugs and make a minor stable
release for example 0.4.1, but what if you had started to develop some
major improvements in your product during the last 2 weeks?
</para>

<para>Now you cant integrate your bug fixes and release them, because
you have a very unstable or totally unfunctional new feature in the
source code, which would also be released. So what to do, wait until
the big new feature is also integrated perfectly? NO.
</para>

<para>Instead you make a branch after the major stable release 0.4.0
and fix/commit your bugs only in this branch. This means, when you
commit bugfixes, they will only be in the branch. In the meantime you
can develop t he big new features into your main development line
(trunk) without the problem of interferance with bugfixes. When you
made some bugfixes, just do a release for example 0.4.1 on the branch,
means the new feature which is still broken wont be released, because
the branch dont know this code.
</para>

<para>So far so good. The last thing you must handle is the merging of
your bugfixes in the trunk. Because it would be silly to do bugfixes
two times, one time in your branch and one time in your trunk. So at
some point in your branch, you decide to merge the changes from the
branch into the trunk. In CVS its just a update with some more
parameters. Details you will find in CVS docs around the world.
</para>

<para><literallayout>
  Bugfixes
  _____|_______________    Branch
  /         .
  /            .MERGE(*1)
  -------------------------------    Trunk
  |        |
  betacode   +bugfixes
</literallayout>
</para>

<para>You can see that after a while (and after the bugfixes of
course) the user decided to merge the changes (the bugfixes) into the
trunk. From now on, the bugfixes are also in your main development
line.
</para>

<para>If you want to merge several times within one branch into the
trunk, you must set a tag on the branch indicating that some merge was
done. The next time you merge into the trunk, you define that the
merge should start from the tag you set before, this way things won't
get re-merged over and over again.
</para>

</section>

<section id="coding_cvs_structure">
<title>more.groupware structure in CVS</title>

<important>
<para>The information about different branches being
  available for more.gorupware ist not correct (any longer, right
  now). All development takes place on the trunk and there are no stable
  and development releases. This will stay this way until a 1.0 release
  is out. Then we will switch to this approach. Keep this in
  mind!
</para>
</important>

<para><literallayout>
  rel0.4-branch                       rel0.6-branch
  _____________________                ____________....
  /     |         |                    /    |
  /    rel0.4.1   rel0.4.x             /  rel0.6.1
  ------------------------------------------------------....Trunk
  |             |           |          | 
  rel0.4.0     rel0.5.0   rel.0.5.x   rel0.6.0
</literallayout>
</para>

<note>
<para>The graph above shows the release tags, there are also
  some merge tags in the branches for knowing when there was a merge in
  the trunk. Tag names would be branch_0_4-intotrunk1 or
  branch_0_4-intotrunk2 or branch_0_4-intotrunk3. This way we can have
  long branches without re-merge allready merged stuff and getting
  conflicts.
</para>
</note>

<para>To see a real-life example, here is the CVS history of the
INSTALL file which is inside the moregroupware package.
<figure>
  <title>part of the CVS structure</title>
  <graphic fileref="images/coding_cvs/branchexample.png"/>
</figure>
</para>

<para>You can see that at some time, a release branch will be made
(here branch-0_4) and then the bugfixes go to this branch, while the
main development line will be continued with new features. The black
boxes are the tags, moregroupware knows two tags, release tags and
merge tags. The "*_intotrunk*" tags are merge tags. The blue boxes are
the file versions, so each commit generates a new blue box with a file
revision number. When you make a bugfix on a branch and commit it, the
blue box will be connected with the branch, otherwise it will be put
to the end of the main line (HEAD).
</para>

<note><itemizedlist>
  <listitem>
    <para>two development lines at any time (one branch and trunk)</para>
  </listitem>
  <listitem>
    <para>All major rel. and minor dev rel. will be tagged on trunk</para>
  </listitem>
  <listitem>
    <para>Minor stable release allways on some branch</para>
  </listitem>
</itemizedlist>
</note>

</section>
</chapter>
