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
 115 12. Place the (private) member variable declaration for a variable which backs a
 116     property next to the (public) property declaration, rather than at the top
 117     of the file. This keeps as much of the code pertaining to a property as
 118     possible in one location.
 119
 120 13. Initialise member variables when declaring them, if possible, rather than in
 121     a constructor or construct{} block. If it’s not possible to initialise a
 122     member variable at declaration time (e.g. because its value depends on
 123     another variable), perform the initialisation in a construct{} block rather
 124     than a specific constructor. This means that the initialisation doesn’t have
 125     to be copied between multiple alternate constructors.
 126
 127 Build health
 128 ============
 129
 130 1.  Before pushing commits to the mainline branch, the final commit in the
 131     series must successfully build and pass 'make check' consistently.
 132
 133 2.  After commits have been pushed to mainline, all buildbots must successfully
 134     build and pass 'make check' on their next build of Folks. It's up to the
 135     committer to ensure this requirement is met and make necessary changes.
 136
 137 Debugging tests
 138 ===============
 139
 140 If a test ever crashes, you'll probably want to run it through gdb. The exact
 141 setup work for that is a bit complicated, so we've provided some convenience
 142 hooks for each test. Simply run:
 143
 144         make -C tests/<dir> <test name>.gdb
 145
 146 Then use gdb as normal.
 147
 148 To run a single test:
 149         make -C tests/<dir> check TESTS=<test name>
 150
 151 To run a single test with debugging output:
 152         make -C tests/<dir> check TESTS=<test name> CHECK_VERBOSE=1
 153
 154 If a test needs to be run through Valgrind for memory debugging, use:
 155         make -C tests/<dir> check TESTS=<test name> FOLKS_TEST_VALGRIND=1
 156
 157 Profiling folks
 158 ===============
 159
 160 Folks has various profiling points throughout its startup code, in order to be
 161 able to profile the startup process. In order to use this:
 162  1. Compile folks with --enable-profiling.
 163  2. strace -ttt -f -o /tmp/logfile folks-inspect # or some other folks program
 164  3. python plot-timeline.py -o output.png /tmp/logfile
 165  4. Examine output.png for obvious problems
 166
 167 This is based on Federico Mena Quintero’s plot-timeline.py, described on:
 168 http://people.gnome.org/~federico/news-2006-03.html#timeline-tools. The Python
 169 script itself can be downloaded from
 170 http://gitorious.org/projects/performance-scripts.