117
117
`your_lp_username`. You can push your branch to Launchpad directly from
120
$ bzr push lp:~your_lp_username/bzr/meaningful_name_here
120
$ bzr push lp:~<your_lp_username>/bzr/meaningful_name_here
122
122
After you have pushed your branch, you will need to propose it for merging to
123
123
the Bazaar trunk. Go to
124
<https://launchpad.net/your_lp_username/bzr/meaningful_name_here> and choose
125
"Propose for merging into another branch". Select "~bzr/bzr/trunk" to hand
124
<https://launchpad.net/~<your_lp_username>/bzr/meaningful_name_here> and choose
125
"Propose for merging into another branch". Select "lp:bzr" to hand
126
126
your changes off to the Bazaar developers for review and merging.
128
128
Alternatively, after pushing you can use the ``lp-propose`` command to
285
281
Documentation specifically targeted at Bazaar and plugin developers.
286
282
(Including this document.)
284
doc/en/release-notes/
286
Detailed changes in each Bazaar release (there is one file by series:
287
bzr-2.3.txt, bzr-2.4.txt, etc) that can affect users or plugin
292
High-level summaries of changes in each Bazaar release (there is one
293
file by series: whats-new-in-2.3.txt, whats-new-in-2.4.txt, etc).
290
296
Automatically-generated API reference information is available at
291
<http://starship.python.net/crew/mwh/bzrlibapi/>.
297
<http://people.canonical.com/~mwh/bzrlibapi/>.
293
299
See also the `Bazaar Architectural Overview
294
300
<http://doc.bazaar.canonical.com/developers/overview.html>`_.
365
When you change bzrlib, please update the relevant documentation for the
366
change you made: Changes to commands should update their help, and
367
possibly end user tutorials; changes to the core library should be
368
reflected in API documentation.
373
If you make a user-visible change, please add a note to the NEWS file.
374
The description should be written to make sense to someone who's just
375
a user of bzr, not a developer: new functions or classes shouldn't be
376
mentioned, but new commands, changes in behaviour or fixed nontrivial
377
bugs should be listed. See the existing entries for an idea of what
380
Within each release, entries in the news file should have the most
381
user-visible changes first. So the order should be approximately:
383
* changes to existing behaviour - the highest priority because the
384
user's existing knowledge is incorrect
385
* new features - should be brought to their attention
386
* bug fixes - may be of interest if the bug was affecting them, and
387
should include the bug number if any
388
* major documentation changes, including fixed documentation bugs
389
* changes to internal interfaces
391
People who made significant contributions to each change are listed in
392
parenthesis. This can include reporting bugs (particularly with good
393
details or reproduction recipes), submitting patches, etc.
395
To help with merging, NEWS entries should be sorted lexicographically
401
The docstring of a command is used by ``bzr help`` to generate help output
402
for the command. The list 'takes_options' attribute on a command is used by
403
``bzr help`` to document the options for the command - the command
404
docstring does not need to document them. Finally, the '_see_also'
405
attribute on a command can be used to reference other related help topics.
410
Functions, methods, classes and modules should have docstrings
411
describing how they are used.
413
The first line of the docstring should be a self-contained sentence.
415
For the special case of Command classes, this acts as the user-visible
416
documentation shown by the help command.
418
The docstrings should be formatted as reStructuredText_ (like this
419
document), suitable for processing using the epydoc_ tool into HTML
422
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
423
.. _epydoc: http://epydoc.sourceforge.net/
426
368
General Guidelines
427
369
==================
494
436
be disabled if necessary by setting the environment variable
495
437
``BZR_SIGQUIT_PDB=0``.
439
All tests inheriting from bzrlib.tests.TestCase can use ``self.debug()``
440
instead of the longer ``import pdb; pdb.set_trace()``. The former also works
441
when ``stdin/stdout`` are redirected (by using the original ``stdin/stdout``
442
file handles at the start of the ``bzr`` script) while the later doesn't.
443
``bzrlib.debug.set_trace()`` also uses the original ``stdin/stdout`` file
575
523
Because Transports work in URLs (as defined earlier), printing the raw URL
576
524
to the user is usually less than optimal. Characters outside the standard
577
525
set are printed as escapes, rather than the real character, and local
578
paths would be printed as ``file://`` urls. The function
526
paths would be printed as ``file://`` URLs. The function
579
527
``unescape_for_display`` attempts to unescape a URL, such that anything
580
528
that cannot be printed in the current encoding stays an escaped URL, but
581
529
valid characters are generated where possible.
added
removed
doc/developers/HACKING.txt
