=----------------=
Horde: How To Help
=----------------=
Copyright 1999 Ivan E. Moore II <rkrusty@tdyc.com>
Copyright 1999 Mike Hardy <mikeh@spark.com>

This code is licensed under the GNU Public License.
See the file COPYING in this directory.

$Author: bjn $
$Revision: 1.1.2.4 $
$Date: 2000/10/18 19:52:53 $

-------------------------------------------------------------------------

There are many ways in which you can help out in the development of
any of the Horde projects.  The first and best way you are already
doing. Your using them.  One of the keys to a great product is 
it's users.  Without users we can't find bugs nor get feedback on
what's good and what sucks.

There is also certain areas that the developement lacks in.  Support
for operating systems other than Linux are secondary.  Most of the
developers currently primarily use Linux.  (not saying all)  Recently
we've had more luck with testing on other platforms.  This is mainly
directed towards the Windows platform as Windows and Linux at times
act totally different.  (especially between Netscape and Internet 
Explorer).

With this said, one of the best ways you can help is to test.  If
you can help us in any way smooth out the code across all the different
platforms your doing a great service to the project.

Now, if that's not enough and  you want to dig in and help code there's
some things we need to cover.

First off.  You need to remember that when you do get access to the
CVS tree you will have the ability to mess some things up.  Not for
good mind you as CVS is pretty kewl in how it handles things.  I'll
explain more about CVS later on.  You have to remember what your 
doing and becareful what you commit and when you commit it.

Because of this it's recommended (and pretty much an unspoken rule) that
you submit your work to the mailing list for a while until we get a bit
comfortable that the code your submitting is good and that your not
going to go crazy on us or anything.

If your going to be an ongoing contributor your in line for a cvs account.
If your only going to be contributing once in a while, there truely is
no need for you to have one. 

Now, let's break down everything else. 

==========
CVS Layout
==========

The CVS tree has gone through alot of changes lately and is still being
worked out as the new format is implimented.  CVS Is layed out kinda
like this:

horde
     /lib
         /src  <lots of other stuff under here>
imp
   /lib
       /src   <lots of other stuff under here>

etc...

These are the main directories.  horde currently only contains the above
directories and a bunch of stuff below src.  horde is the core component
of all horde based products.  It will be required by all of them, but 
it does not require any of them.  (though it does nothing without one of them)

All modules will reside (after installation) under the horde module like this:

   horde
        /lib
            /src
        /imp
            /lib
                /src
        /troll
              /lib

   etc...

This makes it easy for each module to know exactly where each other is and
how to talk to specific files each may have.  For example, the addressbook
functionality of IMP will be torn out of it and built into it's own module
sometime after 2.2.0 is released.  With it as it's own module it can work
independantly or with any other module.  This would allow people to have
the same addressbook whether they are using IMP or TROLL.

-----======------
Post 2.0.0 Stuff
-----======------

After 2.0.0 is released, alot of things will be changing.  Besides me
ripping the contacts section out of IMP, there will be some major 
database and library work going on.  The whole sessions problem that
we've been fighting with for a long time will finally be worked out.
SSL authentication and Digital Signatures will be coming back.  GNUPG
support will hopefully be added.  (Depending on how well it works)

These are just a few off the top of my head.  And these are just dealing
with IMP.  The other projects within horde will be kicking off again.  Most
of the developers have been focusing on IMP to get 2.0.0 out the door
and at the same time stabalize the library code so that all projects can
progress in the same direction and not duplicate efforts.  This is
important.  

The current horde modules that I know of are:

  IMP       = IMAP webMail Program
  TROLL     = NNTP News Client
  NAG       = TODO list  
  WEBSHOP   = Shopping cart program
  KRONOLITH = Calendar program
  WHUPS     = Bug tracking system
  TURBA     = Enhanced Addressbook
  SKATTEK   = Linux Firewall Management System

These are at least the one's in the CVS tree.  Being able to use any or
all of these at the same time and the ability for them to work within
each other is important.  (using the calander within your todo list so
you can set a date correctly)

=-=-=-=-=-=-=-=-=-=-=-
Obtaining CVS accounts
=-=-=-=-=-=-=-=-=-=-=-

Currently CVS accounts are only going out to key developers.  Those
contributing single translations (one language) do not fit into
this catagory at this time.  Here is a small explanation from Chuck
about this:

   "Until I have either a seperate cvs machine or a nice granular way to do
   access control, I'm not handing out cvs access to people only contributing
   one translation. I'd like to, but it'd be nightmare for me right now and
   it's easy enough to submit the files..."

The best way to submit patchs is to send them either to imp@lists.horde.org
or to dev@lists.horde.org.  If it's a patch to the horde module itself, the
same applies, plus you can also send it to horde@lists.horde.org.

