doc/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  - The nick and blurb of properties in public classes should be marked for
  28    translation by using the P_() macro defined in the clutter-private.h
  29    header file.
  30
  31  - Public entry points must always check their arguments with
  32    g_return_if_fail() or g_return_val_if_fail().
  33
  34  - Private entry points should use g_assert() or g_warn_if_fail() to
  35    verify internal state; do not use g_return_if_fail() or
  36    g_return_val_if_fail() as they might be compiled out.
  37
  38  - If you need to share some state variable across source files use
  39    ClutterContext and a private accessor.
  40
  41  - Private, non-static functions must begin with an underscore and
  42    be declared inside clutter-private.h.
  43
  44  - Don't add direct GL calls but add API to Cogl (both GL and GL|ES
  45    versions if possible).
  46
  47  - Use the CLUTTER_NOTE() macro for debug statements in Clutter, and
  48    the COGL_NOTE() macro for debug statements in Cogl. If necessary,
  49    add a value inside ClutterDebugFlags or CoglDebugFlags to specify
  50    the debug section.
  51
  52  - New features should also include an exhaustive test unit under
  53    tests/conform and, eventually, a user-interactive test under
  54    tests/interactive.
  55
  56  - When committing, use the standard git commit message format:
  57
  58 === begin example commit ===
  59 Short explanation of the commit
  60
  61 Longer explanation explaining exactly what's changed, whether any
  62 external or private interfaces changed, what bugs were fixed (with bug
  63 tracker reference if applicable) and so forth. Be concise but not too
  64 brief. Don't be afraid of using UTF-8, or even ASCII art.
  65 === end example commit ===
  66
  67  - Always add a brief description of the commit to the _first_ line of
  68    the commit and terminate by two newlines (it will work without the
  69    second newline, but that is not nice for the interfaces).
  70
  71      short description          - MUST be less than 72 characters
  72      <newline>                  - MANDATORY empty line
  73      long description           - Each line MUST be less than 76 characters
  74
  75  - Do NOT put the commit message on the short description line. One line
  76    commit messages should be avoided, unless they can be *fully* explained
  77    in less than 72 characters (e.g. "Fix typo in
  78    clutter_actor_create_pango_context() docs").
  79
  80  - The brief description might optionally have a "tag", i.e. a word or two
  81    followed by a color, detailing what part of the repository the commit
  82    affected, e.g.:
  83
  84       alpha: Add :mode property
  85       text: Emit ::cursor-event only on changes
  86
  87  - The tag counts as part of overall character count, so try using
  88    a short word. Optionally, you can also use the "[tag]" form.
  89
  90  - Build environment fixes should use the "build" tag.
  91
  92  - Think of the commit message as an email sent to the maintainers explaining
  93    "what" you did and, more importantly, "why" you did it. The "how" is not
  94    important, since "git show" will show the patch inlined with the commit
  95    message.