← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/en/user-guide/sending_changes.txt

(vila) Fix test failures blocking package builds. (Vincent Ladeuil)

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/user-guide/sending_changes.txt
 
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
 
 
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/index.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::
 
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.