b63b1584bd
We should formalise the current coding style of Clutter for third parties that wish to start hacking and contribute back patches.
96 lines
3.2 KiB
Text
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$
|