mutter/HACKING

GENERAL
=======

General notes and rules on clutter core hacking;

 - Follow the CODING_STYLE document.

 - All non static public API funcs should be documented in the source files
   via gtk-doc. Structures, enumerations and macros should be documented in
   the header files.

 - All non-trivial static and private API should be documented, especially
   the eventual lifetime handling of the arguments/return values or locking
   of mutexes.

 - All public functions with float parameters should also provide a fixed
   point version, with the 'x' postfix to the function name, e.g.:
   
     clutter_actor_set_foo      - floating point
     clutter_actor_set_foox     - fixed point

   Fixed point should be always be used internally, except when precision
   is paramount.

 - All public functions dealing with pixels should also provide a
   ClutterUnit version, with the 'u' postfix to the function name, e.g:

     clutter_actor_set_bar      - pixels
     clutter_actor_set_baru     - units
   
   ClutterUnit should always be used internally.

 - Properties should always be in floating point (never fixed point).
   The preferred precision is double.

 - Properties should use pixels whenever is possible. If sub-pixel
   precision is fundamental, use ClutterParamSpecUnit and
   clutter_param_spec_unit() to install ClutterUnit properties, and
   clutter_value_set_unit()/clutter_value_get_unit() to handle GValues in
   a safe way. Never install a ClutterUnit property using a GParamSpecInt.

 - Public entry points must always check their arguments with
   g_return_if_fail() or g_return_val_if_fail().

 - Private entry points should use g_assert() to verify internal state;
   do not use g_return_if_fail()/g_return_val_if_fail() as they might
   be compiled out.

 - Really try to avoid if possible additions to clutter-private.h. Use
   accessor functions instead.

 - Don't add direct GL calls but wrap with cogl (also adding GLES
   version if possible, or at least a stub).

 - Use CLUTTER_NOTE() macro for debug statements.

 - New features should also include an exhaustive test unit under
   tests/conform and, eventually, a user-interactive tes under
   tests/interactive.

 - When committing, use the standard git commit message format:

     short description          - MUST be less than 74 characters
     <newline>                  - MANDATORY empty line
     long description           - Each line must be less than 80 characters

   Do NOT put the commit message on the short description line.
   One line commit messages should be avoided, unless they can be
   *fully* explained in less than 70 characters (e.g. "Fix typo in
   clutter_actor_create_pango_context() docs"). Think of the commit
   message as an email sent to the maintainers explaining "what" you
   did and, more importantly, "why" you did it. The "how" is not
   important, since "git show" will show the patch inlined with the
   commit message.

RELEASES
========

In making a new release;

 - Check out a fresh copy from SVN.

 - Verify versioning in configure.ac, increasing relevant
   clutter_major_version/clutter_minor_version/clutter_micro_version
   value. For point releases, bump clutter_micro_version to the next
   even number.

 - If there was no API change (addition, removal), increment
   clutter_interface_age by two. If there was an API change,
   set clutter_interface_age to zero. The interface_age is used to
   keep the soname the same.

 - Update NEWS (New feature details, bug #'s), README (Any API changes
   relevant to developers + version), AUTHORS if relevant.

 - Add a Release entry to the ChangeLog noting version.

 - Call make distcheck and fix if fails. 

 - Upload the tarball.

 - Bump clutter_micro_version to the next odd number version.

 - Commit.
 
 - Announce release to waiting world on blog and mailing list.

 - Release any dependant add-ons following similar rules to above. 
   Dont forget to check *.pc file version deps!

$LastChangedDate$