mirror of
https://github.com/brl/mutter.git
synced 2024-11-13 01:36:10 -05:00
d036d088aa
Update with the new fixed point and units rules. Also, fix the grammar and clarify what to do with non-static private functions.
123 lines
4.4 KiB
Plaintext
123 lines
4.4 KiB
Plaintext
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.
|
|
|
|
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$
|