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
==================
621
885
how to set it up and configure it.
894
Of the many workflows supported by Bazaar, the one adopted for Bazaar
895
development itself is known as "Decentralized with automatic gatekeeper".
896
To repeat the explanation of this given on
897
http://wiki.bazaar.canonical.com/Workflows:
900
In this workflow, each developer has their own branch or
901
branches, plus read-only access to the mainline. A software gatekeeper
902
(e.g. PQM) has commit rights to the main branch. When a developer wants
903
their work merged, they request the gatekeeper to merge it. The gatekeeper
904
does a merge, a compile, and runs the test suite. If the code passes, it
905
is merged into the mainline.
907
In a nutshell, here's the overall submission process:
909
#. get your work ready (including review except for trivial changes)
910
#. push to a public location
911
#. ask PQM to merge from that location
914
At present, PQM always takes the changes to merge from a branch
915
at a URL that can be read by it. For Bazaar, that means a public,
918
As a result, the following things are needed to use PQM for submissions:
920
#. A publicly available web server
921
#. Your OpenPGP key registered with PQM (contact RobertCollins for this)
922
#. The PQM plugin installed and configured (not strictly required but
926
Selecting a Public Branch Location
927
----------------------------------
929
If you don't have your own web server running, branches can always be
930
pushed to Launchpad. Here's the process for doing that:
932
Depending on your location throughout the world and the size of your
933
repository though, it is often quicker to use an alternative public
934
location to Launchpad, particularly if you can set up your own repo and
935
push into that. By using an existing repo, push only needs to send the
936
changes, instead of the complete repository every time. Note that it is
937
easy to register branches in other locations with Launchpad so no benefits
938
are lost by going this way.
941
For Canonical staff, http://people.ubuntu.com/~<user>/ is one
942
suggestion for public http branches. Contact your manager for information
943
on accessing this system if required.
945
It should also be noted that best practice in this area is subject to
946
change as things evolve. For example, once the Bazaar smart server on
947
Launchpad supports server-side branching, the performance situation will
948
be very different to what it is now (Jun 2007).
951
Configuring the PQM Plug-In
952
---------------------------
954
While not strictly required, the PQM plugin automates a few things and
955
reduces the chance of error. Before looking at the plugin, it helps to
956
understand a little more how PQM operates. Basically, PQM requires an
957
email indicating what you want it to do. The email typically looks like
960
star-merge source-branch target-branch
964
star-merge http://bzr.arbash-meinel.com/branches/bzr/jam-integration http://bazaar-vcs.org/bzr/bzr.dev
966
Note that the command needs to be on one line. The subject of the email
967
will be used for the commit message. The email also needs to be ``gpg``
968
signed with a key that PQM accepts.
970
The advantages of using the PQM plugin are:
972
#. You can use the config policies to make it easy to set up public
973
branches, so you don't have to ever type the full paths you want to merge
976
#. It checks to make sure the public branch last revision matches the
977
local last revision so you are submitting what you think you are.
979
#. It uses the same public_branch and smtp sending settings as bzr-email,
980
so if you have one set up, you have the other mostly set up.
982
#. Thunderbird refuses to not wrap lines, and request lines are usually
983
pretty long (you have 2 long URLs in there).
985
Here are sample configuration settings for the PQM plugin. Here are the
986
lines in bazaar.conf::
989
email = Joe Smith <joe.smith@internode.on.net>
990
smtp_server=mail.internode.on.net:25
992
And here are the lines in ``locations.conf`` (or ``branch.conf`` for
993
dirstate-tags branches)::
995
[/home/joe/bzr/my-integration]
996
push_location = sftp://joe-smith@bazaar.launchpad.net/%7Ejoe-smith/bzr/my-integration/
997
push_location:policy = norecurse
998
public_branch = http://bazaar.launchpad.net/~joe-smith/bzr/my-integration/
999
public_branch:policy = appendpath
1000
pqm_email = Bazaar PQM <pqm@bazaar-vcs.org>
1001
pqm_branch = http://bazaar-vcs.org/bzr/bzr.dev
1003
Note that the push settings will be added by the first ``push`` on
1004
a branch. Indeed the preferred way to generate the lines above is to use
1005
``push`` with an argument, then copy-and-paste the other lines into
1012
Here is one possible recipe once the above environment is set up:
1014
#. pull bzr.dev => my-integration
1015
#. merge patch => my-integration
1016
#. fix up any final merge conflicts (NEWS being the big killer here).
1022
The ``push`` step is not required if ``my-integration`` is a checkout of
1025
Because of defaults, you can type a single message into commit and
1026
pqm-commit will reuse that.
1029
Tracking Change Acceptance
1030
--------------------------
1032
The web interface to PQM is https://pqm.bazaar-vcs.org/. After submitting
1033
a change, you can visit this URL to confirm it was received and placed in
1036
When PQM completes processing a change, an email is sent to you with the
625
1040
Planning Releases
626
1041
=================
added
removed
doc/developers/HACKING.txt
