1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
|
This file is meant to summarize the Folks development policies.
Code merging
============
This is the work flow for modifying the master repository:
1. File a bug for the given flaw or feature (if it does not already exist) at
<https://bugzilla.gnome.org/enter_bug.cgi?product=folks>.
2. Clone the main repository (if you haven't already) and start work in a new
branch (which preferably includes the bug number in its name).
3. If this is a non-trivial flaw or feature, write test cases. We won't accept
significant changes without adequate test coverage.
4. Write code to fix the flaw or add the feature. In the case that tests are
necessary, the new tests must pass consistently.
5. All code must follow the project coding style (see below).
6. The project must remain buildable with all configure options and pass all
tests on all platforms.
7. Push your branch to a public repository and attach patch(es) to the bug. Ask
for a review.
8. Rework your code based on suggestions in the review and submit new patches.
Return to the review step as necessary.
9. Upon approval, pull the latest master branch, rebase your branch upon it, and
push the resulting branch to master. Simple!
Clean commits
=============
Commits/patches should be as fine-grained as possible (and no finer). Every
distinct change should be in its own commit and every commit should be a
meaningful change on its own.
As much as possible, the full tree should be buildable and pass all tests at
every commit. There are exceptions, but they're rare. And, of course, it's more
critical that the master branch be buildable (and all tests pass) after every
merge.
Coding style
============
In general, Folks follows the Telepathy-GLib coding style described in
<http://telepathy.freedesktop.org/wiki/Style>.
Additional general rules
------------------------
1. All public symbols which support a Valadoc comment block must have one. This
comment block must also be sufficient for gobject-introspection to adequately
introspect the symbol for use in other programming languages.
2. Include a @since statement in the comment block for new symbols.
Vala-specific rules
-------------------
1. Any functions which could block must be async.
2. Use the language-native Errors for error reporting, not return values.
3. Take advantage of properties and their automatic notify signals as much as
possible (this eliminates the need for most special accessors, mutators, and
custom signals and is more conventional).
4. Class function blocks should be indented like GNU/Telepathy-GLib if/while
blocks. It's arguable that these should be aligned in column 0, as in regular
C functions, but it's too late to change this (as it would make 'git blame'
useless).
5. Private and internal class data members should beging with a _ (public data
members and local variables should not begin with a _). This is to make
non-public data members instantly recognizable as such (which helps
readability).
6. Private and internal class functions should begin with a _ (public functions
should not begin with a _). This is to make non-public functions instantly
recognizable as such (which helps readability).
7. Maximize use of the 'var' variable type. This shortens the declarations where
it's valid, reducing noise.
Rarely, the use of 'var' can obscure the effective type of the variable. In
this case, it's acceptable to provide an explicit type.
8. Use the 'unowned' modifier when it would prevent a non-trivial amount of
memory allocation. This is most commonly true for strings, arrays, and
non-reference-counted variables.
Do not use 'unowned' for reference-counted variables (like objects) since it
reduces readability without benefit. And, as of this writing, bgo#638199
forces unowned variables to have an explicit type (preventing the use of
'var').
9. As in most languages, avoid casting. Casting is usually a sign of an error
which should be fixed and reduces readability.
10. Refer to non-local variables and methods with their qualified name. Within a
class function, refer to private data members like 'this._foo' and foreign
package symbols like 'package_name.symbol'.
This makes scope immediately clear, helping readability.
Build health
============
1. Before pushing commits to the mainline branch, the final commit in the
series must successfully build and pass 'make check' consistently.
2. After commits have been pushed to mainline, all buildbots must successfully
build and pass 'make check' on their next build of Folks. It's up to the
committer to ensure this requirement is met and make necessary changes.
Debugging tests
===============
If a test ever crashes, you'll probably want to run it through gdb. The exact
setup work for that is a bit complicated, so we've provided some convenience
hooks for each test. Simply run:
make -C tests/<dir> <test name>.gdb
Then use gdb as normal.
|
