|
2977.1.10
by Ian Clatworthy
2nd cut at Distributed collaboration chapter |
1 |
Sending changes |
2 |
=============== |
|
3 |
||
4 |
Motivation |
|
5 |
---------- |
|
6 |
||
7 |
In many distributed development scenarios, it isn't always feasible for |
|
8 |
developers to share task branches by advertising their URLs. |
|
9 |
For example, a developer working on a laptop might take it home overnight |
|
10 |
so his/her task branches could well be inaccessible when a gatekeeper |
|
11 |
in another timezone wants to review or merge it. |
|
12 |
||
13 |
Bazaar provides a neat feature to assist here: *merge directives*. |
|
14 |
||
15 |
Understanding merge directives |
|
16 |
------------------------------ |
|
17 |
||
18 |
You can think of a merge directive as a "mini branch" - just the |
|
19 |
new growth on a branch since it was created. It's a software |
|
20 |
patch showing what's new but with added intelligence: metadata |
|
21 |
like interim commits, renames and digital signatures. |
|
22 |
||
23 |
Another useful metaphor is a packet cake: a merge directive has a recipe |
|
24 |
together with the ingredients you need bundled inside it. |
|
25 |
To stretch the metaphor, the ingredients are all the metadata on the |
|
26 |
changes made to the branch; the recipe is instructions on how those |
|
27 |
changes ought to be merged, i.e. information for the ``merge`` command |
|
28 |
to use in selecting common ancestors. |
|
29 |
||
30 |
Regardless of how you think of them, merge directives are neat. |
|
31 |
They are easy to create, suitable for mailing around as attachments |
|
32 |
and can be processed much like branches can on the receiving end. |
|
33 |
||
34 |
Creating a merge directive |
|
35 |
-------------------------- |
|
36 |
||
|
3377.2.1
by Martin Pool
doc: send -o, and more on send in user guide |
37 |
To create and optionally send a merge directive, use the ``send`` command. |
38 |
||
39 |
By default, ``send`` will email the merge directive to the "submission |
|
40 |
address" for the branch, which is typically the lead developer or the |
|
41 |
development mailing list. |
|
42 |
``send`` without options will create a merge directive, fire up your email |
|
43 |
tool and attach it, ready for you to add the explanatory text bit. |
|
44 |
(See the online help for ``send`` and |
|
45 |
`Configuration Settings <../user-reference/bzr_man.html#configuration-settings>`_ |
|
46 |
in the User Reference for further details on how to configure this.) |
|
47 |
||
48 |
Most projects like people to add some explanation to the mail along with |
|
49 |
the patch, explaining the reason for the patch, and why it is done the way |
|
50 |
it is. This gives a reviewer some context before going into the |
|
51 |
line-by-line diff. |
|
52 |
||
53 |
Alternatively, if the ``--output`` (or ``-o``) option is given, ``send`` |
|
54 |
will write the merge directive to a file, so you can mail it yourself, |
|
55 |
examine it, or save it for later use. If an output file of ``-`` is |
|
56 |
given, the directive is written to stdout. For example:: |
|
|
2977.1.10
by Ian Clatworthy
2nd cut at Distributed collaboration chapter |
57 |
|
58 |
cd X-fix-123 |
|
59 |
bzr send -o ../fix-123.patch |
|
60 |
||
61 |
||
62 |
Applying a merge directive |
|
63 |
-------------------------- |
|
64 |
||
65 |
Merge directives can be applied in much the same way as branches: by |
|
66 |
using the ``merge`` and ``pull`` commands. |
|
67 |
||
68 |
They can also be useful when communicating with upstream projects |
|
69 |
that don't use Bazaar. In particular, the preview of the overall |
|
70 |
change in a merge directive looks like a vanilla software patch, so |
|
71 |
they can be applied using ``patch -p0`` for example. |