365
Processing Command Lines
366
------------------------
368
bzrlib has a standard framework for parsing command lines and calling
369
processing routines associated with various commands. See builtins.py
370
for numerous examples.
373
Standard Parameter Types
374
------------------------
376
There are some common requirements in the library: some parameters need to be
377
unicode safe, some need byte strings, and so on. At the moment we have
378
only codified one specific pattern: Parameters that need to be unicode
379
should be checked via ``bzrlib.osutils.safe_unicode``. This will coerce the
380
input into unicode in a consistent fashion, allowing trivial strings to be
381
used for programmer convenience, but not performing unpredictably in the
382
presence of different locales.
388
(The strategy described here is what we want to get to, but it's not
389
consistently followed in the code at the moment.)
391
bzrlib is intended to be a generically reusable library. It shouldn't
392
write messages to stdout or stderr, because some programs that use it
393
might want to display that information through a GUI or some other
396
We can distinguish two types of output from the library:
398
1. Structured data representing the progress or result of an
399
operation. For example, for a commit command this will be a list
400
of the modified files and the finally committed revision number
403
These should be exposed either through the return code or by calls
404
to a callback parameter.
406
A special case of this is progress indicators for long-lived
407
operations, where the caller should pass a ProgressBar object.
409
2. Unstructured log/debug messages, mostly for the benefit of the
410
developers or users trying to debug problems. This should always
411
be sent through ``bzrlib.trace`` and Python ``logging``, so that
412
it can be redirected by the client.
414
The distinction between the two is a bit subjective, but in general if
415
there is any chance that a library would want to see something as
416
structured data, we should make it so.
418
The policy about how output is presented in the text-mode client
419
should be only in the command-line tool.
422
Progress and Activity Indications
423
---------------------------------
425
bzrlib has a way for code to display to the user that stuff is happening
426
during a long operation. There are two particular types: *activity* which
427
means that IO is happening on a Transport, and *progress* which means that
428
higher-level application work is occurring. Both are drawn together by
431
Transport objects are responsible for calling `report_transport_activity`
434
Progress uses a model/view pattern: application code acts on a
435
`ProgressTask` object, which notifies the UI when it needs to be
436
displayed. Progress tasks form a stack. To create a new progress task on
437
top of the stack, call `bzrlib.ui.ui_factory.nested_progress_bar()`, then
438
call `update()` on the returned ProgressTask. It can be updated with just
439
a text description, with a numeric count, or with a numeric count and
440
expected total count. If an expected total count is provided the view
441
can show the progress moving along towards the expected total.
443
The user should call `finish` on the `ProgressTask` when the logical
444
operation has finished, so it can be removed from the stack.
446
Progress tasks have a complex relationship with generators: it's a very
447
good place to use them, but because python2.4 does not allow ``finally``
448
blocks in generators it's hard to clean them up properly. In this case
449
it's probably better to have the code calling the generator allocate a
450
progress task for its use and then call `finalize` when it's done, which
451
will close it if it was not already closed. The generator should also
452
finish the progress task when it exits, because it may otherwise be a long
453
time until the finally block runs.
459
When filenames or similar variables are presented inline within a message,
460
they should be enclosed in double quotes (ascii 0x22, not chiral unicode
463
bzr: ERROR: No such file "asdf"
465
When we print just a list of filenames there should not be any quoting:
468
.. _bug 544297: https://bugs.launchpad.net/bugs/544297
470
https://wiki.ubuntu.com/UnitsPolicy provides a good explanation about
471
which unit should be used when. Roughly speaking, IEC standard applies
472
for base-2 units and SI standard applies for base-10 units:
474
* for network bandwidth and disk sizes, use base-10 (Mbits/s, kB/s, GB)
476
* for RAM sizes, use base-2 (GiB, TiB)
483
Bazaar has online help for various topics through ``bzr help COMMAND`` or
484
equivalently ``bzr command -h``. We also have help on command options,
485
and on other help topics. (See ``help_topics.py``.)
487
As for python docstrings, the first paragraph should be a single-sentence
488
synopsis of the command. These are user-visible and should be prefixed with
489
``__doc__ =`` so help works under ``python -OO`` with docstrings stripped.
491
The help for options should be one or more proper sentences, starting with
492
a capital letter and finishing with a full stop (period).
494
All help messages and documentation should have two spaces between
498
Handling Errors and Exceptions
499
==============================
501
Commands should return non-zero when they encounter circumstances that
502
the user should really pay attention to - which includes trivial shell
505
Recommended values are:
508
1. Conflicts in merge-like operations, or changes are present in
509
diff-like operations.
510
2. Unrepresentable diff changes (i.e. binary files that we cannot show
512
3. An error or exception has occurred.
513
4. An internal error occurred (one that shows a traceback.)
515
Errors are handled through Python exceptions. Exceptions should be defined
516
inside bzrlib.errors, so that we can see the whole tree at a glance.
518
We broadly classify errors as either being either internal or not,
519
depending on whether ``internal_error`` is set or not. If we think it's our
520
fault, we show a backtrace, an invitation to report the bug, and possibly
521
other details. This is the default for errors that aren't specifically
522
recognized as being caused by a user error. Otherwise we show a briefer
523
message, unless -Derror was given.
525
Many errors originate as "environmental errors" which are raised by Python
526
or builtin libraries -- for example IOError. These are treated as being
527
our fault, unless they're caught in a particular tight scope where we know
528
that they indicate a user errors. For example if the repository format
529
is not found, the user probably gave the wrong path or URL. But if one of
530
the files inside the repository is not found, then it's our fault --
531
either there's a bug in bzr, or something complicated has gone wrong in
532
the environment that means one internal file was deleted.
534
Many errors are defined in ``bzrlib/errors.py`` but it's OK for new errors
535
to be added near the place where they are used.
537
Exceptions are formatted for the user by conversion to a string
538
(eventually calling their ``__str__`` method.) As a convenience the
539
``._fmt`` member can be used as a template which will be mapped to the
540
error's instance dict.
542
New exception classes should be defined when callers might want to catch
543
that exception specifically, or when it needs a substantially different
546
#. If it is something that a caller can recover from, a custom exception
549
#. If it is a data consistency issue, using a builtin like
550
``ValueError``/``TypeError`` is reasonable.
552
#. If it is a programmer error (using an api incorrectly)
553
``AssertionError`` is reasonable.
555
#. Otherwise, use ``BzrError`` or ``InternalBzrError``.
557
Exception strings should start with a capital letter and should not have a
558
final fullstop. If long, they may contain newlines to break the text.
565
When you change bzrlib, please update the relevant documentation for the
566
change you made: Changes to commands should update their help, and
567
possibly end user tutorials; changes to the core library should be
568
reflected in API documentation.
573
If you make a user-visible change, please add a note to the NEWS file.
574
The description should be written to make sense to someone who's just
575
a user of bzr, not a developer: new functions or classes shouldn't be
576
mentioned, but new commands, changes in behaviour or fixed nontrivial
577
bugs should be listed. See the existing entries for an idea of what
580
Within each release, entries in the news file should have the most
581
user-visible changes first. So the order should be approximately:
583
* changes to existing behaviour - the highest priority because the
584
user's existing knowledge is incorrect
585
* new features - should be brought to their attention
586
* bug fixes - may be of interest if the bug was affecting them, and
587
should include the bug number if any
588
* major documentation changes, including fixed documentation bugs
589
* changes to internal interfaces
591
People who made significant contributions to each change are listed in
592
parenthesis. This can include reporting bugs (particularly with good
593
details or reproduction recipes), submitting patches, etc.
595
To help with merging, NEWS entries should be sorted lexicographically
601
The docstring of a command is used by ``bzr help`` to generate help output
602
for the command. The list 'takes_options' attribute on a command is used by
603
``bzr help`` to document the options for the command - the command
604
docstring does not need to document them. Finally, the '_see_also'
605
attribute on a command can be used to reference other related help topics.
610
Functions, methods, classes and modules should have docstrings
611
describing how they are used.
613
The first line of the docstring should be a self-contained sentence.
615
For the special case of Command classes, this acts as the user-visible
616
documentation shown by the help command.
618
The docstrings should be formatted as reStructuredText_ (like this
619
document), suitable for processing using the epydoc_ tool into HTML
622
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
623
.. _epydoc: http://epydoc.sourceforge.net/
362
626
General Guidelines
363
627
==================
added
removed
doc/developers/HACKING.txt
