sid/HACK-RULES

   1 This file describes some of the required procedures for contributors working
   2 on SID.  Please read and understand this before checking anything in.  Post
   3 proposed diffs to this file on sid@sources.redhat.com, the project's public
   4 mailing list.
   5
   6
   7 * Special headers
   8
   9 Several files in sid/include/ define the SID low-level API, contained
  10 in the sid:: C++ namespace.  By extension, this also defines the ABI
  11 for compiled component modules.  Because of this, any functional change
  12 to the headers causes instant incompatibility with far-reaching effects.
  13 Therefore, the files that define the low-level API are special and change
  14 extremely rarely.  The special header files are:
  15
  16    sidcomp.h
  17    sidso.h
  18    sidtypes.h
  19
  20 You should NOT check in ANY functional changes to these files without
  21 prior discussion on the project mailing list.  It would be most polite
  22 to post proposed reasonably formatted diffs, and have convincing arguments
  23 ready to justify them.  Sadist <fche> likes to try to veto anything
  24 nonessential.
  25
  26 Whenever the low level API is changed in any way, the
  27 API_MINOR_VERSION and/or API_MAJOR_VERSION values in sidcomp.h must be
  28 changed.  This allows previously compiled component binaries to be
  29 recognized as incompatible at load-attempt time.
  30
  31
  32 * Utility headers
  33
  34 A growing number of header files define optional utility classes and
  35 functions for SID component classes.  These definitions all go into
  36 the sidutil:: C++ namespace.  They are used pervasively in existing
  37 SID component code for convenience only.  These headers are never
  38 installed via "make install".
  39
  40 Feel free to add reasonably formatted new classes/functions at will
  41 into existing files, or new ones.  Convention suggests that any new
  42 utility files be named sid*util.h.  Changes to existing classes may be
  43 made, but only if all affected component sources continue to work.
  44
  45 The utility classes are used by components by a mere #include.  There
  46 is no "sidutil" library for them to link in.  This means that these
  47 headers define template classes/functions or non-template classes with
  48 inline functions only.  One negative side-effect of this arrangement
  49 is that of compiler memory bloat, so this may be changed sometime.
  50
  51
  52 * Components
  53
  54 New components are absolutely welcome.  Here are a few steps that form
  55 an informal checklist:
  56
  57 - Read up on SID architectural theory and practice.  Design
  58   it to be a nice self-contained portable component.  Avoid
  59   anti-component practices (custom APIs, global variables, etc.).
  60 - Announce your intentions on the mailing list.  Good advice is
  61   available at no charge.
  62 - Extend an existing component source directory, if your component is most
  63   conveniently derived from another.  Use a new source directory otherwise.
  64 - Pick an appropriate component type string and shared library name.
  65 - Record them in sid/component/CATALOG.  Name yourself as maintainer.
  66 - Code it up.  Integrate it into the existing autoconf based build system.
  67 - Avoid constructs that are not reliable in the context of a complex
  68   C++ program located in shared libraries / DLLs.
  69 - Use a reasonable coding style.  However, in each component's directory,
  70   follow the style already present.  If there appears to be more than one,
  71   pick one, but don't introduce new ones.
  72 - Document it using the standard XML DTD format in the source directory,
  73   to be installed into $pkgdata along with the generated .txt form.
  74 - Build and automate some tests.  Choosing to not use dejagnu requires a
  75   good reason.
  76
  77 Improvements to existing components are welcome.  Please contact each's
  78 maintainer for advice and perhaps approval.
  79
  80
  81 * Mainlines
  82
  83 New mainlines (sid/main) or sid front-end scripts (sid/bsp) are absolutely
  84 welcome, though are usually less necessary than new components.  Discuss
  85 your intentions on the mailing list as you proceed.
  86
  87
  88 * Check-in checklist
  89
  90 - Confirm that your code runs on both big- and little-endian hosts.
  91   We use mainly Solaris, Linux, Cygwin hosts.  Consider using several
  92   compilers.
  93 - Add standard ChangeLog entries for source files.  Incidentally
  94   regenerated files need not have ChangeLog entries.
  95 - By default, insert a copy of the new ChangeLog entries in the CVS
  96   check-in comments.
  97 - For large systemic changes, make CVS tags before and after the checkin.
  98