1
Bazaar Contribution in Five Minutes
2
===================================
4
Contributing to Bazaar requires attention to quality. To ensure
5
high-quality commits, the "Bazaar process" involves you in our
6
code review and improvement activities.
8
In brief, a contribution should include:
10
1. A brief rationale, including expected audience and use cases,
11
for inclusion in Bazaar.
13
2. A branch registered as a branch on Launchpad, and submitted as
16
3. The branch should include:
18
a. implementation of the feature,
20
b. user documentation (if the feature is visible in the user
21
interface) and/or developer documentation (if new or
22
changed APIs are provided), and
24
c. tests to ensure the specification is correctly
27
For more information, see the `Bazaar Developer Guide <HACKING.html>`_.
29
If you are not an experienced Bazaar contributor, why not ask for
30
mentoring? When you submit your merge proposal on Launchpad, simply say
31
"I'd like to be mentored, please" in your submission. Or ask for help
32
with your contribution on the IRC channel, mailing list, or on Launchpad
33
(https://answers.launchpad.net/bzr).
36
Current Bazaar Mentors
37
----------------------
39
See the roster at http://bazaar-vcs.org/PatchPilot, although other
40
developers may help too!
46
1. Why is this "Bazaar process" in HACKING.txt so complicated?
48
Answer: If we knew *that*, we'd simplify it! We are working
49
on streamlining many aspects, but quality comes first.
51
1. What sort of things can a mentor help with?
53
Anything that's getting in your way, time permitting. This includes
54
guiding you through the ``bzrlib`` API, explaining how to use our test
55
infrastructure, discussing possible designs for your bug fix or
7
If you want to fix or improve something in Bazaar, we want to help you.
8
You can ask at any time for help, on the list, on irc, or through a merge
11
In particular, the rostered
12
`Patch Pilot <http://wiki.bazaar.canonical.com/PatchPilot>`_
13
is an experienced developer who will help you get your changes in, through
14
code review, advice, debugging, writing tests, or whatever it takes.
16
* `Bazaar mailing list <http://lists.ubuntu.com/mailman/listinfo/bazaar>`_
18
* IRC in channel ``#bzr`` on ``irc.ubuntu.com``
24
Before starting on a change it's a good idea to either file a bug, find a
25
relevant existing bug, or send a proposal to the list. If there is a bug
26
you should set it to "In Progress" and if you wish assign it to yourself.
28
You might like to start with a bug tagged `easy
29
<https://bugs.launchpad.net/bzr/+bugs?field.tag=easy>`_.
31
If you are wondering if your understanding of the bug is correct, or if the
32
approach you have in mind is likely to work, feel to ask about it on the bug,
33
in ``#bzr`` or on the mailing list.
38
First, get a local copy of Bazaar::
43
$ bzr branch lp:bzr bzr.dev
45
Now make your own branch; we recommend you include the bug number and also
48
$ bzr branch bzr.dev 123456-status-speed
50
and go ahead and commit in there. Normally you should fix only one bug or
51
closely-related cluster of bugs per branch, to make reviews and merges
54
For bugs that exist in older supported branches of bzr like 2.0 or 2.1,
55
you might want to fix the bug there so it can go into a bugfix release,
58
$ bzr branch lp:bzr/2.1 bzr.2.1
59
$ bzr branch bzr.2.1 123458-2.1-status
61
You probably want this configuration in ``~/.bazaar/locations.conf``::
64
push_location = lp:~LAUNCHPAD_USER/bzr/
65
push_location:policy = appendpath
66
public_branch = http://bazaar.launchpad.net/~LAUNCHPAD_USER/bzr/
67
public_branch:policy = appendpath
69
with your local and Launchpad usernames inserted.
73
Publishing your changes
74
-----------------------
76
After you've locally committed your changes, the configuration above
77
should be enough that you can push them to Launchpad with a simple ::
85
We value test coverage and generally all changes should have or update a
86
test. There is a powerful test framework but it can be hard to find the
87
right place to put your test. Don't hesitate to ask, or to propose a
88
merge that does not yet have tests.
90
Normally for command-line code you should look in
91
``bzrlib.tests.blackbox`` and for library code in ``bzrlib.tests``. For
92
functions on an interface for which there are multiple implementations,
93
like `Transport`, look in ``bzrlib.tests.per_transport``.
95
It's a good idea to search the tests for something related to the thing
96
you're changing and you may find a test you can modify or adapt.
102
Normally the tests will skip if some library dependencies are not present.
103
On Ubuntu, you can install them with this command (you must have source
104
repositories enabled in Software Sources)::
106
$ sudo apt-get build-dep bzr
108
To build the binary extensions::
112
For more information: `Testing Guide <testing.html>`_.
119
Then propose a merge into bzr; for bzr 2.2 and later you can use the ``bzr
120
lp-propose-merge`` command. In the comment for your merge proposal please
121
explain what you're trying to do and why. For `example
122
<https://code.launchpad.net/~ian-clatworthy/bzr/whats-new-in-2.1/+merge/19677>`_:
124
As discussed on the mailing list, this patch adds a What's New document
125
summarising the changes since 2.0.
127
If you make additional changes to your branch you don't need to resubmit;
128
they'll automatically show up in the merge proposal.
130
* `Launchpad Code Review Help <http://help.launchpad.net/Code/Review>`_.
59
134
vim: ft=rst tw=74 ai
added
removed
doc/developers/contribution-quickstart.txt
