[Sommaire] [Imprimer]

   1  =============================
   2   Horde Development Resources
   3  =============================
   4  
   5  :Last update:   $Date: 2006/02/01 09:20:29 $
   6  :Revision:      $Revision: 1.7.10.1 $
   7  :Author:        Ivan E. Moore II <rkrusty@tdyc.com>, Mike Hardy
   8                  <mikeh@spark.com>
   9  :Contact:       horde@lists.horde.org
  10  
  11  .. contents:: Contents
  12  .. section-numbering::
  13  
  14  Online resources for developing with Horde (including Horde Framework API
  15  documentation) are available at:
  16  
  17     http://dev.horde.org/   
  18  
  19  
  20  Hacking on Horde from CVS
  21  =========================
  22  
  23  Horde and its modules use CVS for source control.  CVS is well-documented, but
  24  the manual page assumes you already know how it works.  An excellent guide to
  25  getting started with CVS is "Open Source Development with CVS" by Karl Fogel.
  26  It's published by Coriolis, and the technical part of the book is available
  27  for free on the Web at
  28  
  29     http://cvsbook.red-bean.com/
  30  
  31  The paper version includes chapters on organizing and managing Open Source
  32  development.  You can obtain a CVS client for your operating system at
  33  CVSHOME, at
  34  
  35     http://www.cvshome.org/downloads.html
  36  
  37  of them may be found at http://www.cyclic.com - they support CVS commercially,
  38  even though it is an open source program.
  39  
  40  You will need a CVS client to do any of the following (check out the Cyclic
  41  homepage if you don't have one).
  42  
  43  For those already familiar with CVS, the anonymous CVSROOT is::
  44  
  45     :pserver:cvsread@anoncvs.horde.org:/repository
  46  
  47  
  48  Downloading Horde modules from CVS
  49  ----------------------------------
  50  
  51  You will want to do this if you want bleeding edge code.
  52  
  53  1. Go to the directory you want to download the code to::
  54  
  55        cd ~/work
  56  
  57  2. Set ``CVSROOT`` to the location of the CVS repository.  You could also pass
  58     cvs the name of the CVS root with the ``-d`` option.  Be sure to note the
  59     colon ``:`` in front of ``pserver``.
  60  
  61     (in sh, ksh, bash, zsh)::
  62  
  63        CVSROOT=:pserver:cvsread@anoncvs.horde.org:/repository
  64        export CVSROOT
  65  
  66     (in csh, tcsh)::
  67  
  68        setenv CVSROOT :pserver:cvsread@anoncvs.horde.org:/repository
  69  
  70  3. Login to the anonymous CVS repository.  When prompted for a password, enter
  71     ``horde``::
  72        
  73        cvs login
  74  
  75  4. Check out the module you want to download from the repository.  Replace
  76     ``MODULE`` with horde, imp, turba, troll, and so forth.  (The ``-z3`` tells
  77     cvs to compress the data it sends over the network, uncompressing it when
  78     you ????::
  79  
  80        cvs -z3 co MODULE
  81  
  82     If you want to check out a particular branch of a module (for example, the
  83     ``RELENG_3`` branch of IMP), include the branch tag like so, replacing
  84     ``TAG`` with the name of the branch::
  85  
  86        cvs -z3 co -r TAG MODULE
  87  
  88  5. As you work with the software, you can periodically update your tree to
  89     match the master tree at any time, from the top directory of the
  90     module.  Using ``horde`` as an example module::
  91  
  92        cd ~/work/horde
  93        cvs -z3 update
  94  
  95  
  96  Obtaining a CVS account
  97  -----------------------
  98  
  99  If you're going to be a regular contributor to Horde, then you can request a
 100  CVS account in order to commit your changes to the repository yourself.  (If
 101  you're only going to be contributing once in a while, there truly is no need
 102  for you to have one, as posting your changes to the application's mailing list
 103  will suffice to get your changes reviewed and included.)
 104  
 105  If you do get commit access to the CVS tree, you will have the ability to mess
 106  some things up.  Not for good, mind you, as CVS allows updates to be backed
 107  off, but you still need to remember what you're doing and be careful what you
 108  commit and when you commit it.  Because of this, we prefer that you submit
 109  your work to the mailing list for a while so we can tell you know what you're
 110  doing.
 111  
 112  If you're not a committer, the best way to submit a patch is to send it either
 113  to the application's mailing list or to dev@lists.horde.org.  For more
 114  information on Horde mailing lists, see
 115  
 116     http://www.horde.org/mail/
 117  
 118  
 119  Committing changes to CVS
 120  -------------------------
 121  
 122  Once you have a CVS account, you will need to log into the CVS server so it
 123  knows who you are and can grant you the appropriate rights to work on the
 124  sources.
 125  
 126  The ``CVSROOT`` is different for committers; instead of the repository listed
 127  above, set ``CVSROOT`` to::
 128  
 129     :ext:USERNAME@cvs.horde.org:/repository
 130  
 131  replacing ``USERNAME`` with your cvs username.
 132  
 133  The committers' repository does not use pserver.  You will need to have ssh
 134  installed on your system, and have arranged with one of the core developers to
 135  put your SSH key on the system.  If you have not done this, talk to one of the
 136  core developers.
 137  
 138  To get cvs to use ssh, you will need to set the environment variable
 139  ``CVS_RSH`` to ``ssh`` in your shell.
 140  
 141  You do not need to do ``cvs login``; you will be prompted for the passphrase
 142  for your SSH key whenever you access the repository.
 143  
 144  You may also wish to set the environment variable ``EDITOR`` to point to your
 145  favorite text editor. This way when you commit software changes and it asks
 146  you to enter a change description, you can do so in your favorite editor.
 147  
 148  Then, for work on developmental, bleeding-edge versions:
 149  
 150  1) Check out the code by typing ``cvs co MODULE``
 151  2) Work on the code <hack, hack, hack>
 152  3) Commit any changes with ``cvs commit FILENAMES`` in the directory the files
 153     are in.
 154  
 155  Sometimes, others will make changes and you will need to update your tree so
 156  the changes show up in your local sources.  You do this with the ``cvs
 157  update`` command in the horde directory.  Please be sure to update your tree
 158  regularly; merging changes is considerably more work than running ``cvs
 159  update``.
 160  
 161  To work with any tagged branch (to patch a stable release, for instance):
 162  
 163  1) Check out the code with ``cvs co -r TAG MODULE``
 164  2) Work on the code <hack, hack, hack>
 165  3) Commit any changes with ``cvs commit FILENAMES`` in the directory the files
 166     are in.
 167  
 168  If somebody else also makes changes to the labeled version, you can get them
 169  in your local source tree with the ``cvs update`` command issued in the module
 170  directory.
 171  
 172  If you are done working with the labeled source branch, and would like to move
 173  back into the bleeding-edge development source tree, you can issue the command
 174  ``cvs update -A`` to update everything to the current ``HEAD`` version.
 175  
 176  (We used to document how to merge code from HEAD into a labeled branch here,
 177  but since it was heavily peppered with "talk to core developers first", it's
 178  been elided to prevent errors of experimentation.  If you think you need to do
 179  that, you have to talk to core developers anyhow -- they'll explain how.)
 180  
 181  
 182  Other CVS Notes
 183  ---------------
 184  
 185  If you do end up getting a CVS account, here are some tips to help keep things
 186  going smoothly:
 187  
 188  1. Subscribe to the cvs@lists.horde.org and dev@lists.horde.org mailing lists.
 189  
 190  2. Be sure to modify the file ``docs/CHANGES`` to reflect the changes to the
 191     code you are committing.
 192  
 193  3. If you're planning on doing anything major, please let people know in
 194     advance on the dev@ or application mailing lists as appropriate.
 195  
 196     Developers need to communicate extensively in order to make sure everyone
 197     knows what's going on.  This is extremely important when you work on key
 198     components.
 199  
 200  4. Use the Bug Tracking System on http://bugs.horde.org.  All new submissions
 201     are being cc'd to the bugs@lists.horde.org mailing list so that if we aren't
 202     paying attention, we'll at least get mail about it.  Using the Bugs
 203     database helps us keep track of issues we are having and where we stand
 204     with the product.
 205  
 206  5. Remember to advance the library version whenever anything major is changed.