[dev] Updating docs/HELP

[Josh Miller]

Quoting Chuck Hagenbuch <chuck@horde.org>:

> Quoting Josh Miller <joshlists@nebonet.com>:
>
> > There is already a copy of it in horde/docs/ but I agree that it shou=
ld
> > be split up.
> >
> > Attached is a possible way of doing this (with spelling, grammar, and=
 a
few
> > other updates) though they're not ready for committing as the footers
and
> > headers need to be changed on all of them...
>
> Plain text? Attachments tend to get stripped out...

Well too bad for the attachments, eh?

The four files are HELP, CVS, LISTS, and TOGETHER...I really have no idea
what to call the last one. (or how to list them all here in a sane way)

-
Josh

HELP

=----------------=
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 the top directory.

Last Updated: 06/23/2001

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

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. You're using
them. One of the keys to a great product is its users. Without users we
can't
find bugs or get feedback on what's good and what's bad.

There are also certain areas that the development 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 can act completely different (and Netscape and
Internet Explorer even more so).

With this said, one of the best ways you can help is to test. If you can
help
us smooth out the code across all (or even any) platforms, you're doing a
great service to the project.

Now, if that's not enough and you want to dig in and help code, you should
first subscribe to the project lists and read the Coding Standards (see the
LISTS and CODING_STANDARDS files in this directory.

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
=
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>

CVS

=----------------=
HORDE: CVS
=----------------=
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 the top directory.

Last Updated: 06/23/2001

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

Horde and its modules use 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.

You will need a CVS client to do any of the following (check out the Cyclic
homepage if you don't have one).

The CVSROOT is :pserver:username@cvs.horde.org:/cvs/horde

===================
Downloading modules
===================

You will want to do this if you want bleeding edge code.

Go to the directory you want to download the code to:

   i.e. 'cd ~/work'

Use the following commands:

   'cvs -d :pserver:cvsread@cvs.horde.org:/cvs/horde login'
   'cvs -z3 -d :pserver:cvsread@cvs.horde.org:/cvs/horde co horde'

The password, when you are asked for it, is "horde".
Now change directories to horde and download the modules you want.

   `cd horde'
   'cvs -z3 -d :pserver:cvsread@cvs.horde.org:/cvs/horde co <MODULE>'

Replace <MODULE> with imp, turba, troll, etc...

To update your tree at any time to match the master tree, switch to the
directory where you have downloaded horde:

   i.e. 'cd ~/work/horde'

and type:

   'cvs -z3 update –d'

=-=-=-=-=-=-=-=-=-=-=-=
Obtaining a CVS account
=-=-=-=-=-=-=-=-=-=-=-=

If you're going to be a constant contributor, then you can request a CVS
account. If on the other hand you're only going to be contributing once in a
while, there truly is no need for you to have one, as posting your changes
to
the mailing list will get them integrated as easily, if not easier.

If you do get commit 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 updates, but you still need to remember what you're doing and be
careful 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 so we can tell you know
what
you're doing (yes, we're slightly paranoid about this).

Currently CVS accounts are only being provided to key developers. Those
contributing single translations (one language) do not fit into this
category
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 a patch is to send it either to the projects list or
to
dev@lists.horde.org (see the LISTS file in this directory).

--------=========--------
Committing changes to CVS
--------=========--------

If you do have a CVS account you will need to do to a few things to work on
the code.

You will need to log into the CVS server so it knows who you are and can
grant
you the appropriate rights to work on the sources. The command to do is:

       'cvs login'

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

Then, for work on developmental, bleeding-edge versions:

  1) Check out the code by typing 'cvs co modulename'
  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
the changes show up in your local sources. You do this with the 'cvs update'
command in the horde directory.

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

  1) Check out the code with 'cvs co -r"label" modulename'
  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 makes changes to the labeled version, you can get them
in your local source tree with a 'cvs update' command issued in the module
directory.

If you are done working with the labeled 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 labeled branch (to backport a new feature that has 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 module directory, 'cvs rtag "label" modulename'.

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

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

These commands encompass all of the source control voodoo you should ever
need
to know to work with the project sources. If any of these give you trouble,
mail the CVS list for horde: cvs@lists.horde.org and ask for help.
If you're willing to code for horde, 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 do something like this:

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

     The reason for this is that it tells us 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 you're planning on doing anything major, please let people know in
     advance. cvs@lists.horde.org should be an extremely active mailing
list.

     Developers need to communicate extensively in order to make sure
everyone
     knows what's going on. This is extremely 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 mailing list so that if we aren't paying attention,
     we'll at least get mail about it. Using the Bugs database helps 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>

LISTS

=----------------=
HORDE: E-Mail Lists
=----------------=

Last Updated: 06/23/2001

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

(Taken from the horde website)

These are the current Horde-related mailing lists.
You must be subscribed to post to any of them.

To subscribe, send an empty email to listname-subscribe@lists.horde.org.

Make sure to actually substitute the name of the list that you want to
subscribe to for "listname"!

Most of these lists are archived on MARC (http://marc.theaimsgroup.com)
under
the WWW category.

===================
General Horde Lists
===================

announce@lists.horde.org is for Horde-related announcements.

horde@lists.horde.org is for general discussion of the Horde Project.
  Discussion of the Horde Core module, new modules, or issues relevant to
the
  Horde project as a whole are appropriate here.

---------========---------
Application-specific Lists
---------========---------
imp@lists.horde.org is for help with IMP, general discussion, patches, and
  other IMP development issues.

kronolith@lists.horde.org is for help with Kronolith, general discussion,
  patches, new ideas, PHP MCAL issues, and other items of interest to people
  working on or using Kronolith.

jonah@lists.horde.org is for help with Jonah, general discussion, patches,
new
  channels, content backends, and other items of interest to fellow Jonah
  users.

skattek@lists.horde.org is for general discussion and development of the
  Skattek Module. This will be a web based Linux firewall management module
  for the Horde Project.

troll@lists.horde.org is for general discussion and development of the Troll
  Module. This will be the web-based news reader for the Horde Project.

turba@lists.horde.org is for general discussion and development of the Turba
  Module. This will be the new contacts module for the Horde Project.

whups@lists.horde.org is for general discussion and development of Whups,
the
  Horde project management system.

chora@lists.horde.org is for general discussion and development of Chora,
the
  Horde CVS front-end module.

nag@lists.horde.org is for general discussion and development of Nag, the
  Horde task list manager.

gollem@lists.horde.org is for general discussion and development of Gollem,
  the Horde account manager.

=-=-=-=-=-=-=-=-=
Development Lists
=-=-=-=-=-=-=-=-=
dev@lists.horde.org is the general Horde development list. Horde developers
  discuss various design and implementation issues here.

cvs@lists.horde.org gets emailed every time someone commits a change to the
  Horde cvs tree.

bugs@lists.horde.org is basically an archive of all submissions/changes to
the
  bug database (http://bugs.horde.org). The main purpose for this list is an
  archive of all reports/fixes that come across the bug tracking system.

doc@lists.horde.org is for discussion concerning documentation for the Horde
  project.

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
=
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>

TOGETHER

=-----------------------------=
HORDE: How it all fits together
=-----------------------------=
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 the top directory.

Last Updated: 06/23/2001

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

================
Directory Layout
================

Horde is the core component of all horde-based modules. It is required by
all
of them, but does not require any of them (although it does nothing without
at
least one of them).

Horde and all modules use the following directory layout.

project_name
  /config
  /docs
  /graphics
  /lib
  /locale
  /scripts
  /templates

There may be more directories if they are logically needed, or less, if some
are not needed (i.e. the module uses no graphics or scripts).

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

.../horde
     /imp
     /turba
     /troll
     etc...

This makes it easy for horde to know where each module is located and how to
integrate with them. For example, turba, the address book module, can work
independently or with another module. This allows users to have the same
address book whether they are using imp, troll, and/or some other module.

-------=======-------
Current horde modules
-------=======-------

CHORA     = CVS Viewer
GOLLEM    = FTP Client -> Account Manager
IMP       = Mail Client
JONAH     = Portal
KRONOLITH = Calendar
NAG       = TODO List
NIC       = Network Utilites
TROLL     = NNTP News Client
TURBA     = Address Book / Contact Manager
WHUPS     = Bug Tracking

These are the modules in the CVS tree that are at least somewhat useable.
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 (i.e. using the calendar within
your todo list so you can set a date correctly).

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
=
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>