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 (requires "set cindent"):
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 third party code and 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, src/base.hh, that should be the very
43first #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 src/base.hh, make sure you keep the "util/audit-includes"
49script consistent 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
53
54Formatting messages
55-------------------
56
57For short messages (single sentence error, warning, info and progress
58messages), we follow the GNU coding standards. However, those are not
59quite enough, and we have developed an extended set of rules to follow
60for messages in english:
61
62 - put single quotes ('') aroung file names and paths, option names,
63 tag names, branch names, command names and commands, as well as
64 any %s that would be expanded to one of those.
65 There is an exception, though: if the quoted item is cited after a
66 colon, either as the last part of the message or on its own line.
67 For example, the following doesn't look very good:
68
69 To apply the changes relative to one of its parents, use:
70 'mtn pluck -r PARENT -r 06c3...'
71
72 The following looks better
73
74 To apply the changes relative to one of its parents, use:
75 mtn pluck -r PARENT -r 06c3...
76
77 - use a Capital first letter in command abstract and description
78 strings. Do not put a period at the end of the abstract, but do
79 so with the description. The following would be very wrong:
80
81 CMD(foo, "foo", "", CMD_REF(foos), "",
82 N_("does the foo thing."),
83 N_("in order to do the foo thing, this allows you to join "
84 "the foo fighters"),
85
86 The following is what it's supposed to look like:
87
88 CMD(foo, "foo", "", CMD_REF(foos), "",
89 N_("Does the foo thing"),
90 N_("In order to do the foo thing, this allows you to join "
91 "the foo fighters."),
92
93 - just as with error messages, use a lowercase first letter in
94 descriptions of options and do not end it with a period. The
95 following would be wrong:
96
97 SIMPLE_OPTION(bar, "bar", bool,
98 gettext_noop("Have the remaining figures go to "
99 "the nearest bar."))
100
101 The following is better:
102
103 SIMPLE_OPTION(bar, "bar", bool,
104 gettext_noop("have the remaining figures go to "
105 "the nearest bar"))
106
107 - for multi-sentence error messages, use a lowercase first letter,
108 but have the second sentence and on start with a Capital letter,
109 and punctuate between sentences. The following is an example that
110 does not follow this rule, and is quite unreadable:
111
112 E(!candidates.empty(), origin::user,
113 F("your request matches no descendents of the current revision\n"
114 "in fact, it doesn't even match the current revision\n"
115 "maybe you want something like --revision=h:%s")
116 % app.opts.branch);
117
118 The proper way to write this message is:
119
120 E(!candidates.empty(), origin::user,
121 F("your request matches no descendents of the current revision.\n"
122 "In fact, it doesn't even match the current revision.\n"
123 "Maybe you want something like --revision=h:%s")
124 % app.opts.branch);
125
126 - proper names, acronyms, function names and variable names must
127 follow their proper capitalization rules. For example, "Botan"
128 and "I/O" must be written that way.
129
130 - "monotone" and "mtn" are proper names with a lower case character,
131 and should always be written with a lower case first character,
132 even though language rules or the rules written here would say
133 otherwise. If you find that troublesome, you might want to
134 consider rephrasing so the sentence doesn't start with "monotone"
135 or "mtn".
136
137 - Please consider that the user has to understand the messages, even
138 though they might not know all the inner details of how monotone
139 works, and might not have a programmer's mind. For example, the
140 following message was hard to understand:
141
142 could not query default database locations
143
144 It has been replaced with the following (which will at least make
145 it clear that this is likely to be a configuration problem and not
146 some inner weirdness in monotone):
147
148 no default database location configured
149
150PLEASE APPLY COMMON SENSE. There are message that will deviate from
151these rules. They should be very few, however.
152
153
154Translation
155-----------
156
157For translators, their language may have a different set of rules for
158things such as quoting (in the french translation, «_ and _» are used
159instead of single quotes, for example) and capitalization. Please use
160your best judgement and be consistent. Still, do not capitalize
161"monotone" or "mtn".
162
163When working on your languages, please do not update any language file
164but your own, as it can be quite annoying for other translators to
165have to deal with merging the changes generated with their current
166work. The best way to deal with this is by updating your language
167files using one of the following methods:
168
169 make ALL_LINGUAS={lang} update-po update-gmo
170
171 make po/{lang}.po-update po/{lang}.gmo
172
173(replace {lang} with your language code)
174
175
176Dialect issues
177--------------
178
179C++ is a big language with a lot of dialects spoken in different
180projects. monotone is no exception; we would prefer submissions
181continued to adhere to the dialect we write in. in particular:
182
183
184 - try to stick to simple functions and data types; don't make big
185 complicated class hierarchies with a lot of interdependencies.
186
187 - avoid pointers whenever possible. if you need to use a handle to a
188 heap allocated object, use a shared_ptr, scoped_ptr, weak_ptr, or
189 the like.
190
191 - if a value has a clearly defined well-formedness condition,
192 encapsulate the value in an object and make the constructors
193 and mutators check the condition. see vocab.hh for string-valued
194 examples.
195
196 - in general, try to express both issues and semantically rich
197 names in the type system. use typedefs to make names more
198 meaningful.
199
200 - avoid returning values, especially large ones. instead, pass a
201 value as a parameter, by reference, clear it and assign into
202 it. this style generally produces fewer invocations of copy
203 constructors, and makes it natural to add multiple, named output
204 parameters from a function.
205
206 - use invariants and logging liberally.
207
208 - make everything as const-correct as possible. make query methods
209 on objects const. make the input parameters to a function const.
210 the word "const" comes after the thing which is constant; for
211 example write "int const" rather than "const int".
212
213 - separate pointer and reference types with space. write "int * foo"
214 rather than "int *foo" or "int* foo".
215
216 - if you have a const, put that _after_ the main type, but before
217 any * or &. Example: "set<revision_id> const & foo".
218
219 - if you are declaring a static array, be aware of a quirk of the
220 language: "foo const * arrayname[]" declares a _non-constant_
221 array of pointers to constant foo. if the array itself will never
222 be modified (true in most cases) you should put a second "const"
223 modifier _after_ the *. this most often comes up with arrays of
224 string constants: write "char const * const arrayname[]" unless
225 you really mean the array to be modifiable.
226
227 - when defining a function, put a carriage return right before the
228 function name, so that the visibility and return type go on the
229 preceeding line. this makes it possible to grep for "^functionname"
230 to find the function definition without its uses.
231
232 - use enums rather than magic constants, if you can.
233
234 - magic constants, when needed, go in constants.{cc,hh}.
235
236 - generally avoid the preprocessor unless you have a matter which is
237 very difficult to express using inlines, reference args,
238 templates, etc.
239
240 - avoid indexing into an array or vector with []. use idx(vec,i),
241 and you will get a nicely informative runtime error when you
242 overflow rather than a crash.
243
244 - avoid recursion, so that you will not overflow the stack on large
245 work sets. use a heap-allocated std::deque<> for breadth-first
246 recursion, std::stack<> for depth-first.
247
248 - generally avoid anything which can generate a SEGV, as it's an
249 uninformative error. prefer errors which say what went wrong.
250
251 - do not use "using namespace <foo>" anywhere. especially do not
252 use "using namespace std".
253
254 - in .cc files, it is preferred to put "using std::foo" at the top
255 for each foo used in the file rather than put "std::" in front of
256 all the uses. this is also the preferred style for symbols from
257 other namespaces when they are used frequently.
258
259 - do not put any "using" declarations in .hh files; use the fully
260 qualified name everywhere necessary.
261
262 - .hh files should include everything that is necessary to parse all
263 of their declarations, but strenuous efforts should be made to
264 keep the number of nested includes to a minimum. wherever
265 possible, use forward declarations (struct foo;) and similar
266 techniques.
267
268 - <iostream> deserves special mention. including this file causes
269 the compiler to emit static constructors to ensure that the
270 standard streams are initialized before their first use.
271 therefore, do not include <iostream> unless you actually refer to
272 one of the standard streams (cin, cout, cerr, clog). use <iosfwd>,
273 <istream>, <ostream>, <fstream>, etc instead, as appropriate. do not,
274 under any circumstances, refer to the standard streams in a header file.
275
276 - it is almost always a mistake to use std::endl instead of '\n'.
277 std::endl writes a newline to the stream *and flushes it*.
278 in monotone this is basically only appropriate when one needs to
279 resynchronize clog and cout (ui.cc:clear_line()), or recover from
280 disabling terminal echo (read_password()). note that it is never
281 necessary to use endl with cerr, as cerr is unbuffered.
282
283 - prefer character constants ('x') to single-character strings ("x") in
284 formatted output sequences.
285
286
287Interfacing with Lua
288--------------------
289
290monotone is extended with hooks written in the Lua language. Code that
291interfaces with Lua must obey the following rules:
292
293 - Lua arrays (tables with numeric indices) are 1-indexed. This is not
294 mandated by the language per se, but the standard libraries assume that
295 and using the arrays otherwise may break hooks that use standard
296 functions.
297
298
299Test suites, and writing test cases
300-----------------------------------
301
302monotone includes a number of unit and integration tests. These can be run
303easily by initiating a 'make check'. The test suite (or, at least, any
304tests potentially affected by your change) should be run before you
305distribute your changes.
306
307Automated build bots run the complete test suite on a regular basis, so
308any problems will be noticed quickly, but it is still faster to find and fix
309any problems locally rather than waiting for the build bots to alert the
310development team of a problem.
311
312All changes to monotone that alter monotone's behaviour should include a new
313test. This includes most changes, but use your judgment about adding tests
314for very small changes. The tests are located in the source tree in the
315test/ directory, documentation on writing tests is available in
316notes/README.testing.
317
318When fixing a bug, check for an existing test case for that bug and
319carefully observe the test case's behaviour before and after your fix. If no
320test case exists, it is strongly recommended to write a test case before
321attempting to fix the bug.
322
323Tip: if the unit tests are failing, the quickest way to find the
324problem is to search the output for the regexp \([0-9]+\) -- i.e., a
325number in parentheses. Or, if using gdb, try setting a breakpoint on
326theboost::unit_test::first_failed_assertion function (see
327results_collector.hpp).
328
329
330Documenting large, user visible or otherwise important changes
331--------------------------------------------------------------
332
333There are changes that are more than mere bug fixes. Those should be
334documented briefly in the NEWS file. Please follow the examples from
335earlier releases in that file.
336Please add the entries in NEWS as part of the change in question, or
337as soon after the change has been committed as possible. That will
338save the release master a lot of hassle at the time of release.
339
340
341Single-character macros
342-----------------------
343
344These are very convenient once you get used to them, but when you
345first look at the code, it can be a bit of a shock to see all these
346bare capital letters scattered around. Here's a quick guide.
347
348 Formatting macros:
349 F("foo %s"):
350 create a formatting object, for display to the user.
351 Translators will translate this string, and F() runs
352 gettext() on its argument. NB: this string should usually
353 _not_ end in a newline.
354 FP("%d foo", "%d foos", n) % n:
355 create a formatting object, with plural handling.
356 Same comments apply as to F().
357 FL("foo %s"):
358 create a raw ("literal") formatting object, mostly for
359 use in logging. This string will _not_ be translated, and
360 gettext() is _not_ called. This is almost always an argument
361 to the L() macro.
362
363 Informational macros:
364 L(FL("foo")):
365 log "foo". Log messages are generally not seen by the
366 user, and are used to debug problems with monotone.
367 P(F("foo")):
368 print "foo". For generic informative messages to the user.
369 W(F("foo")):
370 warn "foo". For warnings to the user.
371
372 Assertion macros (see also the next section). These all cause
373 monotone to exit if their condition is false:
374 I(x != y):
375 "invariant" -- if the condition is not true, then there
376 is a bug in monotone.
377 E(x != y, origin::user, F("x and y are not equal")):
378 "error" -- a general error. The second argument is used to
379 give the system a hint what kind of error that is. One of the
380 origin types in origin_type.hh is possible.
381
382 Tracing macros:
383 MM(x):
384 Mark the given variable as one of the things we are looking
385 at right now. On its own, this statement has no visible
386 effect; but if monotone crashes (that is, an I() check fails)
387 while MM(x) is in scope, then the value of x will be printed
388 to the debug log. This is quite cheap, so feel free to
389 scatter them through your code; this information is _very_
390 useful when trying to understand crashes, especially ones
391 reported by users, that cannot necessarily be reproduced.
392 There are some limitations:
393 -- the object passed to MM must remain in scope as long as the
394 MM does. Code like
395 MM(get_cool_value())
396 will probably crash! Instead say
397 cool_t my_cool_value = get_cool_value();
398 MM(my_cool_value);"
399 -- You can only use MM() once per line. If you say
400 MM(x); MM(y);
401 you will get a compile error. Instead say
402 MM(x);
403 MM(y);
404 -- The object passed to MM() must have a defined "dump"
405 function. You can easily add an overload to "dump" to
406 support new types.
407
408
409"Application state" objects
410---------------------------
411
412There are nine object types which hold a substantial portion of the
413overall state of the program. You will see them frequently in
414argument lists. Most, but not all, of these are allocated only once
415for the entire program.
416
417Because many functions take some of these objects as arguments, we
418have a convention for their position and order: all such arguments
419appear first within the overall argument list, and in the order of
420the list below.
421
422 * "app_state" is being phased out; it used to be an umbrella object
423 carrying almost all the state of the program, with sub-objects of
424 the types listed below. Most of those are now allocated
425 separately, but the options and lua_hooks objects are still under
426 the umbrella. Also, there are a very few operations that are still
427 app_state methods. Do not introduce new functions which take an
428 app_state argument, unless there is no alternative.
429
430 * "options" holds information from all of the command-line options.
431 It does *not* record the non-option command line arguments. Some
432 of its fields may default to other information sources as well.
433
434 To the maximum extent practical, "options" objects should not
435 appear in function arguments. Instead, pass down specific fields
436 that are relevant to the lower-level code.
437
438 * When adding new options, separate words with dash "-" not
439 underscore "_"; dash is easier to type.
440
441 * "lua_hooks" holds the Lua interpreter handle and all the associated
442 state, in particular all the hook functions that the user may
443 override. It is, unfortunately, not possible to pass around single
444 hook functions, so any C++ function that (transitively) calls some
445 hook must get the lua_hooks object somehow.
446
447 * There are three types that encapsulate the database of revisions at
448 different levels of abstraction. No function should take more than
449 one of the following types.
450
451 - "project_t" represents a development project within the
452 database, that is, a database plus a set of branch names and
453 trust decisions.
454
455 - "database" represents the database as a whole, at a level where
456 trust decisions are irrelevant. At present, the database
457 object does do some trust checking and has responsibility for
458 all public key operations (signature checks and nonce
459 encryption); these may be moved to the project object in the
460 future.
461
462 - "sqlite3" is the raw SQLite library handle. Some very
463 low-level internal functions use this instead of a database
464 object. Introducing more of them is to be avoided.
465
466 * "node_id_source" is not really a top-level state object, but if a
467 function takes one of them, it goes right after the database in the
468 argument list.
469
470 * "key_store" holds the user's private keys, and is responsible for all
471 private key operations (creating signatures and decrypting nonces).
472
473 * "workspace" is responsible for manipulating checked-out source trees.
474
475
476Reporting errors to the user
477----------------------------
478
479monotone has a number of assertion macros available for different
480situations. These assertion macros are divided into two categories:
481invariants and general errors.
482
483Invariants assert that monotone's internal state is in the expected state.
484An invariant failure indicates that there is a bug in monotone. e.g.
485
486 I(r_working.edges.size() == 1);
487
488Error conditions handle most other error cases, where monotone is unable to
489complete an operation due to an error, but that error is not caused by a bug
490in monotone, e.g.
491
492 E(converted != NULL, origin::system,
493 F("failed to convert string from %s to %s: '%s'")
494 % src_charset % dst_charset % src);
495
496Each of these assertion macros are fatal and will cause an exception to be
497thrown that will ultimately cause the monotone process to exit. Exceptions
498are used (rather than C-style abort() based assertions) so that the stack
499will unwind and cause the destructors for objects allocated on the stack to
500run. This allows monotone to leave the user's database and workspace in
501as logical a state as possible. Any in-flight uncommitted database
502transactions will be aborted. Operations occurring on a workspace may
503leave the workspace in an inconsistent state, as we do not have a way to
504atomically update the workspace.
505
506
507Patch submission guidelines
508---------------------------
509
510Register an account on our code forge at <https://code.monotone.ca> and go to
511the "Issues" view of the "monotone" project listed there. Then create a
512separate issue for the patch you want to send; describe it briefly in the
513issue's title and explain the reasoning more in detail in the description
514text. Afterwards append the patch file to the issue so we can review and
515comment on it. Please do not paste or upload it somewhere else, external
516resources tend to expire from time to time and we would like to preserve
517the information as they are as long as possible. Please do also not include
518your patch inline in the issue's description, so its formatting is not
519destroyed.
520
521If you prefer old-style mail, send your patches to 'monotone-devel@nongnu.org'
522with a subject beginning with '[PATCH]', again followed by a brief description of
523the patch. The body of the message should then also contain more information
524with reasoning for why the changes are required. Patches may be included inline
525in a message, or attached as a text/plain, text/x-diff, or text/x-patch attachment.
526Make sure your mailer does not mangle the patch (e.g. by wrapping lines in the
527patch) before sending your patch to the list.
528
529All changes to the monotone source require an accompanying commit message, so
530please add a prepared commit message to your submission, as it will make our
531lives a little easier.
532
533Any changes that affect the user interface (e.g. adding command-line
534options, changing the output format) or affect the documented behaviour of
535monotone must include appropriate changes to the documentation. Please also
536think about adding unit and / or functional tests for bug fixes or new features
537in your patch.
538
539Finally, please review your patch prior to submission, to not include
540accidental white-space-only changes or changes to the language
541files. Usually you should revert po/*.po files before generating a
542patch - unfortunately these are often changed when you build but do
543not contain any reasonable changes. Alternatively restrict mtn diff to
544the files you've actually changed.
545
546The monotone development team will review and comment on all patches on a
547best-efforts basis. Patches are never ignored, but a patch may not be
548discussed or applied immediately according to the amount of spare time the
549developers have. Don't be discouraged if you don't receive an immediate
550response, and if you feel that your patch has slipped through the cracks,
551post a follow up reminder message with a pointer to the original issue
552or message to the mailing list archives.
553
554
555Third-party code
556----------------
557
558monotone used to include a number of libraries directly in its source
559tree for a long time. Today we prefer to keep big external sources
560outside of our tree, with the exception of our network library "Netxx"
561which has been abandoned by its original author long ago and which has
562also seen minor modifications from our side in the meantime.
563
564So if you write new code that depends on third-party code or libraries,
565then try to rely on packaged versions of this code as much as possible.
566If this is impractical, for example because its only one file or even
567a single method you need, check the copyrights of the code in question for
568compatibility with the GPL that is used for monotone and add individual
569copyrights to the AUTHORS file before you copy it into monotone's
570source tree.
571
572Also from time to time, bug fixes to third-party code are required. These
573fixes should be made in the monotone versions of the code first to solve the
574immediate problem. In all cases that make sense (i.e. for general bug
575fixes), the change should also be sent to the upstream developers for
576inclusion in the next release.
577
578In a small number of cases, a change made to our local version of the
579third-party code may not make sense to send upstream. In this case,
580make a note of this in the file you're changing and in your commit
581message so that this permanent deviation is documented.
582
583
584Compiling Hints
585---------------
586
587 - monotone's compilation time can be improved significantly by compiling
588 with 'CXXFLAGS=-O0'. Note that disabling optimisation makes the resultant
589 binary significantly slower - don't bother using it for performance
590 profiling.
591
592 - precompiled headers can be enabled by running 'configure' with --enable-pch
593 This should give shorter compile times, given boost's extensive use of
594 templates. Some versions of gcc have issues with precompiled headers, so if
595 you get strange compilation errors, try disabling them.
596
597 - ccache (http://ccache.samba.org/) is quite effective for speeding up
598 repeated compiles of the same source

Archive Download this file

Branches

Tags

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