README.developers

   1 =======================================================================
   2 *** README.developers - JACK development practices                  ***
   3 =======================================================================
   4
   5 :Version: $Id$
   6 :Formatting: restructured text, http://docutils.sourceforge.net/rst.html
   7
   8 What is this?
   9 -----------------------------------------------------------------------
  10
  11 This file is a collection of practices and rules for JACK
  12 development. If you have questions, or would like to make
  13 changes, raise the issue on jackit-devel (see
  14 http://lists.sourceforge.net/lists/listinfo/jackit-devel ).
  15
  16
  17 Contents
  18 -----------------------------------------------------------------------
  19
  20 - What is this?
  21 - Version numbers
  22 - Important files for developers
  23 - Sending patches
  24 - CVS Access
  25 - Decision Process
  26
  27
  28 Important files for developers
  29 -----------------------------------------------------------------------
  30
  31 AUTHORS
  32         List of contributors. If you have contributed code, mail Paul
  33         Davis to get your name added to the list, or if you have
  34         CVS-access, help yourself. :) Also remember to update the
  35         per source file copyright statements when committing changes.
  36
  37 README.developers
  38         This file.
  39
  40 TODO
  41         A one file mini-bugzilla for JACK developers. Note: this file
  42         is no longer actively updated - please use the Mantis
  43         bugtracker instead, see http://jackit.sourceforge.net/dev/ .
  44
  45 libjack/ChangeLog
  46         A list of _all_ changes to the public interface!
  47
  48
  49 Version numbers
  50 -----------------------------------------------------------------------
  51
  52 JACK's package version
  53 ~~~~~~~~~~~~~~~~~~~~~~
  54
  55 JACK's package version is set in configure.in, and consists of
  56 major, minor and revision numbers. This version should be
  57 updated whenever a non-trivial set of changes is committed
  58 to CVS:
  59
  60 major version
  61    ask on jackit-devel :)
  62
  63 minor version
  64    incremented when any of the public or internal
  65    interfaces are changed
  66
  67 revision
  68    incremented when implementation-only
  69    changes are made
  70
  71 Client API versioning
  72 ~~~~~~~~~~~~~~~~~~~~~
  73
  74 JACK clients are affected by two interfaces, the JACK Client API (libjack)
  75 and the JACK Client Protocol API (interface between jackd and
  76 libjack). The former one is versioned using libtool interface
  77 versioniong (set in configure.in). This version should be updated
  78 whenever a set of changes affecting the interface is committed
  79 to CVS:
  80
  81 current
  82     incremented whenever the public libjack API is changed
  83
  84 revision
  85     incremented when the libjack implementation is changed
  86
  87 age
  88     current libjack is both source and binary compatible with
  89     libjack interfaces current,current-1,...,current-age
  90
  91 Note! It was decided in January 2003 that current interface number
  92       will remain as zero until the first stable JACK version
  93       is released.
  94
  95 JACK Client Protocol is versioned... <TBD>.
  96
  97 Note! All changes that affect the libjack API must be documented
  98 in jack/libjack/ChangeLog using the standard ChangeLog style
  99 (see GNU developer docs).
 100
 101
 102 Sending patches
 103 ---------------------------------------------------------------------
 104
 105 People without CVS-access
 106 ~~~~~~~~~~~~~~~~~~~~~~~~~
 107
 108 Send your patches to jackit-devel. Normally patches are accepted
 109 by Paul Davis and/or Jack O'Quin. Either the patch is applied right
 110 away, or you get an "ok to me" message, after which other developers
 111 with CVS-access can commit the patch.
 112
 113 People with CVS-access
 114 ~~~~~~~~~~~~~~~~~~~~~~
 115
 116 Trivial changes can be committed without review. For non-trivial
 117 changes, you should first send a proposal to jackit-devel and
 118 wait for comments. There are no strict approval rules so use of
 119 common sense is recommended. ;)
 120
 121 Tips for making patches
 122 ~~~~~~~~~~~~~~~~~~~~~~~
 123
 124 - test your patch on a clean CVS-checkout
 125 - remember to run cvs update before making commits
 126
 127
 128 CVS Access
 129 -----------------------------------------------------------------------
 130
 131 Contact Paul Davis.
 132
 133
 134 Uses of external libraries and other packages
 135 -----------------------------------------------------------------------
 136
 137 The main JACK components, jackd and libjack, should only use
 138 standard POSIX and ANSI-C services. If use of other interfaces is
 139 absolutely needed, it should be made optional in the build process (via
 140 a configure switch for example).
 141
 142 Other components like example clients and drivers, may rely on other
 143 packages, but these dependencies should not affect the main build
 144 process.
 145
 146
 147 Decision Process
 148 -----------------------------------------------------------------------
 149
 150 All non-trivial changes should be discussed on the jackit-devel
 151 mailing list. It has been agreed that Paul Davis will make
 152 the final decisions based on these discussions.
 153