~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

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

  • Committer: Martin Pool
  • Date: 2010-02-25 06:17:27 UTC
  • mfrom: (5055 +trunk)
  • mto: This revision was merged to the branch mainline in revision 5057.
  • Revision ID: mbp@sourcefrog.net-20100225061727-4sd9lt0qmdc6087t
merge news

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
 
Bazaar Contribution in Five Minutes
2
 
===================================
3
 
 
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.
7
 
 
8
 
In brief, a contribution should include:
9
 
 
10
 
1.  A brief rationale, including expected audience and use cases,
11
 
    for inclusion in Bazaar.
12
 
 
13
 
2.  A branch registered as a branch on Launchpad, and submitted as
14
 
    a merge proposal.
15
 
 
16
 
3.  The branch should include:
17
 
 
18
 
    a.  implementation of the feature,
19
 
 
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
23
 
 
24
 
    c.  tests to ensure the specification is correctly
25
 
        implemented.
26
 
 
27
 
For more information, see the `Bazaar Developer Guide <HACKING.html>`_.
28
 
 
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).
34
 
 
35
 
 
36
 
Current Bazaar Mentors
37
 
----------------------
38
 
 
39
 
See the roster at http://bazaar-vcs.org/PatchPilot, although other
40
 
developers may help too!
41
 
 
42
 
 
43
 
Bazaar Mentors FAQ
44
 
------------------
45
 
 
46
 
1.  Why is this "Bazaar process" in HACKING.txt so complicated?
47
 
 
48
 
    Answer: If we knew *that*, we'd simplify it!  We are working
49
 
    on streamlining many aspects, but quality comes first.
50
 
 
51
 
1.  What sort of things can a mentor help with?
52
 
 
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
56
 
    feature, and so on.
 
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.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
 
 
59
    [/home/USER/bzr]
 
60
    push_location = lp:~LAUNCHPAD_USER/bzr/
 
61
    push_location:policy = appendpath
 
62
    public_branch = http://bazaar.launchpad.net/~LAUNCHPAD_USER/bzr/
 
63
    public_branch:policy = appendpath
 
64
 
 
65
with your local and Launchpad usernames inserted.
 
66
 
 
67
 
 
68
Writing tests
 
69
-------------
 
70
 
 
71
We value test coverage and generally all changes should have or update a
 
72
test.  There is a powerful test framework but it can be hard to find the
 
73
right place to put your test.  Don't hesitate to ask, or to propose a
 
74
merge that does not yet have tests.
 
75
 
 
76
Normally for command-line code you should look in
 
77
``bzrlib.tests.blackbox`` and for library code in ``bzrlib.tests``.  For
 
78
functions on an interface for which there are multiple implementations,
 
79
like `Transport`, look in ``bzrlib.tests.per_transport``.
 
80
 
 
81
It's a good idea to search the tests for something related to the thing
 
82
you're changing and you may find a test you can modify or adapt.
 
83
 
 
84
To run the tests::
 
85
 
 
86
    $ ./bzr selftest
 
87
 
 
88
Normally the tests will skip if some library dependencies are not present.
 
89
On Ubuntu, you can install them with this command (you must have some
 
90
repositories enabled in Software Sources)::
 
91
 
 
92
    $ sudo apt-get build-dep bzr
 
93
 
 
94
To build the binary extensions::
 
95
 
 
96
    $ make
 
97
 
 
98
For more information: `Testing Guide <testing.html>`_.
 
99
 
 
100
 
 
101
Proposing a merge
 
102
-----------------
 
103
 
 
104
 
 
105
Then propose a merge into bzr; for bzr 2.2 and later you can use the ``bzr
 
106
propose-merge`` command.  In the comment for your merge proposal please
 
107
explain what you're trying to do and why.  For `example
 
108
<https://code.launchpad.net/~ian-clatworthy/bzr/whats-new-in-2.1/+merge/19677>`_:
 
109
 
 
110
  As discussed on the mailing list, this patch adds a What's New document
 
111
  summarising the changes since 2.0.
 
112
 
 
113
If you make additional changes to your branch you don't need to resubmit;
 
114
they'll automatically show up in the merge proposal.
 
115
 
 
116
* `Launchpad Code Review Help <http://help.launchpad.net/Code/Review>`_.
 
117
 
57
118
 
58
119
..
59
120
   vim: ft=rst tw=74 ai