1
0
Fork 0
mutter-performance-source/HACKING
Emmanuele Bassi b63b1584bd [docs] Add coding style document
We should formalise the current coding style of Clutter for
third parties that wish to start hacking and contribute back
patches.
2008-12-18 18:03:43 +00:00

96 lines
3.2 KiB
Text

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.
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$