[docs] Added a HACKING file

1 files changed, 136 insertions, 0 deletions

diff --git a/HACKING b/HACKING
new file mode 100644
index 00000000..43cea4b4
--- /dev/null
+++ b/HACKING
@@ -0,0 +1,136 @@
+Formatting
+==========
+
+All code should follow the same formatting standards which are broadly based on the GNU style (http://www.gnu.org/prep/standards.html) with some
+additions. Briefly:
+
+ - Tab indents are used and braces for blocks go on the same line as the block statement:
+
+	if (x < foo (y, z)) {
+		haha = bar[4] + 5;
+	} else {
+		while (z) {
+			haha += foo (z, z);
+			z--;
+		}
+		return abc (haha);
+	}
+
+   Braces should be omitted for single-line blocks, but included for all blocks in a multi-part if statement which has blocks containing more than
+   one line (as above).
+
+ - Spaces should be present between function name and argument block, and after commas:
+
+	foo (z, z)
+
+ - In pointer types, the '*' is grouped with the variable name, not with the base type. 
+
+	int *a;
+
+   Not:
+
+	int* a;
+
+   In cases where there is no variable name, for instance, return values, there should be a single space between the base type and the '*'.
+
+   Type casts should have no space between the type and '*', but a space before the variable being cast:
+
+	(gchar*) foobar;
+	(gchar**) &foobar;
+
+ - Function and variable names are lower_case_with_underscores, type names are CamelCase and macro names are UPPER_CASE_WITH_UNDERSCORES.
+
+ - Comparisons to NULL, TRUE and FALSE should always be made explicit, for clarity.
+
+ - Code should be wrapped at around 150 columns, such that it doesn't require horizontal scrolling on a decent-sized display. Don't wrap at 80 columns.
+
+Documentation comments
+======================
+
+All public API functions should have inline documentation headers in the gtk-doc style. For more information about gtk-doc comments, see the gtk-doc
+manual (http://library.gnome.org/devel/gtk-doc-manual/stable/). There are a few conventions above and beyond the standard gtk-doc formatting which
+libgdata employs:
+
+ - For API which returns allocated memory, the relevant free/unref function must be mentioned in the "Return value" part of the documentation:
+
+	* Return value: a new #GDataEntry; unref with g_object_unref()
+
+   If the function can also return NULL (on error), format it as follows:
+
+	* Return value: a new #GDataGDFeedLink, or %NULL; free with gdata_gd_feed_link_free()
+
+ - When adding API, make sure to add a "Since" clause:
+
+	* Since: 0.2.0
+
+ - For object methods, the "self" parameter should be documented simply as "a #GObjectType":
+
+	* @self: a #GDataQuery
+
+ - For function parameters which can legitimately be set to NULL (or some other default value), list that as follows:
+
+	* @updated_max: the new maximum update time, or %NULL
+
+ - If numbers are mentioned in documentation as values to be passed around in code, they should be prefixed by a '%', just like %NULL.
+
+Adding public API
+=================
+
+ - Ensure it has proper guards against bad parameters:
+
+	g_return_if_fail (GDATA_IS_QUERY (self));
+	g_return_if_fail (foobar != NULL);
+
+ - All public API must have a gtk-doc comment, and be added to the docs/reference/gdata-sections.txt file, to include it in the documentation.
+   The documentation comment must have a "Since" clause (see "Documentation comments" section).
+
+ - All public API must be listed in gdata/gdata.symbols.
+
+ - Non-trivial API should have a test case added in the relevant test suite file in gdata/tests. Note that the "general" test suite file cannot make
+   network requests in the course of running its test cases.
+
+ - All GObject properties must have getter/setter functions.
+
+ - All API which returns allocated memory must be tagged with G_GNUC_WARN_UNUSED_RESULT after its declaration, to safeguard against consumers of the
+   API forgetting to use (and consequently free) the memory. This is unlikely, but adding the macro costs little and acts as a reminder in the API
+   documentation to free the result.
+
+ - All GObject *_get_type function declarations must be tagged with the G_GNUC_CONST macro, as well as any other applicable functions
+   (see the gcc documentation: http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html#index-g_t_0040code_007bconst_007d-function-attribute-2207).
+
+Choosing function names
+=======================
+
+In general, use common sense. However, there are some specific cases where a standard is enforced:
+
+ - For boolean getters (e.g. for FooBar:is-baz) use foo_bar_is_baz, rather than foo_bar_get_is_baz. Note that the property name should be "is-baz",
+   rather than just "baz".
+
+ - For boolean setters use foo_bar_set_is_baz, rather than foo_bar_set_baz.
+
+ - In general, try to keep API named similarly to the actual GData API constructs. In certain cases, however, it might make more sense to rename pieces
+   of API to be less cryptic (e.g. "timezone" instead of "ctz": http://code.google.com/apis/calendar/docs/2.0/reference.html#Parameters).
+
+Commit messages
+===============
+
+libgdata does not use a ChangeLog; it is auto-generated from the git log when packaging a release. Commit messages should follow the GNOME commit
+message guidelines (http://live.gnome.org/Git/CommitMessages), with the exception that when a commit closes a bug, the short explanation of the commit
+should simply be the bug's title, as copied from Bugzilla (e.g. "Bug 579885 – Add code examples to documentation"). The long explanation should then
+be used to give details of the changes. If the bug's title is not relevant, it should be changed before committing the changes.
+
+The short explanation of a commit should always be prefixed by a tag to describe the part of the library it touches. The following tags are valid:
+
+ - [core] — for the core code in the gdata directory, such as GDataEntry.
+
+ - [docs] — for documentation changes which are not specific to a service, such as updates to the docs directory, NEWS, README, this file, etc.
+
+ - [tests] — for changes to the test code in gdata/tests which are not specific to a service.
+
+ - [calendar] — for the Google Calendar code in gdata/services/calendar.
+
+ - [contacts] — for the Google Contacts code in gdata/services/contacts.
+
+ - [youtube] — for the YouTube code in gdata/services/youtube.
+
+The only commits which should not have a tag are translation commits, touching only the po directory.