~bzr-pqm/bzr/bzr.dev

Contributing to Bazaar

======================

Talk to us

----------

If you want to fix or improve something in Bazaar, we want to help you.

You can ask at any time for help, on the list, on irc, or through a merge

proposal on Launchpad.

In particular, the rostered

`Patch Pilot <http://wiki.bazaar.canonical.com/PatchPilot>`_ 

is an experienced developer who will help you get your changes in, through

code review, advice, debugging, writing tests, or whatever it takes.

* `Bazaar mailing list <http://lists.ubuntu.com/mailman/listinfo/bazaar>`_

* IRC in channel ``#bzr`` on ``irc.ubuntu.com``

Starting

--------

Before starting on a change it's a good idea to either file a bug, find a

relevant existing bug, or send a proposal to the list.  If there is a bug

you should set it to "In Progress" and if you wish assign it to yourself.

You might like to start with a bug tagged `easy

<https://bugs.launchpad.net/bzr/+bugs?field.tag=easy>`_.

If you are wondering if your understanding of the bug is correct, or if the 

approach you have in mind is likely to work, feel to ask about it on the bug,

in ``#bzr`` or on the mailing list.

Making a branch

---------------

First, get a local copy of Bazaar::

   $ cd $HOME

   $ bzr init-repo bzr

   $ cd bzr

   $ bzr branch lp:bzr bzr.dev

Now make your own branch; we recommend you include the bug number and also

a brief description::

   $ bzr branch bzr.dev 123456-status-speed

and go ahead and commit in there.  Normally you should fix only one bug or

closely-related cluster of bugs per branch, to make reviews and merges

flow more smoothly.

For bugs that exist in older supported branches of bzr like 2.0 or 2.1,

you might want to fix the bug there so it can go into a bugfix release,

ie ::

   $ bzr branch lp:bzr/2.1 bzr.2.1

   $ bzr branch bzr.2.1 123458-2.1-status

You probably want this configuration in ``~/.bazaar/locations.conf``::

    [/home/USER/bzr]

    push_location = lp:~LAUNCHPAD_USER/bzr/

    push_location:policy = appendpath

    public_branch = http://bazaar.launchpad.net/~LAUNCHPAD_USER/bzr/

    public_branch:policy = appendpath

with your local and Launchpad usernames inserted.

Publishing your changes

-----------------------

After you've locally committed your changes, the configuration above

should be enough that you can push them to Launchpad with a simple ::

    $ bzr push

Writing tests

-------------

We value test coverage and generally all changes should have or update a

test.  There is a powerful test framework but it can be hard to find the

right place to put your test.  Don't hesitate to ask, or to propose a

merge that does not yet have tests.

Normally for command-line code you should look in

``bzrlib.tests.blackbox`` and for library code in ``bzrlib.tests``.  For

functions on an interface for which there are multiple implementations,

like `Transport`, look in ``bzrlib.tests.per_transport``.

It's a good idea to search the tests for something related to the thing

you're changing and you may find a test you can modify or adapt.

To run the tests::

    $ ./bzr selftest

Normally the tests will skip if some library dependencies are not present.

On Ubuntu, you can install them with this command (you must have source

repositories enabled in Software Sources)::

    $ sudo apt-get build-dep bzr

To build the binary extensions::

    $ make

For more information: `Testing Guide <testing.html>`_.

Proposing a merge

-----------------

Then propose a merge into bzr; for bzr 2.2 and later you can use the ``bzr

lp-propose-merge`` command.  In the comment for your merge proposal please

explain what you're trying to do and why.  For `example

<https://code.launchpad.net/~ian-clatworthy/bzr/whats-new-in-2.1/+merge/19677>`_:

  As discussed on the mailing list, this patch adds a What's New document

  summarising the changes since 2.0.

If you make additional changes to your branch you don't need to resubmit;

they'll automatically show up in the merge proposal.

* `Launchpad Code Review Help <http://help.launchpad.net/Code/Review>`_.

..

   vim: ft=rst tw=74 ai