diff options
Diffstat (limited to 'doc/developers/contribution-quickstart.txt')
| -rw-r--r-- | doc/developers/contribution-quickstart.txt | 134 |
1 files changed, 134 insertions, 0 deletions
diff --git a/doc/developers/contribution-quickstart.txt b/doc/developers/contribution-quickstart.txt new file mode 100644 index 0000000..6298935 --- /dev/null +++ b/doc/developers/contribution-quickstart.txt @@ -0,0 +1,134 @@ +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 |