~bzr-pqm/bzr/bzr.dev

5037.2.8 by Martin Pool
Clearer instructions on building and getting started
1
Contributing to Bazaar
2
======================
4806.1.2 by Andrew Bennetts
Add 5 minute contribution guide contributed by Stephen Turnbull.
3
5037.2.9 by Martin Pool
Point to list and irc (thanks parthm)
4
Talk to us
5
----------
6
5037.2.7 by Martin Pool
Better contribution information, replacing wiki page
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
9
proposal on Launchpad.
10
5037.2.8 by Martin Pool
Clearer instructions on building and getting started
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.
5037.2.7 by Martin Pool
Better contribution information, replacing wiki page
15
5037.2.9 by Martin Pool
Point to list and irc (thanks parthm)
16
* `Bazaar mailing list <http://lists.ubuntu.com/mailman/listinfo/bazaar>`_
17
18
* IRC in channel ``#bzr`` on ``irc.ubuntu.com``
19
20
5037.2.7 by Martin Pool
Better contribution information, replacing wiki page
21
Starting
22
--------
23
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.
27
28
You might like to start with a bug tagged `easy
29
<https://bugs.edge.launchpad.net/bzr/+bugs?field.tag=easy>`_.
30
31
Making a branch
32
---------------
33
34
First, get a local copy of Bazaar::
35
36
   $ cd $HOME
37
   $ bzr init-repo bzr
38
   $ cd bzr
39
   $ bzr branch lp:bzr bzr.dev
40
41
Now make your own branch; we recommend you include the bug number and also
42
a brief description::
43
44
   $ bzr branch bzr.dev 123456-status-speed
45
46
and go ahead and commit in there.  Normally you should fix only one bug or
47
closely-related cluster of bugs per branch, to make reviews and merges
48
flow more smoothly.
49
50
For bugs that exist in older supported branches of bzr like 2.0 or 2.1,
51
you might want to fix the bug there so it can go into a bugfix release,
52
ie ::
53
54
   $ bzr branch lp:bzr/2.1 bzr.2.1
55
   $ bzr branch bzr.2.1 123458-2.1-status
56
57
You probably want this configuration in ``~/.bazaar/locations.conf``::
58
5037.2.11 by Martin Pool
Clarify Launchpad setup example
59
    [/home/USER/bzr]
60
    push_location = lp:~LAUNCHPAD_USER/bzr/
5037.2.7 by Martin Pool
Better contribution information, replacing wiki page
61
    push_location:policy = appendpath
5037.2.11 by Martin Pool
Clarify Launchpad setup example
62
    public_branch = http://bazaar.launchpad.net/~LAUNCHPAD_USER/bzr/
5037.2.7 by Martin Pool
Better contribution information, replacing wiki page
63
    public_branch:policy = appendpath
64
5037.2.11 by Martin Pool
Clarify Launchpad setup example
65
with your local and Launchpad usernames inserted.
5037.2.7 by Martin Pool
Better contribution information, replacing wiki page
66
67
5283.3.1 by Martin Pool
Remove obsolete documentation about using bzr-pqm (thanks bialix)
68
69
Publishing your changes
70
-----------------------
71
72
After you've locally committed your changes, the configuration above
73
should be enough that you can push them to Launchpad with a simple ::
74
75
    $ bzr push
76
77
5037.2.7 by Martin Pool
Better contribution information, replacing wiki page
78
Writing tests
79
-------------
80
81
We value test coverage and generally all changes should have or update a
82
test.  There is a powerful test framework but it can be hard to find the
83
right place to put your test.  Don't hesitate to ask, or to propose a
84
merge that does not yet have tests.
85
86
Normally for command-line code you should look in
87
``bzrlib.tests.blackbox`` and for library code in ``bzrlib.tests``.  For
88
functions on an interface for which there are multiple implementations,
89
like `Transport`, look in ``bzrlib.tests.per_transport``.
90
91
It's a good idea to search the tests for something related to the thing
92
you're changing and you may find a test you can modify or adapt.
93
5037.2.8 by Martin Pool
Clearer instructions on building and getting started
94
To run the tests::
95
96
    $ ./bzr selftest
97
98
Normally the tests will skip if some library dependencies are not present.
99
On Ubuntu, you can install them with this command (you must have some
100
repositories enabled in Software Sources)::
101
102
    $ sudo apt-get build-dep bzr
103
104
To build the binary extensions::
105
106
    $ make
107
5037.2.7 by Martin Pool
Better contribution information, replacing wiki page
108
For more information: `Testing Guide <testing.html>`_.
109
5037.2.8 by Martin Pool
Clearer instructions on building and getting started
110
5037.2.7 by Martin Pool
Better contribution information, replacing wiki page
111
Proposing a merge
112
-----------------
113
114
115
Then propose a merge into bzr; for bzr 2.2 and later you can use the ``bzr
116
propose-merge`` command.  In the comment for your merge proposal please
117
explain what you're trying to do and why.  For `example
118
<https://code.launchpad.net/~ian-clatworthy/bzr/whats-new-in-2.1/+merge/19677>`_:
119
120
  As discussed on the mailing list, this patch adds a What's New document
121
  summarising the changes since 2.0.
122
5037.2.10 by Martin Pool
Tips for code review
123
If you make additional changes to your branch you don't need to resubmit;
124
they'll automatically show up in the merge proposal.
125
126
* `Launchpad Code Review Help <http://help.launchpad.net/Code/Review>`_.
127
4806.1.2 by Andrew Bennetts
Add 5 minute contribution guide contributed by Stephen Turnbull.
128
129
..
130
   vim: ft=rst tw=74 ai