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.
113 1. Before pushing commits to the mainline branch, the final commit in the
114 series must successfully build and pass 'make check' consistently.
116 2. After commits have been pushed to mainline, all buildbots must successfully
117 build and pass 'make check' on their next build of Folks. It's up to the
118 committer to ensure this requirement is met and make necessary changes.
123 If a test ever crashes, you'll probably want to run it through gdb. The exact
124 setup work for that is a bit complicated, so we've provided some convenience
125 hooks for each test. Simply run:
127 make -C tests/<dir> <test name>.gdb
129 Then use gdb as normal.