11
11
the Bazaar mailing list. To propose a correction or addition to this
12
12
document, send a merge request or new text to the mailing list.
14
The current version of this document is available in the file
15
``doc/en/developer-guide/HACKING.txt`` in the source tree, or at
16
http://doc.bazaar-vcs.org/bzr.dev/en/developer-guide/HACKING.html
19
`Bazaar Developer Documentation Catalog <../../developers/index.html>`_.
14
The latest developer documentation can be found online at
15
http://doc.bazaar-vcs.org/developers/.
82
76
Bazaar Development in a Nutshell
83
77
================================
85
Looking for a 10 minute introduction to submitting a change?
86
See http://bazaar-vcs.org/BzrGivingBack.
88
TODO: Merge that Wiki page into this document.
79
.. was from bazaar-vcs.org/BzrGivingBack
81
One of the fun things about working on a version control system like Bazaar is
82
that the users have a high level of proficiency in contributing back into
83
the tool. Consider the following very brief introduction to contributing back
84
to Bazaar. More detailed instructions are in the following sections.
89
First, get a local copy of the development mainline (See `Why make a local
95
$ bzr branch http://bazaar-vcs.org/bzr/bzr.dev/ bzr.dev
97
Now make your own branch::
99
$ bzr branch bzr.dev 123456-my-bugfix
101
This will give you a branch called "123456-my-bugfix" that you can work on
102
and commit in. Here, you can study the code, make a fix or a new feature.
103
Feel free to commit early and often (after all, it's your branch!).
105
Documentation improvements are an easy place to get started giving back to the
106
Bazaar project. The documentation is in the `doc/` subdirectory of the Bazaar
109
When you are done, make sure that you commit your last set of changes as well!
110
Once you are happy with your changes, ask for them to be merged, as described
113
Making a Merge Proposal
114
-----------------------
116
The Bazaar developers use Launchpad to further enable a truly distributed
117
style of development. Anyone can propose a branch for merging into the Bazaar
118
trunk. To start this process, you need to push your branch to Launchpad. To
119
do this, you will need a Launchpad account and user name, e.g.
120
`your_lp_username`. You can push your branch to Launchpad directly from
123
$ bzr push lp:~your_lp_username/bzr/giveback
125
After you have pushed your branch, you will need to propose it for merging to
126
the Bazaar trunk. Go to <https://launchpad.net/your_lp_username/bzr/giveback>
127
and choose "Propose for merging into another branch". Select "~bzr/bzr/trunk"
128
to hand your changes off to the Bazaar developers for review and merging.
130
Why make a local copy of bzr.dev?
131
---------------------------------
133
Making a local mirror of bzr.dev is not strictly necessary, but it means
135
- You can use that copy of bzr.dev as your main bzr executable, and keep it
136
up-to-date using ``bzr pull``.
137
- Certain operations are faster, and can be done when offline. For example:
140
- ``bzr diff -r ancestor:...``
143
- When it's time to create your next branch, it's more convenient. When you
144
have further contributions to make, you should do them in their own branch::
147
$ bzr branch bzr.dev additional_fixes
148
$ cd additional_fixes # hack, hack, hack
91
152
Understanding the Development Process
213
275
Good reviews do take time. They also regularly require a solid
214
276
understanding of the overall code base. In practice, this means a small
215
277
number of people often have a large review burden - with knowledge comes
216
responsibility. No one like their merge requests sitting in a queue going
278
responsibility. No one likes their merge requests sitting in a queue going
217
279
nowhere, so reviewing sooner rather than later is strongly encouraged.
332
394
Proposing a merge through the web
333
395
---------------------------------
335
To create the propsal through the web: push your branch to Launchpad, eg::
397
To create the proposal through the web, first push your branch to Launchpad.
398
For example, a branch dealing with documentation belonging to the Launchpad
399
User mbp could be pushed as ::
337
401
bzr push lp:~mbp/bzr/doc
339
then go to the branch's web page, which in this case would be
340
<https://code.launchpad.net/~mbp/bzr/doc>. You can automate that by just
403
Then go to the branch's web page, which in this case would be
404
<https://code.launchpad.net/~mbp/bzr/doc>. You can simplify this step by just
345
You can then click "Propose for merging into another branch", and enter a
346
cover letter into the web form. Typically you'll want to merge into
347
``~bzr/bzr/trunk`` which will be the default; you might also want to
348
nominate merging into a release branch for a bug fix. There is the option
349
to specify a specific reviewer or type of review, and you shouldn't
350
normally change those.
409
You can then click "Propose for merging into another branch", and enter your
410
cover letter (see above) into the web form. Typically you'll want to merge
411
into ``~bzr/bzr/trunk`` which will be the default; you might also want to
412
nominate merging into a release branch for a bug fix. There is the option to
413
specify a specific reviewer or type of review, and you shouldn't normally
352
416
Submitting the form takes you to the new page about the merge proposal
353
417
containing the diff of the changes, comments by interested people, and
799
864
_function or ...) behind which forwards to the new API. See the
800
865
bzrlib.symbol_versioning module for decorators that take care of the
801
866
details for you - such as updating the docstring, and issuing a warning
802
when the old api is used.
867
when the old API is used.
804
869
For unsupported API's, it does not hurt to follow this discipline, but it's
805
870
not required. Minimally though, please try to rename things so that
922
987
The user should call `finish` on the `ProgressTask` when the logical
923
988
operation has finished, so it can be removed from the stack.
925
Progress tasks have a complex relatioship with generators: it's a very
990
Progress tasks have a complex relationship with generators: it's a very
926
991
good place to use them, but because python2.4 does not allow ``finally``
927
992
blocks in generators it's hard to clean them up properly. In this case
928
993
it's probably better to have the code calling the generator allocate a
1236
1301
Attempting to print an unprintable character will cause a UnicodeError.
1237
1302
This is for commands that are intended more as scripting support, rather
1238
1303
than plain user review.
1239
For exampl: ``bzr ls`` is designed to be used with shell scripting. One
1240
use would be ``bzr ls --null --unknows | xargs -0 rm``. If ``bzr``
1304
For example: ``bzr ls`` is designed to be used with shell scripting. One
1305
use would be ``bzr ls --null --unknowns | xargs -0 rm``. If ``bzr``
1241
1306
printed a filename with a '?', the wrong file could be deleted. (At the
1242
1307
very least, the correct file would not be deleted). An error is used to
1243
1308
indicate that the requested action could not be performed.
1542
1607
https://blueprints.launchpad.net/bzr/. Once a blueprint for ready for
1543
1608
review, please announce it on the mailing list.
1545
Alternatively, send an email begining with [RFC] with the proposal to the
1610
Alternatively, send an email beginning with [RFC] with the proposal to the
1546
1611
list. In some cases, you may wish to attach proposed code or a proposed
1547
1612
developer document if that best communicates the idea. Debate can then
1548
1613
proceed using the normal merge review processes.
added
removed
doc/developers/HACKING.txt
