HACKING

   1 This file is meant to summarize the Folks development policies.
   2
   3 Code merging
   4 ============
   5
   6 This is the work flow for modifying the master repository:
   7
   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>.
  10
  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).
  13
  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.
  16
  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.
  19
  20 5. All code must follow the project coding style (see below).
  21
  22 6. The project must remain buildable with all configure options and pass all
  23    tests on all platforms.
  24
  25 7. Push your branch to a public repository and attach patch(es) to the bug. Ask
  26    for a review.
  27
  28 8. Rework your code based on suggestions in the review and submit new patches.
  29    Return to the review step as necessary.
  30
  31 9. Upon approval, pull the latest master branch, rebase your branch upon it, and
  32    push the resulting branch to master. Simple!
  33
  34 Clean commits
  35 =============
  36
  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.
  40
  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
  44 merge.
  45
  46 Coding style
  47 ============
  48
  49 In general, Folks follows the Telepathy-GLib coding style described in
  50 <http://telepathy.freedesktop.org/wiki/Style>.
  51
  52 Additional general rules
  53 ------------------------
  54
  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.
  58
  59 2. Include a @since statement in the comment block for new symbols.
  60
  61 Vala-specific rules
  62 -------------------
  63
  64 1. Any functions which could block must be async.
  65
  66 2. Use the language-native Errors for error reporting, not return values.
  67
  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).
  71
  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'
  75    useless).
  76
  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
  80    readability).
  81
  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).
  85
  86 7. Maximize use of the 'var' variable type. This shortens the declarations where
  87    it's valid, reducing noise.
  88
  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.
  91
  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.
  95
  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
  99    'var').
 100
 101 9. As in most languages, avoid casting. Casting is usually a sign of an error
 102    which should be fixed and reduces readability.
 103
 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'.
 107
 108     This makes scope immediately clear, helping readability.
 109
 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
 116
 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.
 121
 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.
 128
 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.
 132
 133 Build health
 134 ============
 135
 136 1.  Before pushing commits to the mainline branch, the final commit in the
 137     series must successfully build and pass 'make check' consistently.
 138
 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.
 142
 143 Debugging tests
 144 ===============
 145
 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:
 149
 150         make -C tests/<dir> <test name>.gdb
 151
 152 Then use gdb as normal.
 153
 154 To run a single test:
 155         make -C tests/<dir> check TESTS=<test name>
 156
 157 To run a single test with debugging output:
 158         make -C tests/<dir> check TESTS=<test name> CHECK_VERBOSE=1
 159
 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
 162
 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
 165
 166 Profiling folks
 167 ===============
 168
 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
 175
 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.
 180
 181 Environment variables
 182 =====================
 183
 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.
 187
 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().
 192
 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().