# # # patch "HACKING" # from [f28fd6981f93583e624a512cc0369af008e54e31] # to [f38b25617f0d9ff75c9bc29943fc09150f02b7e0] # # patch "file_io.hh" # from [b25393c180869ad70aa6344b0e0a08d3ab82d474] # to [bd4beae86ace6c7e07f54e6466e22571793b75f0] # # patch "paths.hh" # from [57c50de2ab3cb44925e731b2ee4c60f4b6d7174b] # to [e92b013f510afba1da74ab8f47a8f2fa799b3b5c] # # patch "platform.hh" # from [28e74359c884cd94c994d4b46259879a358acf6a] # to [648608271dd6559ba89bc0bb816a3de306c3355f] # # patch "work.hh" # from [b2a0f077a4ad9482283a6dab697778ff0815dc1e] # to [e9fa5e199e99600095c5a56799614b7f91866c06] # ============================================================ --- HACKING f28fd6981f93583e624a512cc0369af008e54e31 +++ HACKING f38b25617f0d9ff75c9bc29943fc09150f02b7e0 @@ -172,7 +172,7 @@ Test suites, and writing test cases functions. Test suites, and writing test cases ----------------------------------- +----------------------------------- monotone includes a number of unit and integration tests. These can be run easily by initiating a 'make check'. The test suite (or, at least, any @@ -186,9 +186,9 @@ test. This includes most changes, but u All changes to monotone that alter monotone's behaviour should include a new test. This includes most changes, but use your judgment about adding tests -for very small changes.. The tests are located in the source tree in the +for very small changes. The tests are located in the source tree in the tests/ directory, documentation on writing tests is available in -tests/README. +notes/README.testing. When fixing a bug, check for an existing test case for that bug and carefully observe the test case's behaviour before and after your fix. If no @@ -219,37 +219,42 @@ bare capital letters scattered around. bare capital letters scattered around. Here's a quick guide. Formatting macros: - F("foo %s"): create a formatting object, for display to the user. + F("foo %s"): + create a formatting object, for display to the user. Translators will translate this string, and F() runs gettext() on its argument. NB: this string should usually _not_ end in a newline. - FP("%d foo", "%d foos", n) % n: create a formatting object, with - plural handling. Same comments apply as to F(). - FL("foo %s"): create a raw ("literal") formatting object, mostly for + FP("%d foo", "%d foos", n) % n: + create a formatting object, with plural handling. + Same comments apply as to F(). + FL("foo %s"): + create a raw ("literal") formatting object, mostly for use in logging. This string will _not_ be translated, and gettext() is _not_ called. This is almost always an argument - to the L() macro: + to the L() macro. Informational macros: - L(FL("foo")): log "foo". Log messages are generally not seen by the + L(FL("foo")): + log "foo". Log messages are generally not seen by the user, and are used to debug problems with monotone. - P(F("foo")): print "foo". For generic informative messages to the - user. - W(F("foo")): warn "foo". For warnings to the user. + P(F("foo")): + print "foo". For generic informative messages to the user. + W(F("foo")): + warn "foo". For warnings to the user. Assertion macros (see also the next section). These all cause monotone to exit if their condition is false: - I(x != y): "invariant" -- if the condition is not true, then there + I(x != y): + "invariant" -- if the condition is not true, then there is a bug in monotone. - N(x != y, F("make x and y equal")): "naughty" -- the user - requested something that doesn't make sense, they should fix - that. - E(x != y, F("x and y are not equal")): "error" -- not a bug in - monotone, not necessarily the users fault... dunno boss, it - just isn't working! + E(x != y, F("x and y are not equal"), origin::user): + "error" -- a general error. The third argument is used to + give the system a hint what kind of error that is. One of the + origin types in origin_type.hh is possible. Tracing macros: - MM(x): Mark the given variable as one of the things we are looking + MM(x): + Mark the given variable as one of the things we are looking at right now. On its own, this statement has no visible effect; but if monotone crashes (that is, an I() check fails) while MM(x) is in scope, then the value of x will be printed @@ -343,27 +348,21 @@ monotone has a number of assertion macro ---------------------------- monotone has a number of assertion macros available for different -situations. These assertion macros are divided into three categories: -invariants, user naughtiness, and general errors. +situations. These assertion macros are divided into two categories: +invariants and general errors. Invariants assert that monotone's internal state is in the expected state. An invariant failure indicates that there is a bug in monotone. e.g. I(r_working.edges.size() == 1); -User naughtiness handles error conditions where the user has asked monotone -to do something it is unable to. e.g. - - N(!completions.empty(), - F("no match for selection '%s'") % str); - Error conditions handle most other error cases, where monotone is unable to complete an operation due to an error, but that error is not caused by a bug -in monotone or explicit user error. e.g. +in monotone, e.g. E(converted != NULL, F("failed to convert string from %s to %s: '%s'") - % src_charset % dst_charset % src); + % src_charset % dst_charset % src, origin::system); Each of these assertion macros are fatal and will cause an exception to be thrown that will ultimately cause the monotone process to exit. Exceptions ============================================================ --- file_io.hh b25393c180869ad70aa6344b0e0a08d3ab82d474 +++ file_io.hh bd4beae86ace6c7e07f54e6466e22571793b75f0 @@ -27,7 +27,7 @@ void assert_path_is_directory(any_path c void assert_path_is_file(any_path const & path); void assert_path_is_directory(any_path const & path); -// use N() +// use E() void require_path_is_nonexistent(any_path const & path, i18n_format const & message); void require_path_is_file(any_path const & path, ============================================================ --- paths.hh 57c50de2ab3cb44925e731b2ee4c60f4b6d7174b +++ paths.hh e92b013f510afba1da74ab8f47a8f2fa799b3b5c @@ -50,7 +50,7 @@ // to the project root. // file_path_external: use this for strings that come from the user. // these strings are normalized before being checked, and if there -// is a problem trigger N() invariants rather than I() invariants. +// is a problem trigger E() invariants rather than I() invariants. // if in a workspace, such strings are interpreted as being // _relative to the user's original directory_. if not in a // workspace, strings are treated as relative to the tree root. The ============================================================ --- platform.hh 28e74359c884cd94c994d4b46259879a358acf6a +++ platform.hh 648608271dd6559ba89bc0bb816a3de306c3355f @@ -108,7 +108,7 @@ std::string get_current_working_dir(); // filesystem stuff // FIXME: BUG: this returns a string in the filesystem charset/encoding std::string get_current_working_dir(); -// calls N() if fails +// calls E() if fails void change_current_working_dir(std::string const & to); std::string tilde_expand(std::string const & path); std::string get_default_confdir(); ============================================================ --- work.hh b2a0f077a4ad9482283a6dab697778ff0815dc1e +++ work.hh e9fa5e199e99600095c5a56799614b7f91866c06 @@ -35,7 +35,7 @@ class app_state; // as well as many instance methods. class methods can be used when you're // not sure yet whether or not there is a workspace. instance methods can // only be used if there definitely is a workspace; the workspace object -// constructor will throw an N() if there isn't one. (this can also be +// constructor will throw an E() if there isn't one. (this can also be // triggered by the class method require_workspace, for the sake of a few // places that need to do that but not create the workspace object yet.) //