1Formatting 2========== 3 4All code should follow the same formatting standards which are broadly based on the GNU style (http://www.gnu.org/prep/standards.html) with some 5additions. Briefly: 6 7 - Tab indents are used and braces for blocks go on the same line as the block statement: 8 9 if (x < foo (y, z)) { 10 haha = bar[4] + 5; 11 } else { 12 while (z) { 13 haha += foo (z, z); 14 z--; 15 } 16 return abc (haha); 17 } 18 19 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 20 one line (as above). 21 22 - Spaces should be present between function name and argument block, and after commas: 23 24 foo (z, z) 25 26 - In pointer types, the '*' is grouped with the variable name, not with the base type. 27 28 int *a; 29 30 Not: 31 32 int* a; 33 34 In cases where there is no variable name, for instance, return values, there should be a single space between the base type and the '*'. 35 36 Type casts should have no space between the type and '*', but a space before the variable being cast: 37 38 (gchar*) foobar; 39 (gchar**) &foobar; 40 41 - Function and variable names are lower_case_with_underscores, type names are CamelCase and macro names are UPPER_CASE_WITH_UNDERSCORES. 42 43 - Comparisons to NULL, TRUE and FALSE should always be made explicit, for clarity. 44 45 - Code should be wrapped at the 150th column, such that it doesn't require horizontal scrolling on a decent-sized display. 46 Don't wrap at the 80th column. 47 48Documentation comments 49====================== 50 51All public API functions should have inline documentation headers in the gtk-doc style. For more information about gtk-doc comments, see the gtk-doc 52manual (http://library.gnome.org/devel/gtk-doc-manual/stable/). There are a few conventions above and beyond the standard gtk-doc formatting which 53libgdata employs: 54 55 - For API which returns allocated memory, the relevant free/unref function must be mentioned in the "Return value" part of the documentation: 56 57 * Return value: a new #GDataEntry; unref with g_object_unref() 58 59 If the function can also return NULL (on error, for example) or some other "default" value (-1, 0, etc.), format it as follows: 60 61 * Return value: a new #GDataGDFeedLink, or %NULL; free with gdata_gd_feed_link_free() 62 63 Note that if a function returns NULL as a result of a precondition or assertion failure, this should not be listed in the documentation. The 64 precondition itself may be listed in the function documentation prose, but if it's the only reason for a function to return NULL, the "or %NULL" 65 clause should be omitted. 66 67 - When adding API, make sure to add a "Since" clause: 68 69 * Since: 0.2.0 70 71 - For object methods, the "self" parameter should be documented simply as "a #GObjectType": 72 73 * @self: a #GDataQuery 74 75 - For function parameters which can legitimately be set to NULL (or some other default value), list that as follows: 76 77 * @updated_max: the new maximum update time, or %NULL 78 79 - If numbers, such as -1, are mentioned in documentation as values to be passed around in code, they should be wrapped in a DocBook "code" tag 80 (e.g. "<code class="literal">-1</code>"), so that they appear similarly to NULL in the documentation. 81 82 - The documentation explaining the purpose of a property, its limitations, interpretation, etc., should be given in the gtk-doc comment for the 83 GObject property itself, not in the documentation for its getter or setter. The documentation for the getter and setter should be stubs which 84 refer to the property's documentation. The getter and setter documentation should, however, still include full details about whether NULL values 85 are permissible for the function parameters, or are possible as the return value, for example. 86 87Adding public API 88================= 89 90 - Ensure it has proper guards against bad parameters: 91 92 g_return_if_fail (GDATA_IS_QUERY (self)); 93 g_return_if_fail (foobar != NULL); 94 95 - 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. 96 The documentation comment must have a "Since" clause (see "Documentation comments" section). 97 98 - All public API must be listed in gdata/gdata-*.symbols. 99 100 - 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 101 network requests in the course of running its test cases. 102 103 - All GObject properties must have getter/setter functions. 104 105 - All API which returns allocated memory must be tagged with G_GNUC_WARN_UNUSED_RESULT after its declaration, to safeguard against consumers of the 106 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 107 documentation to free the result. 108 109 - All GObject *_get_type function declarations must be tagged with the G_GNUC_CONST macro, as well as any other applicable functions 110 (see the gcc documentation: http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html#index-g_t_0040code_007bconst_007d-function-attribute-2207). 111 112 - All properties which could be considered to use an enumerated value should almost definitely use a string instead. See the documentation section 113 on "Enumerable Properties" in the "GData Overview" section. Where appropriate, the values for these string properties should be made available 114 as #defines. 115 116 - New services should be implemented in libgdata itself, not by applications which use libgdata. See the documentation section on "New Services" in 117 the "GData Overview" section. 118 119 - New API must never be added in a stable micro release. API additions can only be made in a major or minor release; this is to prevent the LT version 120 of one minor version's micro releases exceeding the LT version of the next minor version as almost happened between versions 0.6.3 and 0.7.0. 121 See http://www.gnu.org/software/libtool/manual/html_node/Libtool-versioning.html for information about libtool's versioning system. See also the 122 “Versioning” section below. 123 124 - Any async function which uses non-async-scope callbacks as well as the async ready callback should provide GDestroyNotify callbacks for destroying 125 the user data for those callbacks. See https://bugzilla.gnome.org/show_bug.cgi?id=649728 for details. 126 127 - Any new class’ class structure (e.g. GDataServiceClass) must have reserved slots to allow future API additions of virtual functions without 128 breaking ABI. 129 130Choosing function names 131======================= 132 133In general, use common sense. However, there are some specific cases where a standard is enforced: 134 135 - 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", 136 rather than just "baz". 137 138 - For boolean setters use foo_bar_set_is_baz, rather than foo_bar_set_baz. 139 140 - 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 141 of API to be less cryptic (e.g. "timezone" instead of "ctz"). 142 143Deprecating public API 144====================== 145 146As libgdata moves towards API stability, old API should be deprecated rather than broken or removed entirely. The following should be ensured when 147deprecating API: 148 149 - G_GNUC_DEPRECATED_FOR is added to the API in the public header file. 150 151 - A “Deprecated:” line is added to the gtk-doc comment for the API. This should mention what API replaces it, give a brief explanation of why the 152 API has been deprecated, and finish with “(Since: [version].)” to list the version the API was deprecated. 153 154 - “#ifndef LIBGDATA_DISABLE_DEPRECATED” should be wrapped around the API in the public header file. 155 156 - All references to the API/uses of the API in libgdata code (including demos and the test suite) should be ported to use the replacement API instead. 157 If this isn't possible, the deprecated function should be split into a static function which contains all the code, and the public symbol should 158 become a simple wrapper of this static function. This allows the static function to be used inside libgdata without causing deprecation warnings. 159 160 - Don't remove deprecated symbols from gdata-*.symbols. 161 162 - Don't forget to also deprecate related symbols, such as the getter/setter for a property (or vice-versa). 163 164Commit messages 165=============== 166 167libgdata does not use a ChangeLog; it is auto-generated from the git log when packaging a release. Commit messages should follow the GNOME commit 168message guidelines (https://wiki.gnome.org/Git/CommitMessages), with the exception that when a commit closes a bug, the short explanation of the commit 169should simply be the bug's title, as copied from Bugzilla (e.g. "Bug 579885 – Add code examples to documentation"). The long explanation should then 170be used to give details of the changes. If the bug's title is not relevant, it should be changed before committing the changes. 171 172Unless the short explanation of a commit is a bug title, it should always be prefixed by a tag to describe the part of the library it touches, using 173the following format "tag: Short explanation". The following tags are valid: 174 175 - core: for the core code in the gdata directory, such as GDataEntry. 176 177 - atom: for the Atom-namespaced code in the gdata/atom directory. 178 179 - gcontact: for the gContact-namespaced code in the gdata/gcontact directory. 180 181 - gd: for the GData-namespaced code in the gdata/gd directory. 182 183 - media: for the Media RSS-namespaced code in the gdata/media directory. 184 185 - build: for build changes and releases. 186 187 - docs: for documentation changes which are not specific to a service, such as updates to the docs directory, NEWS, README, this file, etc. 188 189 - tests: for changes to the test code in gdata/tests which are not specific to a service or namespace. 190 191 - demos: for changes to the demo applications in the demos directory. 192 193 - introspection: for introspection annotations and build changes. 194 195 - calendar: for the Google Calendar code in gdata/services/calendar. 196 197 - contacts: for the Google Contacts code in gdata/services/contacts. 198 199 - documents: for the Google Documents code in gdata/services/documents. 200 201 - picasaweb: for the PicasaWeb code in gdata/services/picasaweb. 202 203 - youtube: for the YouTube code in gdata/services/youtube. 204 205The only commits which should not have a tag are translation commits, touching only the po directory. 206 207Versioning 208========== 209 210Starting with version 0.9.0, libgdata has adopted an even–odd/stable–unstable versioning policy, where odd minor version numbers are unstable releases, 211released periodically (with increasing micro version numbers) and leading to a stable release with the next even minor version number. API breaks of 212new API are allowed in micro releases with an odd minor version number, but not in micro releases with an even minor version number. 213 214ABI and API backwards compatibility must be preserved unless the major version number is changed. libgdata is now ABI-stable. 215 216It is encouraged to make a new micro release of an odd minor series after each large API addition or break. 217