CONTRIBUTE

   1  Date: 1999-08-04
   2
   3 To Think About When Contributing Source Code
   4
   5  This document is intended to offer some guidelines that can be useful to
   6  keep in mind when you decide to write a contribution to the project. This
   7  concerns new features as well as corrections to existing flaws or bugs.
   8
   9 Naming
  10
  11  Try using a non-confusing naming scheme for your new functions and variable
  12  names. It doesn't necessarily have to mean that you should use the same as
  13  in other places of the code, just that the names should be logical,
  14  understandable and be named according to what they're used for.
  15
  16 Indenting
  17
  18  Please try using the same indenting levels and bracing method as all the
  19  other code already does. It makes the source code a lot easier to follow if
  20  all of it is written using the same style. I don't ask you to like it, I
  21  just ask you to follow the tradition! ;-)
  22
  23 Commenting
  24
  25  Comment your source code extensively. I don't see myself as a very good
  26  source commenter, but I try to become one. Commented code is quality code
  27  and enables future modifications much more. Uncommented code much more risk
  28  being completely replaced when someone wants to extend things, since other
  29  persons' source code can get quite hard to read.
  30
  31 General Style
  32
  33  Keep your functions small. If they're small you avoid a lot of mistakes and
  34  you don't accidentaly mix up variables.
  35
  36 Non-clobbering All Over
  37
  38  When you write new functionality or fix bugs, it is important that you
  39  don't fiddle all over the source files and functions. Remember that it is
  40  likely that other people have done changes in the same source files as you
  41  have and possibly even in the same functions. If you bring completely new
  42  functionality, try writing it in a new source file. If you fix bugs, try to
  43  fix one bug at a time and send them as separate patches.
  44
  45 Separate Patches Doing Different Things
  46
  47  It is annoying when you get a huge patch from someone that is said to fix 511
  48  odd problems, but discussions and opinions don't agree with 510 of them - or
  49  509 of them were already fixed in a different way. Then the patcher needs to
  50  extract the single interesting patch from somewhere within the huge pile of
  51  source, and that gives a lot of extra work. Preferably, all fixes that
  52  correct different problems should be in their own patch with an attached
  53  description exactly what they correct so that all patches can be selectively
  54  applied by the maintainer or other interested parties.
  55
  56 Document
  57
  58  Writing docs is dead boring and one of the big problems with many open
  59  source projects. Someone's gotta do it. It makes it a lot easier if you
  60  submit a small description of your fix or your new features with every
  61  contribution so that it can be swiftly added to the package documentation.
  62
  63 Write Access to CVS Repository
  64
  65  If you are a frequent contributor, or have another good reason, you can of
  66  course get write access to the CVS repository and then you'll be able to
  67  check-in all your changes straight into the CVS tree instead of sending all
  68  changes by mail as patches. Just ask if this is what you'd want.