From f73cecbd9e2e2b8bac68c0b2f59ef6dfcbf01ea5 Mon Sep 17 00:00:00 2001 From: Nicola Fontana Date: Fri, 18 Jun 2010 21:54:32 +0200 Subject: [PATCH] [docs] Added HACKING.xml file Moved and improved the coding conventions on its own chapter (HACKING) and added what needed to properly include this file in the ADG documentation. Refurbished CONTRIBUTING.xml by adding the "Spread" section and linking CONTRIBUTING. Closes issue #20: http://dev.entidi.com/p/adg/issues/20/ --- .gitignore | 25 ++-- Makefile.am | 6 +- docs/adg/Makefile.am | 3 +- docs/adg/adg-docs.xml | 1 + docs/gnu/CONTRIBUTING.xml | 217 +++++++++-------------------- docs/gnu/{CONTRIBUTING.xml => HACKING.xml} | 124 +++++++++-------- 6 files changed, 153 insertions(+), 223 deletions(-) rewrite docs/gnu/CONTRIBUTING.xml (75%) copy docs/gnu/{CONTRIBUTING.xml => HACKING.xml} (59%) diff --git a/.gitignore b/.gitignore index 1a4756b0..a1e3261a 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,16 @@ +/aclocal.m4 +/autom4te.cache/ +/ChangeLog +/config.log +/config.status +/configure +/CONTRIBUTING +/HACKING +/INSTALL +/libtool +/NEWS +/README +/TODO *.la *.lo *.loT @@ -5,17 +18,5 @@ *.stamp .deps/ .libs/ -/CONTRIBUTING -/ChangeLog -/INSTALL -/NEWS -/README -/TODO -/aclocal.m4 -/autom4te.cache/ -/config.log -/config.status -/configure -/libtool Makefile Makefile.in diff --git a/Makefile.am b/Makefile.am index 13f09209..8bae56a0 100644 --- a/Makefile.am +++ b/Makefile.am @@ -18,7 +18,8 @@ BUILT_SOURCES= ChangeLog \ README \ NEWS \ TODO \ - CONTRIBUTING + CONTRIBUTING \ + HACKING EXTRA_DIST= COPYING \ ChangeLog-0.2.1 \ @@ -60,3 +61,6 @@ TODO: $(xml2txt_stylesheet) $(srcdir)/docs/gnu/TODO.xml CONTRIBUTING: $(xml2txt_stylesheet) $(srcdir)/docs/gnu/CONTRIBUTING.xml $(xml2txt_command) $(srcdir)/docs/gnu/CONTRIBUTING.xml + +HACKING: $(xml2txt_stylesheet) $(srcdir)/docs/gnu/HACKING.xml + $(xml2txt_command) $(srcdir)/docs/gnu/HACKING.xml diff --git a/docs/adg/Makefile.am b/docs/adg/Makefile.am index f13edb66..1324feca 100644 --- a/docs/adg/Makefile.am +++ b/docs/adg/Makefile.am @@ -51,7 +51,8 @@ HTML_IMAGES= content_files= $(top_srcdir)/docs/gnu/README.xml \ $(top_srcdir)/docs/gnu/NEWS.xml \ $(top_srcdir)/docs/gnu/TODO.xml \ - $(top_srcdir)/docs/gnu/CONTRIBUTING.xml + $(top_srcdir)/docs/gnu/CONTRIBUTING.xml \ + $(top_srcdir)/docs/gnu/HACKING.xml expand_content_files= diff --git a/docs/adg/adg-docs.xml b/docs/adg/adg-docs.xml index 0944e26a..51f4c22a 100644 --- a/docs/adg/adg-docs.xml +++ b/docs/adg/adg-docs.xml @@ -10,6 +10,7 @@ + diff --git a/docs/gnu/CONTRIBUTING.xml b/docs/gnu/CONTRIBUTING.xml dissimilarity index 75% index 57abe81f..62f22867 100644 --- a/docs/gnu/CONTRIBUTING.xml +++ b/docs/gnu/CONTRIBUTING.xml @@ -1,148 +1,69 @@ - - - - -How to contribute -How you can help the ADG canvas project - - -Join the effort! - -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. - - - - -Report any errors and issues or suggest new features - -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. - - - - -Translation of the ADG messages - -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. - - - - -Enhancements, bugs fixing, documentation improvements: patches welcome - -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 - - - - + + + + +How to contribute +How you can help the ADG canvas project + +The ADG canvas is a relatively young and little project: any help +will be appreciated. This document shows a (non-exhaustive) list of +ways on how you can contribute. For any question or suggestion, fill +free to contact us. + + +Spread the word + +The easiest way to contribute is to let the other know of the ADG +existence. Blog about it, bookmark the home page, suggest it as an +alternative to any potential user. + +Objectively, the ADG canvas is a niche project and there is nothing +can be done about it. The target audience is a software developer +with technical design knowledge or a designer with development skills, +and I bet there are not many of them around. + +A community, in the open source meaning, will be quite difficult to +achieve but the project itself is really innovative and there is no +other similar alternative I am aware of in the free software world. + + + + +Report any errors and issues or suggest new features + +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. + + + + +Translation of the ADG messages + +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. + + + + +Patches welcome (obviously) + +The ADG canvas is a free project (as in speech and as in beer): any +code contribution will be publicly shared. For technical details on +the way the code is implemented in the ADG project, please consult +the dedicated section. + + diff --git a/docs/gnu/CONTRIBUTING.xml b/docs/gnu/HACKING.xml similarity index 59% copy from docs/gnu/CONTRIBUTING.xml copy to docs/gnu/HACKING.xml index 57abe81f..ed91437b 100644 --- a/docs/gnu/CONTRIBUTING.xml +++ b/docs/gnu/HACKING.xml @@ -2,57 +2,48 @@ - -How to contribute -How you can help the ADG canvas project + +Code contributions +Conventions used by the ADG canvas project - -Join the effort! +This is a high-level guide to how the ADG project is organized and +how to get started hacking on it. The following statements should be +considered recommendations, not rules. -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. - - - -Report any errors and issues or suggest new features + +Hints on how to submit patches -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 +Any patch worth the inclusion in the mainstream could be submitted to the +bug tracker or by using the mailing list. -This is the main source of information where discussion about the -future of the project will take place. +The former is preferred when the patch addresses some specific issue while +the latter is a better choice for generic patches and proofs of concept. - +The project uses git as version control system +and the repositories could be found at different places. The following are +all kept up to date: - -Translation of the ADG messages + + repo.cz + SourceForge + Gitorious + -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. +The preferred way to create a patch is by using git format-patch to +generate the file. A typical usage involves the following 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: send it - -Enhancements, bugs fixing, documentation improvements: patches welcome - -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. + +Coding style 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 @@ -61,16 +52,19 @@ the kernel norma 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: +common way to deal with the latter problem is to enable the +pre-commit +hook in your own repository: cd adg cp nodist/pre-commit .git/hooks chmod 0755 .git/hooks/pre-commit + + + +API conventions - -The rules used by the API are more rigid and they are strictly tied to the +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 @@ -101,7 +95,7 @@ AdgObject * adg_object_get_object (AdgObject *object); * they are passed by value */ ScalarType adg_object_get_scalar_value (AdgObject *object); -/* Alternative getter method to be used when the generic syntax is +/* Alternative getter method to use when the generic syntax is * not allowed, such as when the value is dynamically generated */ void adg_object_put_value (AdgObject *object, AdgValue *value); @@ -117,8 +111,7 @@ void adg_object_set_value_from_model (AdgADim *adim, const gchar *named_pair); - -The method should be grouped by argument, that is methods working on the +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. @@ -128,21 +121,30 @@ 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: + +How the API should be used -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 +The getter methods must be considered read-only. Although in some +circumstances some of them do not return a const value, +this is done just to allow referencing and unreferencing an object, +but still that object should be considered read-only. This means to +change a property you should write something along these lines: +CpmlExtents extents; - +cpml_extents_copy(&extents, adg_entity_get_extents(entity)); +/* Modify extents... */ +adg_entity_set_extents(entity, &extents); + +The put version of a getter usually does not have the setter +counterpart (because the returned value is typically computed) so the +above will be reduced to: +CpmlExtents extents; + +cpml_segment_put_extents(segment, &extents); +/* Use extents... */ + + -- 2.11.4.GIT