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
42There is a special header file, base.hh, that should be the very first
43#include in every .cc file, without exception. It makes a small
44number of inclusions and declarations that we want to be globally
45visible. Do not include this header in any other header file;
46however, in header files, assume the contents of base.hh are already
47visible. "make distcheck" will verify that these rules are followed.
48If you modify base.hh, make sure you keep the "audit-includes" script
49consistent with it. Try not to add things to base.hh; it's intended
50to be a minimal set of declarations that really do need to be visible
51everywhere.
52
53Dialect issues
54--------------
55
56C++ is a big language with a lot of dialects spoken in different
57projects. monotone is no exception; we would prefer submissions
58continued to adhere to the dialect we write in. in particular:
59
60
61 - try to stick to simple functions and data types; don't make big
62 complicated class hierarchies with a lot of interdependencies.
63
64 - avoid pointers whenever possible. if you need to use a handle to a
65 heap allocated object, use a shared_ptr, scoped_ptr, weak_ptr, or
66 the like.
67
68 - if a value has a clearly defined well-formedness condition,
69 encapsulate the value in an object and make the constructors
70 and mutators check the condition. see vocab.hh for string-valued
71 examples.
72
73 - in general, try to express both issues and semantically rich
74 names in the type system. use typedefs to make names more
75 meaningful.
76
77 - avoid returning values, especially large ones. instead, pass a
78 value as a parameter, by reference, clear it and assign into
79 it. this style generally produces fewer invocations of copy
80 constructors, and makes it natural to add multiple, named output
81 parameters from a function.
82
83 - use invariants and logging liberally.
84
85 - make everything as const-correct as possible. make query methods
86 on objects const. make the input parameters to a function const.
87 the word "const" comes after the thing which is constant; for
88 example write "int const" rather than "const int".
89
90 - separate pointer and reference types with space. write "int * foo"
91 rather than "int *foo" or "int* foo".
92
93 - if you have a const, put that _after_ the main type, but before
94 any * or &. Example: "set<revision_id> const & foo".
95
96 - if you are declaring a static array, be aware of a quirk of the
97 language: "foo const * arrayname[]" declares a _non-constant_
98 array of pointers to constant foo. if the array itself will never
99 be modified (true in most cases) you should put a second "const"
100 modifier _after_ the *. this most often comes up with arrays of
101 string constants: write "char const * const arrayname[]" unless
102 you really mean the array to be modifiable.
103
104 - when defining a function, put a carriage return right before the
105 function name, so that the visibility and return type go on the
106 preceeding line. this makes it possible to grep for "^functionname"
107 to find the function definition without its uses.
108
109 - use enums rather than magic constants, if you can.
110
111 - magic constants, when needed, go in constants.{cc,hh}.
112
113 - generally avoid the preprocessor unless you have a matter which is
114 very difficult to express using inlines, reference args,
115 templates, etc.
116
117 - avoid indexing into an array or vector with []. use idx(vec,i),
118 and you will get a nicely informative runtime error when you
119 overflow rather than a crash.
120
121 - avoid recursion, so that you will not overflow the stack on large
122 work sets. use a heap-allocated std::deque<> for breadth-first
123 recursion, std::stack<> for depth-first.
124
125 - generally avoid anything which can generate a SEGV, as it's an
126 uninformative error. prefer errors which say what went wrong.
127
128 - do not use "using namespace <foo>" anywhere. especially do not
129 use "using namespace std".
130
131 - in .cc files, it is preferred to put "using std::foo" at the top
132 for each foo used in the file rather than put "std::" in front of
133 all the uses. this is also the preferred style for symbols from
134 other namespaces when they are used frequently.
135
136 - do not put any "using" declarations in .hh files; use the fully
137 qualified name everywhere necessary.
138
139 - .hh files should include everything that is necessary to parse all
140 of their declarations, but strenuous efforts should be made to
141 keep the number of nested includes to a minimum. wherever
142 possible, use forward declarations (struct foo;) and similar
143 techniques.
144
145 - <iostream> deserves special mention. including this file causes
146 the compiler to emit static constructors to ensure that the
147 standard streams are initialized before their first use.
148 therefore, do not include <iostream> unless you actually refer to
149 one of the standard streams (cin, cout, cerr, clog). use <iosfwd>,
150 <istream>, <ostream>, <fstream>, etc instead, as appropriate. do not,
151 under any circumstances, refer to the standard streams in a header file.
152
153 - it is almost always a mistake to use std::endl instead of '\n'.
154 std::endl writes a newline to the stream *and flushes it*.
155 in monotone this is basically only appropriate when one needs to
156 resynchronize clog and cout (ui.cc:clear_line()), or recover from
157 disabling terminal echo (read_password()). note that it is never
158 necessary to use endl with cerr, as cerr is unbuffered.
159
160 - prefer character constants ('x') to single-character strings ("x") in
161 formatted output sequences.
162
163Interfacing with Lua
164--------------------
165
166monotone is extended with hooks written in the Lua language. Code that
167interfaces with Lua must obey the following rules:
168
169 - Lua arrays (tables with numeric indices) are 1-indexed. This is not
170 mandated by the language per se, but the standard libraries assume that
171 and using the arrays otherwise may break hooks that use standard
172 functions.
173
174Test suites, and writing test cases
175----------------------------------
176
177monotone includes a number of unit and integration tests. These can be run
178easily by initiating a 'make check'. The test suite (or, at least, any
179tests potentially affected by your change) should be run before you
180distribute your changes.
181
182Automated build bots run the complete test suite on a regular basis, so
183any problems will be noticed quickly, but it is still faster to find and fix
184any problems locally rather than waiting for the build bots to alert the
185development team of a problem.
186
187All changes to monotone that alter monotone's behaviour should include a new
188test. This includes most changes, but use your judgment about adding tests
189for very small changes.. The tests are located in the source tree in the
190tests/ directory, documentation on writing tests is available in
191tests/README.
192
193When fixing a bug, check for an existing test case for that bug and
194carefully observe the test case's behaviour before and after your fix. If no
195test case exists, it is strongly recommended to write a test case before
196attempting to fix the bug.
197
198Tip: if the unit tests are failing, the quickest way to find the
199problem is to search the output for the regexp \([0-9]+\) -- i.e., a
200number in parentheses. Or, if using gdb, try setting a breakpoint on
201theboost::unit_test::first_failed_assertion function (see
202results_collector.hpp).
203
204Documenting large, user visible or otherwise important changes
205--------------------------------------------------------------
206
207There are changes that are more than mere bug fixes. Those should be
208documented briefly in the NEWS file. Please follow the examples from
209earlier releases in that file.
210Please add the entries in NEWS as part of the change in question, or
211as soon after the change has been committed as possible. That will
212save the release master a lot of hassle at the time of release.
213
214Single-character macros
215-----------------------
216
217These are very convenient once you get used to them, but when you
218first look at the code, it can be a bit of a shock to see all these
219bare capital letters scattered around. Here's a quick guide.
220
221 Formatting macros:
222 F("foo %s"): create a formatting object, for display to the user.
223 Translators will translate this string, and F() runs
224 gettext() on its argument. NB: this string should usually
225 _not_ end in a newline.
226 FP("%d foo", "%d foos", n) % n: create a formatting object, with
227 plural handling. Same comments apply as to F().
228 FL("foo %s"): create a raw ("literal") formatting object, mostly for
229 use in logging. This string will _not_ be translated, and
230 gettext() is _not_ called. This is almost always an argument
231 to the L() macro:
232
233 Informational macros:
234 L(FL("foo")): log "foo". Log messages are generally not seen by the
235 user, and are used to debug problems with monotone.
236 P(F("foo")): print "foo". For generic informative messages to the
237 user.
238 W(F("foo")): warn "foo". For warnings to the user.
239
240 Assertion macros (see also the next section). These all cause
241 monotone to exit if their condition is false:
242 I(x != y): "invariant" -- if the condition is not true, then there
243 is a bug in monotone.
244 N(x != y, F("make x and y equal")): "naughty" -- the user
245 requested something that doesn't make sense, they should fix
246 that.
247 E(x != y, F("x and y are not equal")): "error" -- not a bug in
248 monotone, not necessarily the users fault... dunno boss, it
249 just isn't working!
250
251 Tracing macros:
252 MM(x): Mark the given variable as one of the things we are looking
253 at right now. On its own, this statement has no visible
254 effect; but if monotone crashes (that is, an I() check fails)
255 while MM(x) is in scope, then the value of x will be printed
256 to the debug log. This is quite cheap, so feel free to
257 scatter them through your code; this information is _very_
258 useful when trying to understand crashes, especially ones
259 reported by users, that cannot necessarily be reproduced.
260 There are some limitations:
261 -- the object passed to MM must remain in scope as long as the
262 MM does. Code like
263 MM(get_cool_value())
264 will probably crash! Instead say
265 cool_t my_cool_value = get_cool_value();
266 MM(my_cool_value);"
267 -- You can only use MM() once per line. If you say
268 MM(x); MM(y);
269 you will get a compile error. Instead say
270 MM(x);
271 MM(y);
272 -- The object passed to MM() must have a defined "dump"
273 function. You can easily add an overload to "dump" to
274 support new types.
275
276"Application state" objects
277---------------------------
278
279There are nine object types which hold a substantial portion of the
280overall state of the program. You will see them frequently in
281argument lists. Most, but not all, of these are allocated only once
282for the entire program.
283
284Because many functions take some of these objects as arguments, we
285have a convention for their position and order: all such arguments
286appear first within the overall argument list, and in the order of
287the list below.
288
289 * "app_state" is being phased out; it used to be an umbrella object
290 carrying almost all the state of the program, with sub-objects of
291 the types listed below. Most of those are now allocated
292 separately, but the options and lua_hooks objects are still under
293 the umbrella. Also, there are a very few operations that are still
294 app_state methods. Do not introduce new functions which take an
295 app_state argument, unless there is no alternative.
296
297 * "options" holds information from all of the command-line options.
298 It does *not* record the non-option command line arguments. Some
299 of its fields may default to other information sources as well.
300
301 To the maximum extent practical, "options" objects should not
302 appear in function arguments. Instead, pass down specific fields
303 that are relevant to the lower-level code.
304
305 * When adding new options, separate words with dash "-" not
306 underscore "_"; dash is easier to type.
307
308 * "lua_hooks" holds the Lua interpreter handle and all the associated
309 state, in particular all the hook functions that the user may
310 override. It is, unfortunately, not possible to pass around single
311 hook functions, so any C++ function that (transitively) calls some
312 hook must get the lua_hooks object somehow.
313
314 * There are three types that encapsulate the database of revisions at
315 different levels of abstraction. No function should take more than
316 one of the following types.
317
318 - "project_t" represents a development project within the
319 database, that is, a database plus a set of branch names and
320 trust decisions.
321
322 - "database" represents the database as a whole, at a level where
323 trust decisions are irrelevant. At present, the database
324 object does do some trust checking and has responsibility for
325 all public key operations (signature checks and nonce
326 encryption); these may be moved to the project object in the
327 future.
328
329 - "sqlite3" is the raw SQLite library handle. Some very
330 low-level internal functions use this instead of a database
331 object. Introducing more of them is to be avoided.
332
333 * "node_id_source" is not really a top-level state object, but if a
334 function takes one of them, it goes right after the database in the
335 argument list.
336
337 * "key_store" holds the user's private keys, and is responsible for all
338 private key operations (creating signatures and decrypting nonces).
339
340 * "workspace" is responsible for manipulating checked-out source trees.
341
342Reporting errors to the user
343----------------------------
344
345monotone has a number of assertion macros available for different
346situations. These assertion macros are divided into three categories:
347invariants, user naughtiness, and general errors.
348
349Invariants assert that monotone's internal state is in the expected state.
350An invariant failure indicates that there is a bug in monotone. e.g.
351
352 I(r_working.edges.size() == 1);
353
354User naughtiness handles error conditions where the user has asked monotone
355to do something it is unable to. e.g.
356
357 N(!completions.empty(),
358 F("no match for selection '%s'") % str);
359
360Error conditions handle most other error cases, where monotone is unable to
361complete an operation due to an error, but that error is not caused by a bug
362in monotone or explicit user error. e.g.
363
364 E(converted != NULL,
365 F("failed to convert string from %s to %s: '%s'")
366 % src_charset % dst_charset % src);
367
368Each of these assertion macros are fatal and will cause an exception to be
369thrown that will ultimately cause the monotone process to exit. Exceptions
370are used (rather than C-style abort() based assertions) so that the stack
371will unwind and cause the destructors for objects allocated on the stack to
372run. This allows monotone to leave the user's database and workspace in
373as logical a state as possible. Any in-flight uncommitted database
374transactions will be aborted. Operations occurring on a workspace may
375leave the workspace in an inconsistent state, as we do not have a way to
376atomically update the workspace.
377
378
379Patch submission guidelines
380---------------------------
381
382Mail patches to 'monotone-devel@nongnu.org' with a subject beginning with
383'[PATCH]' and followed by a brief description of the patch. The body of the
384message should contain a description of the patch with reasoning for why the
385changes are required, followed by a prepared commit message. Patches may
386be included inline in a message, or attached as a text/plain, text/x-diff,
387or text/x-patch attachment. Make sure your mailer does not mangle the
388patch (e.g. by wrapping lines in the patch) before sending your patch to the
389list.
390
391All changes to the monotone source require an accompanying commit message.
392Any changes that affect the user interface (e.g. adding command-line
393options, changing the output format) or affect the documented behaviour of
394monotone must include appropriate changes to the documentation.
395
396Please review your patch prior to submission, to not include
397accidental white-space-only changes or changes to the language
398files. Usually you should revert po/*.po files before generating a
399patch - unfortunately these are often changed when you build but do
400not contain any reasonable changes. Alternatively restrict mtn diff to
401the files you've actually changed.
402
403The monotone development team review and comment on all patches on a
404best-efforts basis. Patches are never ignored, but a patch may not be
405discussed or applied immediately according to the amount of spare time the
406developers have. Don't be discouraged if you don't receive an immediate
407response, and if you feel that your patch has slipped through the cracks,
408post a follow up reminder message with a pointer to the original message in
409the mailing list archives.
410
411
412Third-party code
413----------------
414
415monotone contains parts of a number of third-party libraries, including but
416not limited to: Lua, Popt, Botan, SQLite, Netxx, and libidn. See AUTHORS
417for complete details on the included third-party code and the copyrights and
418licenses of each portion.
419
420From time to time, bug fixes to this third-party code are required. These
421fixes should be made in the monotone versions of the code first to solve the
422immediate problem. In all cases that make sense (i.e. for general bug
423fixes), the change should also be sent to the upstream developers for
424inclusion in the next release.
425
426In a small number of cases, a change made to our local version of the
427third-party code may not make sense to send upstream. In this case,
428make a note of this in the file you're changing and in your commit
429message so that this permanent deviation is documented.
430
431
432Compiling Hints
433---------------
434
435 - monotone's compilation time can be improved significantly by compiling
436 with 'CXXFLAGS=-O0'. Note that disabling optimisation makes the resultant
437 binary significantly slower - don't bother using it for performance
438 profiling.
439
440 - precompiled headers can be enabled by running 'configure' with --enable-pch
441 This should give shorter compile times, given boost's extensive use of
442 templates. Some versions of gcc have issues with precompiled headers, so if
443 you get strange compilation errors, try disabling them.
444
445 - ccache (http://ccache.samba.org/) is quite effective for speeding up
446 repeated compiles of the same source

Archive Download this file

Branches

Tags

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