← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/contribution-quickstart.txt

  • Committer: John Arbash Meinel
  • Date: 2008-08-28 20:13:31 UTC
  • mfrom: (3658 +trunk)
  • mto: This revision was merged to the branch mainline in revision 3688.
  • Revision ID: john@arbash-meinel.com-20080828201331-dqffxf54l2heokll
Merge bzr.dev 3658

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/contribution-quickstart.txt
1
 
Contributing to Bazaar
2
 
======================
3
 
 
4
 
Talk to us
5
 
----------
6
 
 
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
 
 
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.
15
 
 
16
 
* `Bazaar mailing list <http://lists.ubuntu.com/mailman/listinfo/bazaar>`_
17
 
 
18
 
* IRC in channel ``#bzr`` on ``irc.ubuntu.com``
19
 
 
20
 
 
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.launchpad.net/bzr/+bugs?field.tag=easy>`_.
30
 
 
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.
34
 
 
35
 
Making a branch
36
 
---------------
37
 
 
38
 
First, get a local copy of Bazaar::
39
 
 
40
 
   $ cd $HOME
41
 
   $ bzr init-repo bzr
42
 
   $ cd bzr
43
 
   $ bzr branch lp:bzr bzr.dev
44
 
 
45
 
Now make your own branch; we recommend you include the bug number and also
46
 
a brief description::
47
 
 
48
 
   $ bzr branch bzr.dev 123456-status-speed
49
 
 
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
52
 
flow more smoothly.
53
 
 
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,
56
 
ie ::
57
 
 
58
 
   $ bzr branch lp:bzr/2.1 bzr.2.1
59
 
   $ bzr branch bzr.2.1 123458-2.1-status
60
 
 
61
 
You probably want this configuration in ``~/.bazaar/locations.conf``::
62
 
 
63
 
    [/home/USER/bzr]
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
68
 
 
69
 
with your local and Launchpad usernames inserted.
70
 
 
71
 
 
72
 
 
73
 
Publishing your changes
74
 
-----------------------
75
 
 
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 ::
78
 
 
79
 
    $ bzr push
80
 
 
81
 
 
82
 
Writing tests
83
 
-------------
84
 
 
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.
89
 
 
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``.
94
 
 
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.
97
 
 
98
 
To run the tests::
99
 
 
100
 
    $ ./bzr selftest
101
 
 
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)::
105
 
 
106
 
    $ sudo apt-get build-dep bzr
107
 
 
108
 
To build the binary extensions::
109
 
 
110
 
    $ make
111
 
 
112
 
For more information: `Testing Guide <testing.html>`_.
113
 
 
114
 
 
115
 
Proposing a merge
116
 
-----------------
117
 
 
118
 
 
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>`_:
123
 
 
124
 
  As discussed on the mailing list, this patch adds a What's New document
125
 
  summarising the changes since 2.0.
126
 
 
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.
129
 
 
130
 
* `Launchpad Code Review Help <http://help.launchpad.net/Code/Review>`_.
131
 
 
132
 
 
133
 
..
134
 
   vim: ft=rst tw=74 ai