4
Merge mode is where only the packaging changes are versioned, that is the
5
branch contains only the ``debian/`` directory. Some people prefer this
6
mode, as it clearly separates the packaging changes from the upstream code.
8
It does however have a few drawbacks, the first being that some tools do not
9
understand this mode, and so may not work without some work on your part.
10
The second is that patches to the upstream source can be a little unwieldy
11
to handle, especially when updating to a new upstream version. I hope to add
12
some support for doing this in a later version. The last is that importing
13
history is difficult, if not impossible if the old versions of the package
14
touched anything outside of the ``debian/`` directory. Currently importing
15
history is not supported, even for packages that confine their changes to
16
the packaging directory.
18
Setting up the package
19
######################
21
As stated above importing existing packages is not supported yet, and so if
22
you choose this mode you will either have to do this yourself, or abandon
23
the history. I will only describe here how to create a new package.
25
Creating a New Package
26
^^^^^^^^^^^^^^^^^^^^^^
28
First you may find it beneficial to set up a shared repository for the
29
package. Shared in this context means shared between your branches, rather
30
than shared between users in a public location, the latter can be done
31
later. To set up a repository then you should run (for a package named
36
$ bzr init-repo ~/packages/scruff/
37
$ cd ~/packages/scruff/
39
and then do all of your work in that directory.
41
Now you need to create a branch in which to create the package, to do that
46
$ bzr init --dirstate-trees scruff/
49
The ``--dirstate-tags`` option here ensures that the branch supports tags,
50
as the current default branch format in Bazaar does not.
52
Now you have a branch that you will create the package in you need to tell
53
`bzr-builddeb` that it will be built in merge mode. To do this you need to
54
create the configuration file ``.bzr-builddeb/default.conf``. This contains
55
the default options for the package. The file starts with a ``[BUILDDEB]``
56
header which states that the file is for use by `bzr-builddeb`. The option
57
we are interested in is the ``merge`` option. The commands to do this are::
59
$ mkdir .bzr-builddeb/
60
$ echo -e '[BUILDDEB]\nmerge = True' > .bzr-builddeb/default.conf
61
$ bzr add .bzr-builddeb/default.conf
63
Now you should add the packaging files to the branch. You have a choice
64
here, either you can add a ``debian/`` directory containing the files,
65
or you can place them directly in the root of the branch, `bzr-builddeb`
66
supports both layouts. The latter layout is preferred by some as it
67
removes the extra directory at the root. However doing this makes some tools
68
more difficult to work with, as they expect to find ``debian/changelog`` or
69
similar, where you only have ``changelog``. This can normally be worked
70
around, or you can add a symlink like::
75
that will allow some tools to work.
77
Once you have made the decision then add the packaging files to the branch,
78
run ``bzr add`` to tell Bazaar to version the files, and then make the first
81
Merge mode requires the upstream tarballs to be available when building. By
82
default it searches for them in ``../tarballs/``. If you would like to use a
83
different location then see the `Configuration Files`_ section. First you
84
should create this directory::
88
and then add the upstream tarballs to it. The plugin expects them to be
89
named as they would be in a source package, that is the tarball for version
90
``0.1`` of ``scruff`` would be::
92
scruff_0.1.orig.tar.gz
94
In the future you will be able to use the ``merge-upstream`` command to do
95
this for you, but it has not been made to support merge mode yet.
97
.. _Configuration Files: configuration.html
99
One the tarballs are in place then you are ready to build the package. See
100
the `Building the package`_ section for more details on this.
102
.. _Building the package: building.html
107
There are three steps to updating a merge mode package to a new upstream
108
version. The first is to download the new upstream tarball, and place it in
109
``../tarballs/``, named as the plugin expects to find it (see above). The
110
``merge-upstream`` command will automate this part of the process in the
111
future, but for now it must be done manually.
113
The next step is to update the changelog for the new version. This can be
114
done using the ``dch`` command, for instance to update to version ``0.2-1``
115
of the package you would run::
119
Note that if you put all of the packaging files in the root of the branch
120
you will need to add the ``-c changelog`` option.
122
The last step is to update the packaging. The first part of this is changing
123
any files to reflect changes in the upstream build, for instance updating
124
``debian/rules``, or ``debian/install``. The last part is updating any
125
patches that have against the upstream code to work against the latest
126
version. This is currently quite troublesome, as you need an unpacked source
127
to apply them against. The easiest way to do this is to use the ``--export``
128
option of ``builddeb`` to get the unpacked source::
130
$ bzr builddeb --export
132
(the ``-w`` option might also be useful here, see the `Building the
133
package`_ section for more details on this option).
135
Then you can ``cd`` to the exported directory, refresh the patches, and copy
136
them back in to the branch.
138
This is a tedious operation, and one that I hope to make easier with support
139
in the plugin in a later version.
141
.. vim: set ft=rst tw=76 :
added
removed
doc/user_manual/merge.rst
