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
94Test suites, and writing test cases
95----------------------------------
96
97monotone includes a number of unit and integration tests. These can be run
98easily by initiating a 'make check'. The test suite (or, at least, any
99tests potentially affected by your change) should be run before you
100distribute your changes.
101
102Automated build bots run the complete test suite on a regularly basis, so
103any problems will be noticed quickly, but it is still faster to find and fix
104any problems locally rather than waiting for the build bots to alert the
105development team of a problem.
106
107All changes to monotone that alter monotone's behaviour should include a new
108test. This includes most changes, but use your judgment about adding tests
109for very small changes.. The tests are located in the source tree in the
110tests/ directory, documentation on writing tests is available in
111tests/README.
112
113When fixing a bug, check for an existing test case for that bug and
114carefully observe the test case's behaviour before and after your fix. If no
115test case exists, it is strongly recommended to write a test case before
116attempting to fix the bug.
117
118
119Reporting errors to the user
120----------------------------
121
122monotone has a number of assertion macros available for different
123situations. These assertion macros are divided into three categories:
124invariants, user naughtiness, and general errors.
125
126Invariants assert that monotone's internal state is in the expected state.
127An invariant failure indicates that there is a bug in monotone. e.g.
128
129 I(r_working.edges.size() == 1);
130
131User naughtiness handles error conditions where the user has asked monotone
132to do something it is unable to. e.g.
133
134 N(completions.size() != 0,
135 F("no match for selection '%s'") % str);
136
137Error conditions handle most other error cases, where monotone is unable to
138complete an operation due to an error, but that error is not caused by a bug
139in monotone or explicit user error. e.g.
140
141 E(converted != NULL,
142 F("failed to convert string from %s to %s: '%s'")
143 % src_charset % dst_charset % src);
144
145Each of these assertion macros are fatal and will cause an exception to be
146thrown that will ultimately cause the monotone process to exit. Exceptions
147are used (rather than C-style abort() based assertions) so that the stack
148will unwind and cause the destructors for objects allocated on the stack to
149run. This allows monotone to leave the user's database and working copy in
150as logical a state as possible. Any in-flight uncommitted database
151transactions will be aborted. Operations occurring on a working copy may
152leave the working copy in an inconsistent state, as we do not have a way to
153atomically update the working copy.
154
155
156Patch submission guidelines
157---------------------------
158
159Mail patches to 'monotone-devel@nongnu.org' with a subject beginning with
160'[PATCH]' and followed by a brief description of the patch. The body of the
161message should contain a description of the patch with reasoning for why the
162changes are required, followed by a prepared ChangeLog entry. Patches may
163be included inline in a message, or attached as a text/plain, text/x-diff,
164or text/x-patch attachment. Make sure your mailer does not mangle the
165patch (e.g. by wrapping lines in the patch) before sending your patch to the
166list.
167
168All changes to the monotone source require an accompanying ChangeLog entry.
169Any changes that affect the user interface (e.g. adding command-line
170options, changing the output format) or affect the documented behaviour of
171monotone must include appropriate appropriate changes to the documentation.
172
173The monotone development team review and comment on all patches on a
174best-efforts basis. Patches are never ignored, but a patch may not be
175discussed or applied immediately according to the amount of spare time the
176developers have. Don't be discouraged if you don't receive an immediate
177response, and if you feel that your patch has slipped through the cracks,
178post a follow up reminder message with a pointer to the original message in
179the mailing list archives.
180
181
182Third-party code
183----------------
184
185monotone contains parts of a number of third-party libraries, including but
186not limited to: Lua, Popt, Crypto++, SQLite, Netxx, and libidn. See AUTHORS
187for complete details on the included third-party code and the copyrights and
188licenses of each portion.
189
190From time to time, bug fixes to this third-party code are required. These
191fixes should be made in the monotone versions of the code first to solve the
192immediate problem. In all cases that make sense (i.e. for general bug
193fixes), the change should also be sent to the upstream developers for
194inclusion in the next release.
195
196In a small number of cases, a change made to our local version of the
197third-party code may not make sense to send upstream. In this case, make a
198note of this in the file you're changing and in the ChangeLog so that this
199permanent deviation is documented.

Archive Download this file

Branches

Tags

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