HACKING

HACKING file for C Ratfor.

This file attempts to describe the rules to use when hacking it.


C Coding Style
--------------

  Mostly K&R style.

  Use indentation of four character.

  Do not use tab characters in C headers and source files, *ever*.

  For variables: do not use CamelCase or mixedCase, but use only
  names_with_underscores.

  Constants defined with `enum' or with `#define' must be written in
  UPPERCASE.  Macros defined with `#define' should be written in UPPERCASE,
  *unless* keeping them lowercase can make the code definitely clearer.

  Do not use typedefs (apart the already existing typedef `bool' for
  booleans): it's better know the real type of what is being declared
  and used, even if that means a bit more typing.

  Preprocessor statements (#if and such) *must* start at column one. To
  indent preprocessor directives you should put the # at the beginning
  of a line, followed by any number of whitespaces.

  Do not write function definitions like this:
    ...
    int foo(void) {
       ... /* function body here */
    }
    ...
    char* bar(char c, char s[], int n)
    {
       ... /* function body here */
    }
    ...
  Instead use:
    ...
    int
    foo(void)
    {
       ... /* function body here */
    }
    ...
    char *
    bar(char c, char s[], int n)
    {
       ... /* function body here */
    }
    ...
  This greatly increases greppability of C source files.

  For header files: protect from multiple inclusions with the idiom
  (assuming a `foo.h' header file):
    #ifndef RAT4_FOO_H
    #  define RAT4_FOO_H 1
    ... /* content of header file here */
    #endif /* RAT4_FOO_H */

  It's ok, and even recommended, to enclose statements in curly brackets
  to increase readability, even when this is not strictly necessary.

  For example, instead of this:

    /* BAD */
    for (i = 0; i < SIZE; i++)
        /* init array */
        a[i] = i + 1

  do this:

    /* GOOD */
    for (i = 0; i < SIZE; i++) {
        /* init array */
        a[i] = i + 1
    }

  and instead of this:

    /* MIGHT BE CONFUSING */
    if (x > 3)
        error()
    else
        y++:
    if (y > 4)
        do_something();

  do this:

    /* BETTER */
    if (x > 3) {
        error()
    } else {
        y++:
    }
    if (y > 4)
        do_something();

  On the contrary, there's no need of adding curly brackets here:

    /* ACCEPTABLE */
    for (i = 0; i < SIZE; i++)
        if (a[i] < 0)
            a[i] = 0
    if (x > 3)
        error()
  
  but adding them won't hurt either, unless it hampers readability
  (e.g. by making the body of a function too long).


Fixing bugs
-----------

  The correct response to most actual bugs is to write new testcase(s)
  which demonstrate the bug.  Then fix the bug, re-run the test suite,
  and check everything in.

  If the bug is particularly complex or subtle, it might be even better
  to first commit the (still failing) testcase, and only thereafter fix
  the bug, committing this fix separately.  The testcase should then be
  expected to pass after the fix is in place.


Making a release
----------------

  NOTE: In what follows, `$VERSION' will denote the version of the package
  you are releasing.  $VERSION should be something like 0.9, 2.0, 1.11.1 or
  10.12 for stable releases, and 0.8a, 3.1b, 1.2.1c or even 3.1z for alpha
  and beta releases.  Likewise, `$RELEASE_TYPE' will denote the type of the
  release; it *must* be either `stable', `beta' or `alpha'.

  Commit any pending change to Git.  Re-bootstrap and re-configure the
  package.  Be sure you have enabled the import of maintainer make rules.
  Run the testsuite of the package, with `make check && make distcheck'.
  If this fail, fix the errors, commit to Git and repeat the procedure,
  until the previous command succeed.

  Repeat the previous steps for some different configurations, e.g. by
  changing the C compiler (CC), the Fortran compiler (F77), and/or the
  shell used by configure and by the makefiles (CONFIG_SHELL).  Also,
  try to use a C++ compiler as the C compiler.  Finally, if possible,
  also try different make(1) programs, and run the testsuite in parallel
  mode (e.g. by using `make -jN check && make -jN distcheck' for N > 1).

  When all the above steps are finally sucessful, edit the `NEWS' file
  to cite the new $VERSION, and commit that change (with a message like
  "NEWS: version bumped to $VERSION").  Create an annotated git tag named
  *exactly* `v$VERSION' (e.g. `v1.0' or `v2.1e'), and with a comment that
  is *exactly* `$RELEASE_TYPE release $VERSION' (e.g. `stable release 1.0'
  or `beta release 2.1e').

  Then simply issue a `make alpha' (if releasing an alpha version), `make
  beta' (if releasing a beta version), or `make stable' (if releasing a
  stable version).  This will do some sanity checks on the state of your
  repository (mostly to verify that you took the steps listed above), and
  if this passes will create a distribution tarball with `make distcheck'.


Miscellaneous
-------------

  We don't commit generated files like configure or the various Makefile.in
  into the C Ratfor Git repository.

  We don't use SVN-style $Id$ lines, which create more problems than
  they solve, especially with Git.