monotone

monotone Mtn Source Tree

Root/HACKING

1Contributing to monotone
2========================
3
4Coding standards
5----------------
6
7Code is largely formatted according to the GNU coding standards, but there
8are minor deviations. Where the coding style differs from the standard
9please follow the coding style of the particular file you're making changes
10to so that formatting consistency is retained within that file.
11
12All source indentation should be done using spaces, with two space
13characters per indentation level.
14
15The appropriate Emacs modeline to use for editing source is:
16
17-*- mode: C++; c-file-style: "gnu"; indent-tabs-mode: nil; c-basic-offset: 2 -*-
18
19And something close (but not perfect) for VIM:
20
21vim: et:sw=2:sts=2:ts=2:cino=>2s,{s,\:s,+s,t0,g0,^-2,e-2,n-2,p2s,(0,=s:
22
23monotone's source includes a number of third party libraries. These have
24been imported from upstream, and should retain the original coding style of
25the particular library in all cases. This makes life easier when a
26developer needs to send our fixes upstream or wants to import new upstream
27versions into monotone.
28
29
30Dialect issues
31--------------
32
33C++ is a big language with a lot of dialects spoken in different
34projects. monotone is no exception; we would prefer submissions
35continued to adhere to the dialect we write in. in particular:
36
37
38 - try to stick to simple functions and data types; don't make big
39 complicated class hierarchies with a lot of interdependencies.
40
41 - avoid pointers whenever possible. if you need to use a handle to a
42 heap allocated object, use a shared_ptr, scoped_ptr, weak_ptr, or
43 the like.
44
45 - if a value has a clearly defined well-formedness condition,
46 encapsulate the value in an object and make the constructors
47 and mutators check the condition. see vocab.hh for string-valued
48 examples.
49
50 - in general, try to express both issues and semantically rich
51 names in the type system. use typedefs to make names more
52 meaningful.
53
54 - avoid returning values, especially large ones. instead, pass a
55 value as a parameter, by reference, clear it and assign into
56 it. this style generally produces fewer invocations of copy
57 constructors, and makes it natural to add multiple, named output
58 parameters from a function.
59
60 - use invariants and logging liberally.
61
62 - make everything as const-correct as possible. make query methods
63 on objects const. make the input parameters to a function const.
64 the word "const" comes after the thing which is constant; for
65 example write "int const" rather than "const int".
66
67 - separate pointer and reference types with space. write "int * foo"
68 rather than "int *foo" or "int* foo".
69
70 - put the name of a function in the first column of the line it
71 occurs on. the visibility and return type go on the preceeding
72 line.
73
74 - use enums rather than magic constants, if you can.
75
76 - magic constants, when needed, go in constants.{cc,hh}.
77
78 - generally avoid the preprocessor unless you have a matter which is
79 very difficult to express using inlines, reference args,
80 templates, etc.
81
82 - avoid indexing into an array or vector with []. use idx(vec,i),
83 and you will get a nicely informative runtime error when you
84 overflow rather than a crash.
85
86 - avoid recursion, so that you will not overflow the stack on large
87 work sets. use a heap-allocated std::deque<> for breadth-first
88 recursion, std::stack<> for depth-first.
89
90 - generally avoid anything which can generate a SEGV, as it's an
91 uninformative error. prefer errors which say what went wrong.
92
93 - for importing symbols in other namespaces add a "using std::foo"
94 for each foo used in the file and then strip "std::" from the uses.
95 do not use "using namespace std" anywhere.
96
97
98Test suites, and writing test cases
99----------------------------------
100
101monotone includes a number of unit and integration tests. These can be run
102easily by initiating a 'make check'. The test suite (or, at least, any
103tests potentially affected by your change) should be run before you
104distribute your changes.
105
106Automated build bots run the complete test suite on a regularly basis, so
107any problems will be noticed quickly, but it is still faster to find and fix
108any problems locally rather than waiting for the build bots to alert the
109development team of a problem.
110
111All changes to monotone that alter monotone's behaviour should include a new
112test. This includes most changes, but use your judgment about adding tests
113for very small changes.. The tests are located in the source tree in the
114tests/ directory, documentation on writing tests is available in
115tests/README.
116
117When fixing a bug, check for an existing test case for that bug and
118carefully observe the test case's behaviour before and after your fix. If no
119test case exists, it is strongly recommended to write a test case before
120attempting to fix the bug.
121
122Tip: if the unit tests are failing, the quickest way to find the
123problem is to search the output for the regexp \([0-9]+\) -- i.e., a
124number in parentheses. Or, if using gdb, try setting a breakpoint on
125theboost::unit_test::first_failed_assertion function (see
126results_collector.hpp).
127
128
129Single-character macros
130-----------------------
131
132These are very convenient once you get used to them, but when you
133first look at the code, it can be a bit of a shock to see all these
134bare capital letters scattered around. Here's a quick guide.
135
136 Formatting macros:
137 F("foo %s"): create a formatting object, for display to the user.
138 Translators will translate this string, and F() runs
139 gettext() on its argument. NB: this string should usually
140 _not_ end in a newline.
141 FP("%d foo", "%d foos", n) % n: create a formatting object, with
142 plural handling. Same comments apply as to F().
143 FL("foo %s"): create a raw ("literal") formatting object, mostly for
144 use in logging. This string will _not_ be translated, and
145 gettext() is _not_ called. This is almost always an argument
146 to the L() macro:
147
148 Informational macros:
149 L(FL("foo")): log "foo". Log messages are generally not seen by the
150 user, and are used to debug problems with monotone.
151 P(F("foo")): print "foo". For generic informative messages to the
152 user.
153 W(F("foo")): warn "foo". For warnings to the user.
154
155 Assertion macros (see also the next section). These all cause
156 monotone to exit if their condition is false:
157 I(x != y): "invariant" -- if the condition is not true, then there
158 is a bug in monotone.
159 N(x != y, F("make x and y equal")): "naughty" -- the user
160 requested something that doesn't make sense, they should fix
161 that.
162 E(x != y, F("x and y are not equal")): "error" -- not a bug in
163 monotone, not necessarily the users fault... dunno boss, it
164 just isn't working!
165
166 Tracing macros:
167 MM(x): Mark the given variable as one of the things we are looking
168 at right now. On its own, this statement has no visible
169 effect; but if monotone crashes (that is, an I() check fails)
170 while MM(x) is in scope, then the value of x will be printed
171 to the debug log. This is quite cheap, so feel free to
172 scatter them through your code; this information is _very_
173 useful when trying to understand crashes, especially ones
174 reported by users, that cannot necessarily be reproduced.
175 There are some limitations:
176 -- the object passed to MM must remain in scope as long as the
177 MM does. Code like
178 MM(get_cool_value())
179 will probably crash! Instead say
180 cool_t my_cool_value = get_cool_value();
181 MM(my_cool_value);"
182 -- You can only use MM() once per line. If you say
183 MM(x); MM(y);
184 you will get a compile error. Instead say
185 MM(x);
186 MM(y);
187 -- The object passed to MM() must have a defined "dump"
188 function. You can easily add an overload to "dump" to
189 support new types.
190
191Reporting errors to the user
192----------------------------
193
194monotone has a number of assertion macros available for different
195situations. These assertion macros are divided into three categories:
196invariants, user naughtiness, and general errors.
197
198Invariants assert that monotone's internal state is in the expected state.
199An invariant failure indicates that there is a bug in monotone. e.g.
200
201 I(r_working.edges.size() == 1);
202
203User naughtiness handles error conditions where the user has asked monotone
204to do something it is unable to. e.g.
205
206 N(completions.size() != 0,
207 F("no match for selection '%s'") % str);
208
209Error conditions handle most other error cases, where monotone is unable to
210complete an operation due to an error, but that error is not caused by a bug
211in monotone or explicit user error. e.g.
212
213 E(converted != NULL,
214 F("failed to convert string from %s to %s: '%s'")
215 % src_charset % dst_charset % src);
216
217Each of these assertion macros are fatal and will cause an exception to be
218thrown that will ultimately cause the monotone process to exit. Exceptions
219are used (rather than C-style abort() based assertions) so that the stack
220will unwind and cause the destructors for objects allocated on the stack to
221run. This allows monotone to leave the user's database and workspace in
222as logical a state as possible. Any in-flight uncommitted database
223transactions will be aborted. Operations occurring on a workspace may
224leave the workspace in an inconsistent state, as we do not have a way to
225atomically update the workspace.
226
227
228Patch submission guidelines
229---------------------------
230
231Mail patches to 'monotone-devel@nongnu.org' with a subject beginning with
232'[PATCH]' and followed by a brief description of the patch. The body of the
233message should contain a description of the patch with reasoning for why the
234changes are required, followed by a prepared ChangeLog entry. Patches may
235be included inline in a message, or attached as a text/plain, text/x-diff,
236or text/x-patch attachment. Make sure your mailer does not mangle the
237patch (e.g. by wrapping lines in the patch) before sending your patch to the
238list.
239
240All changes to the monotone source require an accompanying ChangeLog entry.
241Any changes that affect the user interface (e.g. adding command-line
242options, changing the output format) or affect the documented behaviour of
243monotone must include appropriate changes to the documentation.
244
245The monotone development team review and comment on all patches on a
246best-efforts basis. Patches are never ignored, but a patch may not be
247discussed or applied immediately according to the amount of spare time the
248developers have. Don't be discouraged if you don't receive an immediate
249response, and if you feel that your patch has slipped through the cracks,
250post a follow up reminder message with a pointer to the original message in
251the mailing list archives.
252
253
254Third-party code
255----------------
256
257monotone contains parts of a number of third-party libraries, including but
258not limited to: Lua, Popt, Crypto++, SQLite, Netxx, and libidn. See AUTHORS
259for complete details on the included third-party code and the copyrights and
260licenses of each portion.
261
262From time to time, bug fixes to this third-party code are required. These
263fixes should be made in the monotone versions of the code first to solve the
264immediate problem. In all cases that make sense (i.e. for general bug
265fixes), the change should also be sent to the upstream developers for
266inclusion in the next release.
267
268In a small number of cases, a change made to our local version of the
269third-party code may not make sense to send upstream. In this case, make a
270note of this in the file you're changing and in the ChangeLog so that this
271permanent deviation is documented.
272
273
274Compiling Hints
275---------------
276
277 - monotone's compilation time can be improved significantly by compiling
278 with 'CXXFLAGS=-O0'. Note that disabling optimisation makes the resultant
279 binary significantly slower - don't bother using it for performance
280 profiling.
281
282 - precompiled headers can be enabled by running 'configure' with --enable-pch
283 This should give shorter compile times, given boost's extensive use of
284 templates. Some versions of gcc have issues with precompiled headers, so if
285 you get strange compilation errors, try disabling them.
286
287 - ccache (http://ccache.samba.org/) is quite effective for speeding up
288 repeated compiles of the same source.

Archive Download this file

Branches

Tags

Quick Links:     www.monotone.ca    -     Downloads    -     Documentation    -     Wiki    -     Code Forge    -     Build Status