monotone

monotone Mtn Source Tree

Root/HACKING

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

Archive Download this file

Branches

Tags

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