===---===
Using CVS
===---===

(Taken from the Horde FAQ)


IMP uses CVS for source control. If you're curious, there are lots of documents 
available regarding its use and administration. Some of
them may be found at http://www.cyclic.com - they support CVS commercially, even
though it is an open source program. 

IMP CVS is not open to everyone. However, if you submit code a couple times, you
can probably get access if you ask. 

Once you have access, here are the normal things that you will need to do to 
work on the code. 

Before you do anything, you'll need to make sure you have a cvs client 
installed on your machine (check out the Cyclic homepage for
those if you don't have one), and you need to let it know where to get the 
source from. 

For IMP, the CVSROOT is :pserver:username@cvs.horde.org:/cvs/horde

You will then need to log into the CVS server, so it knows who you are and can 
make sure you're allowed to work on the sources. The command to do is:

             'cvs login' 

One other thing you can do, if you want to, is set an environment variable 
called EDITOR to your favorite text editor. That way when you
commit software changes and it asks you to enter a change description, you 
can do is in your favorite editor (rather than vi, which some love, but
I'm lost in) 

Then for work on developmental, bleeding-edge versions:

    1) Check out the code 'cvs co imp'
    2) Work on the code <hack, hack, hack>
    3) Commit any changes with 'cvs commit "filenames"' in the directory the 
       files are in. 

Sometimes, others will make changes and you will need to update your tree so 
that the changes show up in your local sources. You do this with the
'cvs update' command in the imp directory. 

To work with any labelled version (to patch a stable release, for instance): 

    1) Check out the code 'cvs co -r"label" imp'
    2) Work on the code <hack, hack, hack>
    3) Commit any changes with 'cvs commit "filenames"' in the directory the 
       files are in. 

If somebody else also made changes to the labelled version, you can get them in 
your local source tree with a 'cvs update' command issued in the imp directory.

If you are done working with the labelled source branch, and would like to move 
back into the main development source tree, you can issue a 'cvs update -A'
command to get all the new developmental stuff back. 

If you're feeling adventurous, you can try merging code from the developmental 
branch into a labelled branch (to backport a new feature that stabilized,
for instance) by "joining" the two versions. The command for this is: 

   'cvs update -j"version number with changes" "filename to backport into"'

If you're feeling *very* adventurous, and have talked it over with the list, 
you can label the sources at the current stage of development with this
command in the imp directory, 'cvs rtag "label" imp'. 

You can also create a labelled branch (to stabilize a release, or do something 
*really* experimental) with this command in the imp directory:

     'cvs rtag -b "root label to branch at" "branch label" imp' 

Those commands encompass all of the source control voodoo you should ever 
need to know to work with the imp sources. If any of these give you
trouble, mail the CVS list for imp: cvs@lists.horde.org and ask for help. If
you're willing to code for imp, I'm sure someone will lend a hand.

                      - Mike <mikeh@spark.com>

=-=-=-=-=-=-=-=
Other CVS Notes
=-=-=-=-=-=-=-=

If you do end up getting a cvs account here are some tips to help 
keep things happy:

   1> Subscribe to the cvs@lists.horde.org and dev@lists.horde.org mailing
      lists

   2> Label all uploads with your name or initials.  
      When you commit changes to cvs it asks you for comments.  In this
      area do something like this:

      [IEM] fixed the lines in compose.php3 that annoyed Chuck.

      The reason for this is that it first off tells use quickly who
      made the change.  CVS will then tell us exactly what was changed, but
      that requires work.  CVS mails these logs to cvs@lists.horde.org so
      with a quick glance at an email we know who did what.

   3> If your planning on doing anything major please let people know
      in advance.  cvs@lists.horde.org should be an extremly active
      mailinglist.  Developers need to communicate extensivly in order to
      make sure everyone knows what's going on.  This is extremly important
      when your working on key components.

   4> Use the Bug Tracking System.  Currently we are using Bugzilla to
      keep track of bugs.  All new submissions are being cc'd to the
      cvs@lists.horde.org mailinglist so that if we aren't paying attention
      we'll at least get mail about it.  Using the Bugs database will help us
      keep track of issues we are having and where we stand with the
      product.

   5> Remember to advance the library version whenever anything major is
      changed.  This also goes for a ton of minor changes.  This way we
      have some means to break up releases and also track down problems.
      

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
This document was prepared by Ivan E. Moore II
It's far from complete and was written from the top of my head.  
It is intended to help future developers understand where we 
are coming from and what some of our current processes are.
Please send any comments or questions pertaining to this document
to:

        Ivan E. Moore II <rkrusty@tdyc.com>


