HACKING

   1 GENERAL
   2 =======
   3
   4 General notes and rules on clutter core hacking;
   5
   6  - Follow the CODING_STYLE document.
   7
   8  - *Really* follow the CODING_STYLE document.
   9
  10  - All non static public API funcs should be documented in the source files
  11    via gtk-doc. Structures, enumerations and macros should be documented in
  12    the header files.
  13
  14  - All non-trivial static and private API should be documented, especially
  15    the eventual lifetime handling of the arguments/return values or locking
  16    of mutexes.
  17
  18  - Properties should always be in floating point (never fixed point).
  19    The preferred precision is double for angles, and single precision
  20    for size and position -- especially if they have to be passed down
  21    to COGL.
  22
  23  - Properties should use pixels whenever is possible. Dimensional and
  24    positional properties can also use ClutterParamSpecUnits to define
  25    the units-based logical values with a unit type.
  26
  27  - Public entry points must always check their arguments with
  28    g_return_if_fail() or g_return_val_if_fail().
  29
  30  - Private entry points should use g_assert() or g_warn_if_fail() to
  31    verify internal state; do not use g_return_if_fail() or
  32    g_return_val_if_fail() as they might be compiled out.
  33
  34  - If you need to share some state variable across source files use
  35    ClutterContext and a private accessor.
  36
  37  - Private, non-static functions must begin with an underscore and
  38    be declared inside clutter-private.h.
  39
  40  - Don't add direct GL calls but add API to COGL (both GL and GL|ES
  41    versions if possible).
  42
  43  - Use the CLUTTER_NOTE() macro for debug statements in Clutter, and
  44    the COGL_NOTE() macro for debug statements in COGL. If necessary,
  45    add a value inside ClutterDebugFlags or CoglDebugFlags to specify
  46    the debug section.
  47
  48  - New features should also include an exhaustive test unit under
  49    tests/conform and, eventually, a user-interactive test under
  50    tests/interactive.
  51
  52  - When committing, use the standard git commit message format:
  53
  54 === begin example commit ===
  55 Short explanation of the commit
  56
  57 Longer explanation explaining exactly what's changed, whether any
  58 external or private interfaces changed, what bugs were fixed (with bug
  59 tracker reference if applicable) and so forth. Be concise but not too
  60 brief.
  61 === end example commit ===
  62
  63    Always add a brief description of the commit to the _first_ line of
  64    the commit and terminate by two newlines (it will work without the
  65    second newline, but that is not nice for the interfaces).
  66
  67      short description          - MUST be less than 72 characters
  68      <newline>                  - MANDATORY empty line
  69      long description           - Each line MUST be less than 76 characters
  70
  71    Do NOT put the commit message on the short description line. One line
  72    commit messages should be avoided, unless they can be *fully* explained
  73    in less than 72 characters (e.g. "Fix typo in
  74    clutter_actor_create_pango_context() docs").
  75
  76    The brief description might optionally have a "tag", enclosed in
  77    square brackets, detailing what part of the repository the commit
  78    affected, e.g.:
  79
  80       [alpha] Add :mode property
  81       [text] Emit ::cursor-event only on changes
  82
  83    The tag counts as part of overall character count, so try using
  84    a short word. Optionally, you can also use the "tag:" form.
  85
  86    Think of the commit message as an email sent to the maintainers explaining
  87    "what" you did and, more importantly, "why" you did it. The "how" is not
  88    important, since "git show" will show the patch inlined with the commit
  89    message.
  90
  91 RELEASES
  92 ========
  93
  94 In making a new release;
  95
  96  - Check out a fresh copy from SVN.
  97
  98  - Verify versioning in configure.ac, increasing relevant
  99    clutter_major_version/clutter_minor_version/clutter_micro_version
 100    value. For point releases, bump clutter_micro_version to the next
 101    even number.
 102
 103  - If there was no API change (addition, removal), increment
 104    clutter_interface_age by two. If there was an API change,
 105    set clutter_interface_age to zero. The interface_age is used to
 106    keep the soname the same.
 107
 108  - Update NEWS (New feature details, bug #'s), README (Any API changes
 109    relevant to developers + version), AUTHORS if relevant.
 110
 111  - Add a Release entry to the ChangeLog noting version.
 112
 113  - Call make distcheck and fix if fails.
 114
 115  - Upload the tarball.
 116
 117  - Bump clutter_micro_version to the next odd number version.
 118
 119  - Commit.
 120
 121  - Announce release to waiting world on blog and mailing list.
 122
 123  - Release any dependant add-ons following similar rules to above.
 124    Dont forget to check *.pc file version deps!
 125
 126 $LastChangedDate$