Merge lp:~al-maisan/bzr-builddeb/mpdocs into lp:~bzr-builddeb-hackers/bzr-builddeb/trunk-old

[Muharem Hrnjadovic]

[Muharem Hrnjadovic (al-maisan)]

Hello there!

The branch at hand adds the documentation for the "merge-package" command. Please take a look. Thanks!

[James Westby (james-w)]

Merged, thank you.

James

review: Approve

=== modified file 'doc/user_manual/normal.rst'
--- doc/user_manual/normal.rst	2009-02-18 22:50:44 +0000
+++ doc/user_manual/normal.rst	2009-09-04 09:41:10 +0000
@@ -276,5 +276,38 @@
 edit the files to resolve the conflicts as normal. Once you have finished
 you should commit, and then you can carry on with your work.
 
+Merging a source package
+########################
+
+When merging a source package the ensuing differences will ideally be
+germane to the target packaging branch. However, on occasion the source and
+target upstream ancestry may have diverged, resulting in spurious conflicts.
+
+The 'merge-package' command can then be used to consolidate the ancestry in
+automated fashion. For example::
+
+    $ bzr branch ~/src/ubuntu/karmic/ipsec-tools/karmic/
+    $ cd karmic/
+    $ bzr merge-package ~/src/debian/sid/ipsec-tools/sid/
+
+On success ``merge-package`` will leave the branch in the same state as a
+normal merge allowing you to review and commit.
+
+In a small number of cases, however, the source `upstream` and target
+`packaging` branches will have conflicts that cause the following error
+instead::
+
+    The upstream branches for the merge source and target have diverged.
+    Unfortunately, the attempt to fix this problem resulted in conflicts.
+    Please resolve these, commit and re-run the "merge-package" command to
+    finish. 
+    Alternatively, until you commit you can use "bzr revert" to restore the
+    state of the unmerged branch.
+
+Resolving the conflicts at hand, committing the changes and re-running
+``merge-package`` to finish is probably the best course of action. Having
+said that, you can return to the state before starting with ``bzr revert``
+just like with a normal merge.
+
 .. vim: set ft=rst tw=76 :