How to contribute

The ADG canvas is a free project (as in speech and as in beer): any help will be appreciated. This document will show a (non-exhaustive) list of ways on how you can contribute to the project. The approach is usual informal, so if you have new suggestions feel free to join our mailing list.

Use the bug tracker to report any bugs you find in the project while using it. The tracker is also opened to suggestions or feature requests: just register yourself and report whatever you fill useful.

If you want to be up to date with the development status or intend to use the ADG canvas seriously, please consider joining the mailing list. This is the main source of information where discussion about the future of the project will take place.

ADG is a library so this is not a big issue. Anyway, as soon as the gettext support will be added, fill free to translate it and submit the result in any way you fill comfortable with. The procedure is pretty straight forward and the wikipedia page provides a good introduction on the gettext usage. This section will be improved with further details as soon as the gettext support will be added.

Of course, ADG is free software so you are free to modify the code under the terms of the LGPL 2.1 license. You can submit any patch you fill worth the inclusion in the mainstream, either on the mailing list or in the bug tracker.

The easiest way to hack the core of the ADG project (plain C language) is by following the code close to the place you are hacking, but if you want a written down set of rules, the coding style is loosely based on the kernel normal form style using a 4 space indentation. The tabs should be expanded to spaces and there must not be any trailing spaces at the end of line or empty lines at the end of a file (they are a PITA in version control). A common way to deal with the latter problem is to enable a pre-commit hook in your own repository:

cd adg
cp nodist/pre-commit .git/hooks
chmod 0755 .git/hooks/pre-commit

The rules used by the API are more rigid and they are strictly tied to the GObject API conventions. The prefixes must be ADG, Adg and adg for the ADG canvas and CPML, Cpml and cpml for the cairo path manipulation library. In addition, the following suggestions/rules also apply:

/* Method emitting "signal-name" */
void            adg_object_signal_name          (AdgObject      *object,
                                                 /* Other parameters */);

/* Generic setter method */
void            adg_object_set_value            (AdgObject      *object,
                                                 const AdgValue *value);
/* Setter method for boolean values */
void            adg_object_switch_boolean_value (AdgObject      *object,
                                                 gboolean       *new_state);

/* Generic getter method */
const AdgValue *adg_object_get_value            (AdgObject      *object);

/* Getter method for boolean values */
gboolean        adg_object_has_boolean_value    (AdgObject      *object);

/* Getter method for reference counted values: an object could be
 * referenced and unreferenced also if read-only, so no const needed */
AdgObject *     adg_object_get_object           (AdgObject      *object);

/* Getter method returning scalar values must not be const:
 * they are passed by value */
ScalarType      adg_object_get_scalar_value     (AdgObject      *object);

/* Alternative getter method to be used when the generic syntax is
 * not allowed, such as when the value is dynamically generated */
void            adg_object_put_value            (AdgObject      *object,
                                                 AdgValue       *value);

/* Different version of the same setter method for pair values */
void            adg_object_set_value            (AdgObject      *object,
                                                 const AdgPair  *value);
void            adg_object_set_value_explicit   (AdgObject      *object,
                                                 gdouble         value_x,
                                                 gdouble         value_y);
void            adg_object_set_value_from_model (AdgADim        *adim,
                                                 AdgModel       *model,
                                                 const gchar    *named_pair);

The method should be grouped by argument, that is methods working on the same subject should be adjacents. The constructors must be the first ones while the helper methods for signal emission should be the last ones. It is preferable to keep the setter before the getter in the list.

For any other non-C contribution (makefiles, translations, bindings, documentation, whatever) just follow the surronding text using a bit of common sense. When no surrounding text exists, use your preferred style and use it consistently.

The project uses git as version control system and the main repository is on repo.cz. You can find some other cloned repository around the web, though.

The preferred way to create a patch is by using git format-patch to generate the file. A basic usage involves only few steps:

git clone git://repo.or.cz/adg.git
cd adg
# Modify and test...
git commit -a
# Write the commit message
git format-patch HEAD^
# You have just created a proper patch file