1 This file is meant to summarize the Folks development policies.
6 This is the work flow for modifying the master repository:
8 1. File a bug for the given flaw or feature (if it does not already exist) at
9 <https://bugzilla.gnome.org/enter_bug.cgi?product=folks>.
11 2. Clone the main repository (if you haven't already) and start work in a new
12 branch (which preferably includes the bug number in its name).
14 3. If this is a non-trivial flaw or feature, write test cases. We won't accept
15 significant changes without adequate test coverage.
17 4. Write code to fix the flaw or add the feature. In the case that tests are
18 necessary, the new tests must pass consistently.
20 5. All code must follow the project coding style (see below).
22 6. The project must remain buildable with all configure options and pass all
23 tests on all platforms.
25 7. Push your branch to a public repository and attach patch(es) to the bug. Ask
28 8. Rework your code based on suggestions in the review and submit new patches.
29 Return to the review step as necessary.
31 9. Upon approval, pull the latest master branch, rebase your branch upon it, and
32 push the resulting branch to master. Simple!
37 Commits/patches should be as fine-grained as possible (and no finer). Every
38 distinct change should be in its own commit and every commit should be a
39 meaningful change on its own.
41 As much as possible, the full tree should be buildable and pass all tests at
42 every commit. There are exceptions, but they're rare. And, of course, it's more
43 critical that the master branch be buildable (and all tests pass) after every
49 In general, Folks follows the Telepathy-GLib coding style described in
50 <http://telepathy.freedesktop.org/wiki/Style>.
52 Additional general rules
53 ------------------------
55 1. All public symbols which support a Valadoc comment block must have one. This
56 comment block must also be sufficient for gobject-introspection to adequately
57 introspect the symbol for use in other programming languages.
59 2. Include a @since statement in the comment block for new symbols.
64 1. Any functions which could block must be async.
66 2. Use the language-native Errors for error reporting, not return values.
68 3. Take advantage of properties and their automatic notify signals as much as
69 possible (this eliminates the need for most special accessors, mutators, and
70 custom signals and is more conventional).
72 4. Class function blocks should be indented like GNU/Telepathy-GLib if/while
73 blocks. It's arguable that these should be aligned in column 0, as in regular
74 C functions, but it's too late to change this (as it would make 'git blame'
77 5. Private and internal class data members should beging with a _ (public data
78 members and local variables should not begin with a _). This is to make
79 non-public data members instantly recognizable as such (which helps
82 6. Private and internal class functions should begin with a _ (public functions
83 should not begin with a _). This is to make non-public functions instantly
84 recognizable as such (which helps readability).
86 7. Maximize use of the 'var' variable type. This shortens the declarations where
87 it's valid, reducing noise.
89 Rarely, the use of 'var' can obscure the effective type of the variable. In
90 this case, it's acceptable to provide an explicit type.
92 8. Use the 'unowned' modifier when it would prevent a non-trivial amount of
93 memory allocation. This is most commonly true for strings, arrays, and
94 non-reference-counted variables.
96 Do not use 'unowned' for reference-counted variables (like objects) since it
97 reduces readability without benefit. And, as of this writing, bgo#638199
98 forces unowned variables to have an explicit type (preventing the use of
101 9. As in most languages, avoid casting. Casting is usually a sign of an error
102 which should be fixed and reduces readability.
104 10. Refer to non-local variables and methods with their qualified name. Within a
105 class function, refer to private data members like 'this._foo' and foreign
106 package symbols like 'package_name.symbol'.
108 This makes scope immediately clear, helping readability.
110 11. Use nullable types correctly. This helps readability (and makes the
111 programmer's intentions clearer about whether a variable may be null). The
112 ultimate goal is for folks to compile correctly with Vala’s strict-non-null
113 mode enabled (https://live.gnome.org/Vala/Tutorial#Strict_Non-Null_Mode).
114 You can compile folks with strict-non-null mode enabled using:
115 make VALAFLAGS=--enable-experimental-non-null
117 12. Place the (private) member variable declaration for a variable which backs a
118 property next to the (public) property declaration, rather than at the top
119 of the file. This keeps as much of the code pertaining to a property as
120 possible in one location.
122 13. Initialise member variables when declaring them, if possible, rather than in
123 a constructor or construct{} block. If it’s not possible to initialise a
124 member variable at declaration time (e.g. because its value depends on
125 another variable), perform the initialisation in a construct{} block rather
126 than a specific constructor. This means that the initialisation doesn’t have
127 to be copied between multiple alternate constructors.
129 14. When iterating over a MultiMap, try to use the map_iterator().
130 This is more efficient than iterating over the result of get_keys(),
131 then calling get() separately for each key.
136 1. Before pushing commits to the mainline branch, the final commit in the
137 series must successfully build and pass 'make check' consistently.
139 2. After commits have been pushed to mainline, all buildbots must successfully
140 build and pass 'make check' on their next build of Folks. It's up to the
141 committer to ensure this requirement is met and make necessary changes.
146 If a test ever crashes, you'll probably want to run it through gdb. The exact
147 setup work for that is a bit complicated, so we've provided some convenience
148 hooks for each test. Simply run:
150 make -C tests/<dir> <test name>.gdb
152 Then use gdb as normal.
154 To run a single test:
155 make -C tests/<dir> check TESTS=<test name>
157 To run a single test with debugging output:
158 make -C tests/<dir> check TESTS=<test name> CHECK_VERBOSE=1
160 If a test needs to be run through Valgrind for memory debugging, use:
161 make -C tests/<dir> check TESTS=<test name> FOLKS_TEST_VALGRIND=1
163 If a test needs to be run through Callgrind for performance profiling, use:
164 make -C tests/<dir> check TESTS=<test name> FOLKS_TEST_CALLGRIND=1
169 Folks has various profiling points throughout its startup code, in order to be
170 able to profile the startup process. In order to use this:
171 1. Compile folks with --enable-profiling.
172 2. strace -ttt -f -o /tmp/logfile folks-inspect # or some other folks program
173 3. python plot-timeline.py -o output.png /tmp/logfile
174 4. Examine output.png for obvious problems
176 This is based on Federico Mena Quintero’s plot-timeline.py, described on:
177 http://people.gnome.org/~federico/news-2006-03.html#timeline-tools. The Python
178 script itself can be downloaded from
179 http://gitorious.org/projects/performance-scripts.
181 Environment variables
182 =====================
184 FOLKS_BACKEND_STORE_KEY_FILE_PATH sets the keyfile used to control the set
185 of enabled backends. The default is g_get_user_data_dir()/folks/backends.ini,
186 and if it is empty, all backends are enabled.
188 If FOLKS_BACKENDS_ALLOWED is set, it's a space-, comma- or
189 colon-separated list of backends to allow, or "all". If unset, the
190 default is equivalent to "all". Backends not in the list are disallowed,
191 even if enabled in the keyfile or with enable_backend().
193 If FOLKS_BACKENDS_DISABLED is set, it's a space-, comma- or
194 colon-separated list of backends to disallow, or "all". If unset, the
195 default is equivalent to "all". Backends in the list are disallowed,
196 even if enabled in the keyfile or with enable_backend().