c418b23baf
When writing language bindings for Clutter some rules should be observed to guarantee the same levels of quality across different bindings.
140 lines
5.2 KiB
Text
140 lines
5.2 KiB
Text
GENERAL
|
|
=======
|
|
|
|
General notes and rules on clutter core hacking;
|
|
|
|
- Follow the CODING_STYLE document.
|
|
|
|
- Really, 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 floating point arguments 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 might also be used internally if the 16.16 precision and
|
|
range allow it.
|
|
|
|
- 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 for angles, and single precision
|
|
for size and position -- especially if they have to be passed down
|
|
to COGL.
|
|
|
|
- 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,
|
|
GParamSpecFloat or GParamSpecDouble.
|
|
|
|
- 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.
|
|
|
|
- If you need to share some state variable across source files use
|
|
ClutterContext and a private accessor.
|
|
|
|
- Private, non-static functions must begin with an underscore and
|
|
be declared inside clutter-private.h.
|
|
|
|
- Don't add direct GL calls but add API to COGL (both GL and GL|ES
|
|
versions if possible).
|
|
|
|
- Use the CLUTTER_NOTE() macro for debug statements in Clutter, and
|
|
the COGL_NOTE() macro for debug statements in COGL. If necessary,
|
|
add a value inside ClutterDebugFlags or CoglDebugFlags to specify
|
|
the debug section.
|
|
|
|
- New features should also include an exhaustive test unit under
|
|
tests/conform and, eventually, a user-interactive test 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.
|
|
|
|
LANGUAGE BINDINGS
|
|
=================
|
|
|
|
- Language bindings should not wrap the fixed-point entry points of the
|
|
API; the functions that usually accept fixed-point values are convenience
|
|
functions for C developers.
|
|
|
|
- Similarly, ClutterUnit is a convenience type for the C library. It can
|
|
be safely wrapped as a floating point value, but it should be converted
|
|
to and from a floating point value using the provided macros.
|
|
|
|
- To reduce the amount of entry points, methods with the -u suffix can be
|
|
wrapped either by overloading (if your language allows it) or by making
|
|
every Unit-based function the only entry point, e.g. wrapping
|
|
clutter_actor_get_position() as accepting floating point values as
|
|
parameters and calling clutter_actor_get_positionu() internally after
|
|
having converted the argument types.
|
|
|
|
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$
|