82
82
Bazaar Development in a Nutshell
83
83
================================
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.
85
.. was from bazaar-vcs.org/BzrGivingBack
87
One of the fun things about working on a version control system like Bazaar is
88
that the users have a high level of proficiency in contributing back into
89
the tool. Consider the following very brief introduction to contributing back
90
to Bazaar. More detailed instructions are in the following sections.
95
First, get a local copy of the development mainline (See `Why make a local
101
$ bzr branch http://bazaar-vcs.org/bzr/bzr.dev/ bzr.dev
103
Now make your own branch::
105
$ bzr branch bzr.dev 123456-my-bugfix
107
This will give you a branch called "123456-my-bugfix" that you can work on
108
and commit in. Here, you can study the code, make a fix or a new feature.
109
Feel free to commit early and often (after all, it's your branch!).
111
Documentation improvements are an easy place to get started giving back to the
112
Bazaar project. The documentation is in the `doc/` subdirectory of the Bazaar
115
When you are done, make sure that you commit your last set of changes as well!
116
Once you are happy with your changes, ask for them to be merged, as described
119
Making a Merge Proposal
120
-----------------------
122
The Bazaar developers use Launchpad to further enable a truly distributed
123
style of development. Anyone can propose a branch for merging into the Bazaar
124
trunk. To start this process, you need to push your branch to Launchpad. To
125
do this, you will need a Launchpad account and user name, e.g.
126
`your_lp_username`. You can push your branch to Launchpad directly from
129
$ bzr push lp:~your_lp_username/bzr/giveback
131
After you have pushed your branch, you will need to propose it for merging to
132
the Bazaar trunk. Go to <https://launchpad.net/your_lp_username/bzr/giveback>
133
and choose "Propose for merging into another branch". Select "~bzr/bzr/trunk"
134
to hand your changes off to the Bazaar developers for review and merging.
136
Why make a local copy of bzr.dev?
137
---------------------------------
139
Making a local mirror of bzr.dev is not strictly necessary, but it means
141
- You can use that copy of bzr.dev as your main bzr executable, and keep it
142
up-to-date using ``bzr pull``.
143
- Certain operations are faster, and can be done when offline. For example:
146
- ``bzr diff -r ancestor:...``
149
- When it's time to create your next branch, it's more convenient. When you
150
have further contributions to make, you should do them in their own branch::
153
$ bzr branch bzr.dev additional_fixes
154
$ cd additional_fixes # hack, hack, hack
91
158
Understanding the Development Process
213
280
Good reviews do take time. They also regularly require a solid
214
281
understanding of the overall code base. In practice, this means a small
215
282
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
283
responsibility. No one likes their merge requests sitting in a queue going
217
284
nowhere, so reviewing sooner rather than later is strongly encouraged.
332
399
Proposing a merge through the web
333
400
---------------------------------
335
To create the propsal through the web: push your branch to Launchpad, eg::
402
To create the proposal through the web, first push your branch to Launchpad.
403
For example, a branch dealing with documentation belonging to the Launchpad
404
User mbp could be pushed as ::
337
406
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
408
Then go to the branch's web page, which in this case would be
409
<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.
414
You can then click "Propose for merging into another branch", and enter your
415
cover letter (see above) into the web form. Typically you'll want to merge
416
into ``~bzr/bzr/trunk`` which will be the default; you might also want to
417
nominate merging into a release branch for a bug fix. There is the option to
418
specify a specific reviewer or type of review, and you shouldn't normally
352
421
Submitting the form takes you to the new page about the merge proposal
353
422
containing the diff of the changes, comments by interested people, and
799
868
_function or ...) behind which forwards to the new API. See the
800
869
bzrlib.symbol_versioning module for decorators that take care of the
801
870
details for you - such as updating the docstring, and issuing a warning
802
when the old api is used.
871
when the old API is used.
804
873
For unsupported API's, it does not hurt to follow this discipline, but it's
805
874
not required. Minimally though, please try to rename things so that
922
991
The user should call `finish` on the `ProgressTask` when the logical
923
992
operation has finished, so it can be removed from the stack.
925
Progress tasks have a complex relatioship with generators: it's a very
994
Progress tasks have a complex relationship with generators: it's a very
926
995
good place to use them, but because python2.4 does not allow ``finally``
927
996
blocks in generators it's hard to clean them up properly. In this case
928
997
it's probably better to have the code calling the generator allocate a
1236
1305
Attempting to print an unprintable character will cause a UnicodeError.
1237
1306
This is for commands that are intended more as scripting support, rather
1238
1307
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``
1308
For example: ``bzr ls`` is designed to be used with shell scripting. One
1309
use would be ``bzr ls --null --unknowns | xargs -0 rm``. If ``bzr``
1241
1310
printed a filename with a '?', the wrong file could be deleted. (At the
1242
1311
very least, the correct file would not be deleted). An error is used to
1243
1312
indicate that the requested action could not be performed.
1542
1611
https://blueprints.launchpad.net/bzr/. Once a blueprint for ready for
1543
1612
review, please announce it on the mailing list.
1545
Alternatively, send an email begining with [RFC] with the proposal to the
1614
Alternatively, send an email beginning with [RFC] with the proposal to the
1546
1615
list. In some cases, you may wish to attach proposed code or a proposed
1547
1616
developer document if that best communicates the idea. Debate can then
1548
1617
proceed using the normal merge review processes.
added
removed
doc/en/developer-guide/HACKING.txt
