40
40
Recommended values are
42
1. Conflicts in merge-like operations, or changes are present in
42
1- Conflicts in merge-like operations, or changes are present in
43
43
diff-like operations.
44
2. Unrepresentable diff changes (i.e. binary files that we cannot show
44
2- Unrepresentable diff changes (i.e. binary files that we cannot show
46
3. An error or exception has occurred.
46
3- An error or exception has occurred.
48
48
Evolving interfaces
49
49
-------------------
194
194
may not catch every case but it's still useful sometimes.
200
In some places we have variables which point to callables that construct
201
new instances. That is to say, they can be used a lot like class objects,
202
but they shouldn't be *named* like classes:
204
> I think that things named FooBar should create instances of FooBar when
205
> called. Its plain confusing for them to do otherwise. When we have
206
> something that is going to be used as a class - that is, checked for via
207
> isinstance or other such idioms, them I would call it foo_class, so that
208
> it is clear that a callable is not sufficient. If it is only used as a
209
> factory, then yes, foo_factory is what I would use.
260
245
option, then you should be writing a UI test. If you are both adding UI
261
246
functionality and library functionality, you will want to write tests for
262
247
both the UI and the core behaviours. We call UI tests 'blackbox' tests
263
and they are found in ``bzrlib/tests/blackbox/*.py``.
248
and they are found in bzrlib/tests/blackbox/*.py.
265
250
When writing blackbox tests please honour the following conventions:
282
267
command changes it name or signature. Ideally only the tests for a
283
268
given command are affected when a given command is changed.
288
We make selective use of doctests__. In general they should provide
289
*examples* within the API documentation which can incidentally be tested. We
290
don't try to test every important case using doctests -- regular Python
291
tests are generally a better solution.
293
Most of these are in ``bzrlib/doc/api``. More additions are welcome.
295
__ http://docs.python.org/lib/module-doctest.html
300
272
Currently, bzr selftest is used to invoke tests.
366
333
for those characters. (Although this is not totally reliable we might still
367
334
accept these and assume they should be put into UTF-8.)
369
A similar edge case is that the url ``http://foo/sweet%2Fsour`` contains
336
A similar edge case is that the url ``http://foo/sweet%2Fsour" contains
370
337
one directory component whose name is "sweet/sour". The escaped slash is
371
338
not a directory separator. If we try to convert URLs to regular Unicode
372
339
paths this information will be lost.
377
344
the form of URL components.
380
Unicode and Encoding Support
381
============================
383
This section discusses various techniques that Bazaar uses to handle
384
characters that are outside the ASCII set.
389
When a ``Command`` object is created, it is given a member variable
390
accessible by ``self.outf``. This is a file-like object, which is bound to
391
``sys.stdout``, and should be used to write information to the screen,
392
rather than directly writing to ``sys.stdout`` or calling ``print``.
393
This file has the ability to translate Unicode objects into the correct
394
representation, based on the console encoding. Also, the class attribute
395
``encoding_type`` will effect how unprintable characters will be
396
handled. This parameter can take one of 3 values:
399
Unprintable characters will be represented with a suitable replacement
400
marker (typically '?'), and no exception will be raised. This is for
401
any command which generates text for the user to review, rather than
402
for automated processing.
403
For example: ``bzr log`` should not fail if one of the entries has text
404
that cannot be displayed.
407
Attempting to print and unprintable character will cause a UnicodeError.
408
This is for commands that are intended more as scripting support, rather
409
than plain user review.
410
For exampl: ``bzr ls`` is designed to be used with shell scripting. One
411
use would be ``bzr ls --null --unknows | xargs -0 rm``. If ``bzr``
412
printed a filename with a '?', the wrong file could be deleted. (At the
413
very least, the correct file would not be deleted). An error is used to
414
indicate that the requested action could not be performed.
417
Do not attempt to automatically convert Unicode strings. This is used
418
for commands that must handle conversion themselves.
419
For example: ``bzr diff`` needs to translate Unicode paths, but should
420
not change the exact text of the contents of the files.
423
``bzrlib.urlutils.unescape_for_display``
424
----------------------------------------
426
Because Transports work in URLs (as defined earlier), printing the raw URL
427
to the user is usually less than optimal. Characters outside the standard
428
set are printed as escapes, rather than the real character, and local
429
paths would be printed as ``file://`` urls. The function
430
``unescape_for_display`` attempts to unescape a URL, such that anything
431
that cannot be printed in the current encoding stays an escaped URL, but
432
valid characters are generated where possible.
435
347
Merge/review process
436
348
====================
added
removed
HACKING
