Difference between revisions of "Working with Bazaar"

From Inkscape Wiki
Jump to navigation Jump to search
(Conflict handling)
(emphasize working with a checkout by default, add info on Git workflow)
Line 35: Line 35:
  
 
Then fetch Inkscape's trunk
 
Then fetch Inkscape's trunk
  $ bzr branch lp:inkscape
+
  $ bzr checkout lp:inkscape
  
 
To carry out a later update of Inkscape's trunk
 
To carry out a later update of Inkscape's trunk
  $ bzr pull lp:inkscape
+
  $ bzr update lp:inkscape
  
 
==Using a centralized (SVN-like) workflow==
 
==Using a centralized (SVN-like) workflow==
Line 46: Line 46:
 
===SVN-style checkout===
 
===SVN-style checkout===
  
Get the latest Inkscape code as a checkout, rather than a branch:
+
Get the latest Inkscape code as a checkout, as described above.
 
  $ bzr checkout lp:inkscape
 
  $ bzr checkout lp:inkscape
  
Line 59: Line 59:
 
If you add new files, add them to version control with <tt>bzr add ''file''</tt>. You can recursively add all new files by writing simply <tt>bzr add</tt> in the top level directory.
 
If you add new files, add them to version control with <tt>bzr add ''file''</tt>. You can recursively add all new files by writing simply <tt>bzr add</tt> in the top level directory.
  
===Binding a BZR branch===
+
===Binding a Bazaar branch===
  
Get Inkscape's code the regular bzr way:
+
Branch Inkscape's code:
 
  $ bzr branch lp:inkscape
 
  $ bzr branch lp:inkscape
  
Line 83: Line 83:
 
* <tt>bzr commit ''file''</tt> works like <tt> svn commit ''file'' && svn update ''project-root''</tt>. After a successful partial commit, the entire tree's revision is increased by 1.
 
* <tt>bzr commit ''file''</tt> works like <tt> svn commit ''file'' && svn update ''project-root''</tt>. After a successful partial commit, the entire tree's revision is increased by 1.
 
* No special server is needed to publish a branch. You can push branches to anywhere, including simple FTP shares. In our scenario, Launchpad works like a central repository, but it's not required to publish everything there.
 
* No special server is needed to publish a branch. You can push branches to anywhere, including simple FTP shares. In our scenario, Launchpad works like a central repository, but it's not required to publish everything there.
* You create branches locally. To simulate creating a SVN-style branch on Launchpad, you need to create a local branch, push it, then bind it to the pushed location.
+
* You create branches locally. To simulate creating a SVN-style branch on Launchpad, you need to create a local branch, push it, then bind it to the pushed location:
 +
$ bzr branch trunk killer-feature
 +
$ cd killer-feature
 +
  <do work>
 +
$ bzr push lp:~inkscape.dev/inkscape/killer-feature
 +
$ bzr bind :push
 
<!--
 
<!--
 
* In some cases it is possible to create subrevisions. When two branches with a common parent are merged, all commits to one of them since the time they diverged will be grouped into one revision. To avoid this, when committing your work to trunk, you should merge from your branch into trunk and push the trunk, rather than merging trunk into your work and pushing your branch as the new trunk.
 
* In some cases it is possible to create subrevisions. When two branches with a common parent are merged, all commits to one of them since the time they diverged will be grouped into one revision. To avoid this, when committing your work to trunk, you should merge from your branch into trunk and push the trunk, rather than merging trunk into your work and pushing your branch as the new trunk.
Line 90: Line 95:
 
==Using a decentralized workflow==
 
==Using a decentralized workflow==
  
In this case you will be working locally until you are ready to publish your changes. The basic idea is to perform the work in a ''branch'' of the Inkscape repository, since committing to a branch stores the changes locally in the branch itself. Then, to share the work with the rest of the Inkscape community, the changes in the branch are merged across to a ''checkout'' of the Inkscape repository. As the previous centralized workflow section describes, committing to a checkout sends the changes directly to the remote repository, making them part of the official Inkscape codebase.
+
In this case you will be working locally until you are ready to publish your changes. The basic idea is to perform the work in a ''branch'' of the Inkscape codebase, since committing to a branch stores the changes locally in the branch itself. Then, to share the work with the rest of the Inkscape community, the changes in the branch are merged across to a ''checkout'' of the Inkscape repository. As the previous centralized workflow section describes, committing to a checkout sends the changes directly to the remote repository, making them part of the official Inkscape codebase.
  
 
'''NOTE:''' this workflow has been updated to avoid the "other people's commits become subrevisions of your commit" problem.
 
'''NOTE:''' this workflow has been updated to avoid the "other people's commits become subrevisions of your commit" problem.
Line 134: Line 139:
 
To undo a commit:
 
To undo a commit:
 
  $ bzr uncommit
 
  $ bzr uncommit
This will leave your working tree in the state it was just before you wrote "bzr commit". This is useful for example if you forgot to add a file, and want to keep a clean revision history. This will NOT work on a trunk checkout.
+
This will leave your working tree in the state it was just before you wrote "bzr commit". This is useful for example if you forgot to add a file, and want to keep a clean revision history. '''This will not work on a trunk checkout.'''
  
Let's say you started from r770 200 local commits, but you decided that what you did since r954 is completely wrong. You want to go back to revision 825 and do it differently. Here's one way to do this. First branch locally to preserve your work (maybe later you'll find out there's some way to save it). Then uncommit everything up to r954 and revert.
+
Let's say you started from r770, made 200 local commits, but you decided that what you did since r954 is completely wrong. You want to go back to revision 954 and do it differently. Here's one way to do this. First branch locally to preserve your work (maybe later you'll find out there's some way to save it). Then uncommit everything up to r954 and revert.
 
  $ bzr branch myproject myproject-dead-end
 
  $ bzr branch myproject myproject-dead-end
 
  $ cd myproject
 
  $ cd myproject
Line 161: Line 166:
 
  $ bzr launchpad-login johnq
 
  $ bzr launchpad-login johnq
  
Publish your branch on Launchpad.
+
Publish your branch on Launchpad. If you push it under your username, only you will be able to modify it. If you have commit access and publish your branch under the username <tt>inkscape.dev</tt>, all Inkscape developers will be able to change it.
 
  $ bzr push lp:~johnq/inkscape/myproject
 
  $ bzr push lp:~johnq/inkscape/myproject
 +
$ bzr push lp:~inkscape.dev/inkscape/myproject
  
 
The push location will be saved. After more commits, you can simply write
 
The push location will be saved. After more commits, you can simply write
Line 172: Line 178:
 
===Putting your work in the trunk===
 
===Putting your work in the trunk===
  
Once your new killer feature is ready, you need to merge your changes into a checkout of the trunk.  If you don't have one, do (in the directory ''containing'' myproject):
+
Once your new killer feature you made in a branch is ready, you need to merge your changes into a checkout of the trunk.  If you don't have one, do (in the directory ''containing'' myproject):
 
   $ bzr checkout lp:inkscape trunk
 
   $ bzr checkout lp:inkscape trunk
 
   $ cd trunk
 
   $ cd trunk
Line 184: Line 190:
 
   $ bzr commit -m'added my feature'
 
   $ bzr commit -m'added my feature'
  
WARNING: There is an alternative method that consists of merging trunk into your local branch, then pushing the result as trunk. Do not do this! It obfuscates the revision history.
+
Alternatively, if you don't have a checkout but a branch:
 +
$ bzr merge ../myproject
 +
$ bzr commit -m 'added my feature'
 +
$ bzr push
 +
 
 +
Note that you need to do the above sequence on a branch that has not diverged from the trunk, otherwise it will fail, as the trunk is append-only.
 +
 
 +
WARNING: There is an alternative method that consists of merging trunk into your local branch, then pushing the result as the new trunk. Do not do this! It obfuscates the revision history, and in any case it will fail with Inkscape's trunk on Launchpad.
  
 
===Working with patch files===
 
===Working with patch files===
Line 197: Line 210:
  
 
Naturally, all this also works locally. For example, when you're in the <tt>inkscape</tt> directory, you can write <tt>bzr branch trunk export-dialog</tt> to create a new branch of the trunk called <tt>export-dialog</tt>, where you'll work only on improving the export dialog. Similarly, you can merge between local branches.
 
Naturally, all this also works locally. For example, when you're in the <tt>inkscape</tt> directory, you can write <tt>bzr branch trunk export-dialog</tt> to create a new branch of the trunk called <tt>export-dialog</tt>, where you'll work only on improving the export dialog. Similarly, you can merge between local branches.
 +
 +
==Conflict handling==
 +
 +
Sometimes two people make conflicting changes to the same file. When this happens, you might encounter output like this:
 +
 +
  $ bzr update
 +
  Enter passphrase for key '/home/johnq/.ssh/id_rsa':
 +
  M  src/painting-algorithm.cpp
 +
  M  src/ui/widget/spinner.h
 +
  M  src/ui/widget/spinner.cpp
 +
  M  src/ui/widget/awesome-widget.cpp
 +
  Text conflict in src/ui/widget/spinner.cpp
 +
  1 conflict encountered.
 +
  Updated to revision 10002 of branch [some URL]
 +
 +
After that, the directory <tt>src/ui/widget</tt> will contain four related files.
 +
* <tt>spinner.cpp</tt>: this will contain an unified view of the conflicts in the file. Conflicts will be marked with lines with multiple consecutive angle brackets.
 +
* <tt>spinner.cpp.BASE</tt>: latest common ancestor version of the file. In other words, both you and other people started from this version before conflicting changes were made.
 +
* <tt>spinner.cpp.THIS</tt>: the file with your changes, with conflicting changes by others removed.
 +
* <tt>spinner.cpp.OTHER</tt>: the file with other people's changes, with your conflicting changes removed.
 +
 +
To display the list of conflicts again, use the command:
 +
$ bzr conflicts
 +
 +
To resolve the conflict, you need to modify the contents of the <tt>spinner.cpp</tt>. You can do this either by manually editing the file or by overwriting it with <tt>spinner.cpp.BASE</tt>, <tt>spinner.cpp.THIS</tt> or <tt>spinner.cpp.OTHER</tt>. Once you are done, you need to tell Bazaar about it:
 +
$ bzr resolve src/ui/widget/spinner.cpp
 +
 +
The above command will delete the files <tt>spinner.cpp.BASE</tt>, <tt>spinner.cpp.THIS</tt> and tt>spinner.cpp.OTHER</tt>. Manually deleting those files has the same effect as executing <tt>bzr resolve</tt>. If you resolve all the conflicts at once, you can tell Bazaar to clean up everything:
 +
$ bzr resolve --all
 +
 +
More information on the "[http://doc.bazaar.canonical.com/latest/en/user-guide/resolving_conflicts.html Bazaar manual - Conflict handling]".
 +
 +
==Using a Git-style branches==
 +
 +
Git stores many branches in one directory, and allows you to switch between them. This is also possible in Bazaar. One way is to use native Bazaar facilities, the other is to use the [https://launchpad.net/bzr-colo bzr-colo] plugin. We'll cover the native way, since the plugin has good documentation.
 +
 +
First, create a no-working-trees shared repository. The repo directory can be hidden if you want.
 +
$ bzr init-repo --no-trees .inkscape-repo
 +
 +
Fetch the trunk and any other branches you want into our repository. (You can also push your local branches.)
 +
$ bzr branch lp:inkscape .inkscape-repo/trunk
 +
$ bzr branch lp:inkscape/0.48.x .inkscape-repo/0.48.x
 +
$ bzr push killer-feature .inkscape-repo/killer-feature
 +
 +
Create your working tree by making a lightweight checkout of a desired branch. The <tt>--lightweight</tt> parameter is imp[ortant, otherwise you can run into problems.
 +
$ bzr checkout --lightweight .inkscape-repo/trunk inkscape
 +
$ cd inkscape
 +
 +
If you have an existing checkout of the trunk, use the following command:
 +
$ cd inkscape
 +
$ bzr reconfigure --lightweight-checkout --bind-to ../.inkscape-repo/trunk
 +
 +
Now you can work in the <tt>inkscape</tt> directory like you would on a normal branch. If you want to switch to a different branch, use:
 +
$ bzr switch ../.inkscape-repo/killer-feature
 +
 +
To create a new branch in the repository:
 +
$ bzr switch -b ../.inkscape-repo/killer-feature-2
  
 
==Best Practices for Inkscape Project==
 
==Best Practices for Inkscape Project==
Line 210: Line 280:
 
===Proper way of merging===
 
===Proper way of merging===
  
To repeat, NEVER do something like:
+
To repeat, don't do something like:
 
  $ bzr branch lp:inkscape myproject
 
  $ bzr branch lp:inkscape myproject
 
  ... work ...
 
  ... work ...
Line 217: Line 287:
 
  $ bzr push lp:inkscape
 
  $ bzr push lp:inkscape
  
It will obfuscate the revision history: trunk commits that happened between the time you branched and the time you pushed will get grouped into one. Do the merge the other way around:
+
It would obfuscate the revision history: trunk commits that happened between the time you branched and the time you pushed would get grouped into one. Additionally, to prevent this obfuscation, Inkscape's trunk is set to append-only, so the above sequence of commands would fail. Do the merge the other way around:
  $ bzr branch lp:inkscape myproject
+
  $ bzr branch trunk myproject
 
  $ cd myproject
 
  $ cd myproject
 
  ... work ...
 
  ... work ...
Line 226: Line 296:
 
  $ bzr commit
 
  $ bzr commit
  
You'll need a trunk checkout, but the revision history will be much less confusing, and it's useful to have a trunk checkout anyway.
+
You'll need a trunk checkout, but the revision history will be much less confusing, and it's useful to have a trunk checkout anyway for minor fixes.
  
 
===Fixing a bug in both trunk and a release branch===
 
===Fixing a bug in both trunk and a release branch===
Line 240: Line 310:
  
 
Fix the bug in trunk and commit it, let's say it will be revision 1234.
 
Fix the bug in trunk and commit it, let's say it will be revision 1234.
Then go to the release branch directory, e.g. 0.48.x
+
Go to the release branch directory, e.g. 0.48.x, and write
Then write
 
  
  bzr merge -r 1233..1234 ../trunk
+
$ bzr merge -r 1233..1234 ../trunk
  
The operation can take a while...
+
The operation can take a while. Resolve any conflicts, fix any compilation failures, then commit to the release branch, or post the diff to a Launchpad bug report.
Then commit to the release branch, or post the diff to Launchpad.
 
 
 
==Conflict handling==
 
 
 
Sometimes you ''(or the building script)'' change a file in the same place that other one change and when you update your local repository a conflict happens.
 
 
 
  $ bzr update
 
  Enter passphrase for key '/home/aurium/.ssh/id_rsa':
 
  M  configure.ac
 
  M  po/POTFILES.in
 
  RN  po/inkscape.pot => po/inkscape.pot.OTHER
 
  M  po/it.po
 
  M  src/zoom-context.cpp
 
  Contents conflict in po/inkscape.pot
 
  Conflict adding id to po/inkscape.pot.OTHER.  Unversioned existing file po/inkscape.pot.
 
  2 conflicts encountered.
 
  Updated to revision 10002 of branch bzr+ssh://bazaar.launchpad.net/%2Bbranch/inkscape
 
 
 
Now '''po/inkscape.pot''' become two files:
 
  $ ls po/inkscape.pot*
 
  po/inkscape.pot.BASE  po/inkscape.pot.OTHER
 
 
 
If you forgot/lost the conflict message or has many conflicts to resolve, you may list it wih this command:
 
  $ bzr conflicts
 
  Contents conflict in po/inkscape.pot
 
  Conflict adding id to po/inkscape.pot.OTHER.  Unversioned existing file po/inkscape.pot.
 
 
 
You may use the diff command to help you to discover what was changed and choice for a solution.
 
  $ diff po/inkscape.pot.BASE  po/inkscape.pot.OTHER
 
  11c11
 
  < "POT-Creation-Date: 2010-12-23 18:43+0100\n"
 
  ---
 
  > "POT-Creation-Date: 2011-01-05 20:49+0100\n"
 
  ...
 
 
 
Sometimes the diff will be really big and will not help you. That happens with automatic generated files like '''po/inkscape.pot'''.
 
 
 
On this case my solution was to use the newer pot:
 
  $ bzr mv po/inkscape.pot.OTHER po/inkscape.pot
 
 
 
If you resolve all, run it:
 
  $ bzr resolve -all
 
 
 
More information on the "[http://doc.bazaar.canonical.com/latest/en/user-guide/resolving_conflicts.html Bazaar manual - Conflict handling]".
 
  
 
==External links==
 
==External links==
 
* [http://doc.bazaar-vcs.org/latest/en/ Bazaar manual]
 
* [http://doc.bazaar-vcs.org/latest/en/ Bazaar manual]

Revision as of 17:19, 13 February 2011

Bazaar concepts

It is assumed that you are familiar with the basic concepts of version control, like working copy, committing, updating, conflicts. There will be a section that explains the basic functionality soon.

Branch
is a working copy of the project's code. Typically you use one branch per set of related changes, for example a new output extension. Once your work is finished, you merge your branch into a larger project. Initially, there is only one branch, the trunk; all other branches are its (probably indirect) descendants. To create a new branch, you have to copy an existing one.
Checkout
is a copy of code contained in a branch that is not stored on your computer (a remote branch). Committing to a checkout will immediately apply the changes to the remote branch. Commits will not succeed if somebody else modified the branch while you were working - you need to have an up-to-date working copy - or when you're offline.
When branches A and B have a common ancestor branch but each contain changes not present in the other, they have diverged. For example, when you work on an improved rectangle tool in your own branch and at the same time somebody else applies a PDF export bugfix to the trunk, your rectangle tool branch becomes diverged from the trunk.
Trunk
is the main branch, which represents cutting-edge working code. You should start from it when doing any new development.
Merge
is the process of reconciling changes made between two branches since they diverged. This operation is asymmetric. When you merge A into B, all changes made to A since it was branched from B are applied to B. A is not changed. When you work on some feature, you typically work in a branch, periodically merging the trunk into your branch (to sync up with the latest changes), then you merge your work into the trunk. Merging is similar to applying a patch - it only changes your working copy. To apply a merge, you need to commit the changes it introduced. Merging un-diverges branches.
Repository
is a place where branches of a project are stored. Having a shared repository reduces the storage requirements of multiple branches of one project. Instead of O(number of branches) space, the Bazaar data takes up O(total size of changes in all branches) space.
Bind
is the process of converting a non-diverged local branch into a checkout of the remote branch.
Push
is the process of publishing an exact copy (a mirror) of your branch in some other location. The difference between pushing and checkouts is that a checked out remote branch is updated every time you commit, while a pushed remote branch is updated only when you push to it - you can commit any amount of changes between pushes. You can only push to a branch if the mirror has not diverged from your local copy. This can happen if more than 1 person can push to the same location.
Pull
is the process of creating a local exact copy (mirror) of a branch, in principle a reverse of pushing.

First steps

First you need to tell Bazaar your name. This will appear on all your commits. You should use your real e-mail, but you can obfuscate it if you are afraid of spam.

Obfuscated e-mail examples:

$ bzr whoami "John Q. Public <john dot q dot public at-sign bigmail dot com>"
$ bzr whoami "John Q. Public <removethis.john.q.public@bigmail.com>"

Unobfuscated e-mail example:

$ bzr whoami "John Q. Public <john.q.public@bigmail.com>"

If you have an account on launchpad and want to commit changes there, you need to specify your launchpad login:

$ bzr launchpad-login johnq

Then fetch Inkscape's trunk

$ bzr checkout lp:inkscape

To carry out a later update of Inkscape's trunk

$ bzr update lp:inkscape

Using a centralized (SVN-like) workflow

In this case, every commit that you make is immediately sent to the central repository. There are two ways of achieving this:

SVN-style checkout

Get the latest Inkscape code as a checkout, as described above.

$ bzr checkout lp:inkscape

Now work as in SVN:

 <do work>
$ bzr commit
 <error, someone else has changed things>
$ bzr update
 <check all is okay>
$ bzr commit

If you add new files, add them to version control with bzr add file. You can recursively add all new files by writing simply bzr add in the top level directory.

Binding a Bazaar branch

Branch Inkscape's code:

$ bzr branch lp:inkscape

Then transform your banch into a checkout:

$ cd inkscape
$ bzr bind lp:inkscape

Now work as in SVN:

 <do work>
$ bzr commit
 <error, someone else has changed things>
$ bzr update
 <check all is okay>
$ bzr commit


Differences from SVN

  • Commits will fail if your checkout is not up to date, even if there would be no conflicts.
  • The revision number is an attribute of the working tree, not of individual files. It is not possible to have different portions of the working tree at different revisions.
  • bzr commit file works like svn commit file && svn update project-root. After a successful partial commit, the entire tree's revision is increased by 1.
  • No special server is needed to publish a branch. You can push branches to anywhere, including simple FTP shares. In our scenario, Launchpad works like a central repository, but it's not required to publish everything there.
  • You create branches locally. To simulate creating a SVN-style branch on Launchpad, you need to create a local branch, push it, then bind it to the pushed location:
$ bzr branch trunk killer-feature
$ cd killer-feature
 <do work>
$ bzr push lp:~inkscape.dev/inkscape/killer-feature
$ bzr bind :push

Using a decentralized workflow

In this case you will be working locally until you are ready to publish your changes. The basic idea is to perform the work in a branch of the Inkscape codebase, since committing to a branch stores the changes locally in the branch itself. Then, to share the work with the rest of the Inkscape community, the changes in the branch are merged across to a checkout of the Inkscape repository. As the previous centralized workflow section describes, committing to a checkout sends the changes directly to the remote repository, making them part of the official Inkscape codebase.

NOTE: this workflow has been updated to avoid the "other people's commits become subrevisions of your commit" problem.

This will assume this directory layout:

inkscape
 +-trunk
 |  +-doc
 |  +-share
 |  +-src
 |  +-po
 |  +-...
 +-myproject
 +-some-other-branch

In this layout, "trunk" is the checkout used for uploading changes to the central Inkscape repository, while "myproject" and "some-other-branch" are local branches used for working on specific features.

Repository setup

To speed things up, it's good to create a local shared repository. This way revision histories will only be stored in one place, instead of in every branch, so local branching will be faster and the branches will take up less space.

Create a shared repository and enter it:

$ bzr init-repo inkscape
$ cd inkscape

Working locally

Get Inkscape's code

$ bzr branch lp:inkscape myproject

Now work:

$ cd myproject
  ... work work work ...
$ bzr commit -m "Some changes"
  ... more work work work ...
$ bzr commit -m "More changes"
  ... create new file ...
$ bzr add new-file.c
$ bzr commit -m "Added new file with kittens"

Advanced local features

To undo a commit:

$ bzr uncommit

This will leave your working tree in the state it was just before you wrote "bzr commit". This is useful for example if you forgot to add a file, and want to keep a clean revision history. This will not work on a trunk checkout.

Let's say you started from r770, made 200 local commits, but you decided that what you did since r954 is completely wrong. You want to go back to revision 954 and do it differently. Here's one way to do this. First branch locally to preserve your work (maybe later you'll find out there's some way to save it). Then uncommit everything up to r954 and revert.

$ bzr branch myproject myproject-dead-end
$ cd myproject
$ bzr uncommit -r 954
$ bzr revert

A different scenario: let's say that commit 1524 introduced a bug, but there were 50 other commits since then and you only want to revert the changes introduced by 1524.

$ bzr merge -r1524..1523

Sometimes a big change gets committed while you are working on a feature. If you want to check whether your code still works after the big change, merge from trunk.

$ bzr merge

In this case, you can omit where you are merging from, because the default is to merge from the branch you started from (the parent).

Publishing your work on Launchpad

To publish branches on Launchpad, you have to add an SSH key to your account. If you don't have one yet, generate it:

$ ssh-keygen
  ... follow instructions ...

Once you created the key, go to your Launchpad profile page, edit SSH keys and paste the contents of the key file (by default it's in ~/.ssh/id_rsa.pub or ~/.ssh/id_dsa.pub) into the window. You can now use the Launchpad integration features.

Login to Launchpad, if you didn't do it yet. You only need to do this once on each computer. You need to use your login name, not the display name.

$ bzr launchpad-login johnq

Publish your branch on Launchpad. If you push it under your username, only you will be able to modify it. If you have commit access and publish your branch under the username inkscape.dev, all Inkscape developers will be able to change it.

$ bzr push lp:~johnq/inkscape/myproject
$ bzr push lp:~inkscape.dev/inkscape/myproject

The push location will be saved. After more commits, you can simply write

$ bzr push

It's sometimes convenient to update the Launchpad copy after each commit. To save on typing, you can bind your working tree to the remote branch. This way every commit will be immediately published on the remote branch. Note that you won't be able to commit while offline.

$ bzr bind :push

Putting your work in the trunk

Once your new killer feature you made in a branch is ready, you need to merge your changes into a checkout of the trunk. If you don't have one, do (in the directory containing myproject):

 $ bzr checkout lp:inkscape trunk
 $ cd trunk

If you already have one on hand, make sure it's up to date:

 $ cd trunk
 $ bzr update

Now that you have a local checkout of the current trunk:

 $ bzr merge ../myproject
 $ bzr commit -m'added my feature'

Alternatively, if you don't have a checkout but a branch:

$ bzr merge ../myproject
$ bzr commit -m 'added my feature'
$ bzr push

Note that you need to do the above sequence on a branch that has not diverged from the trunk, otherwise it will fail, as the trunk is append-only.

WARNING: There is an alternative method that consists of merging trunk into your local branch, then pushing the result as the new trunk. Do not do this! It obfuscates the revision history, and in any case it will fail with Inkscape's trunk on Launchpad.

Working with patch files

If you don't have permission to commit to the trunk, you can bundle your branch's changes into a patch instead:

 $ bzr send -o mychanges.patch

To apply patches produced by the above command, just do this:

 $ bzr merge somechanges.patch

Local branching

Naturally, all this also works locally. For example, when you're in the inkscape directory, you can write bzr branch trunk export-dialog to create a new branch of the trunk called export-dialog, where you'll work only on improving the export dialog. Similarly, you can merge between local branches.

Conflict handling

Sometimes two people make conflicting changes to the same file. When this happens, you might encounter output like this:

 $ bzr update
 Enter passphrase for key '/home/johnq/.ssh/id_rsa': 
  M  src/painting-algorithm.cpp
  M  src/ui/widget/spinner.h
  M  src/ui/widget/spinner.cpp
  M  src/ui/widget/awesome-widget.cpp
 Text conflict in src/ui/widget/spinner.cpp
 1 conflict encountered.
 Updated to revision 10002 of branch [some URL]

After that, the directory src/ui/widget will contain four related files.

  • spinner.cpp: this will contain an unified view of the conflicts in the file. Conflicts will be marked with lines with multiple consecutive angle brackets.
  • spinner.cpp.BASE: latest common ancestor version of the file. In other words, both you and other people started from this version before conflicting changes were made.
  • spinner.cpp.THIS: the file with your changes, with conflicting changes by others removed.
  • spinner.cpp.OTHER: the file with other people's changes, with your conflicting changes removed.

To display the list of conflicts again, use the command:

$ bzr conflicts

To resolve the conflict, you need to modify the contents of the spinner.cpp. You can do this either by manually editing the file or by overwriting it with spinner.cpp.BASE, spinner.cpp.THIS or spinner.cpp.OTHER. Once you are done, you need to tell Bazaar about it:

$ bzr resolve src/ui/widget/spinner.cpp

The above command will delete the files spinner.cpp.BASE, spinner.cpp.THIS and tt>spinner.cpp.OTHER. Manually deleting those files has the same effect as executing bzr resolve. If you resolve all the conflicts at once, you can tell Bazaar to clean up everything:

$ bzr resolve --all

More information on the "Bazaar manual - Conflict handling".

Using a Git-style branches

Git stores many branches in one directory, and allows you to switch between them. This is also possible in Bazaar. One way is to use native Bazaar facilities, the other is to use the bzr-colo plugin. We'll cover the native way, since the plugin has good documentation.

First, create a no-working-trees shared repository. The repo directory can be hidden if you want.

$ bzr init-repo --no-trees .inkscape-repo

Fetch the trunk and any other branches you want into our repository. (You can also push your local branches.)

$ bzr branch lp:inkscape .inkscape-repo/trunk
$ bzr branch lp:inkscape/0.48.x .inkscape-repo/0.48.x
$ bzr push killer-feature .inkscape-repo/killer-feature

Create your working tree by making a lightweight checkout of a desired branch. The --lightweight parameter is imp[ortant, otherwise you can run into problems.

$ bzr checkout --lightweight .inkscape-repo/trunk inkscape
$ cd inkscape

If you have an existing checkout of the trunk, use the following command:

$ cd inkscape
$ bzr reconfigure --lightweight-checkout --bind-to ../.inkscape-repo/trunk

Now you can work in the inkscape directory like you would on a normal branch. If you want to switch to a different branch, use:

$ bzr switch ../.inkscape-repo/killer-feature

To create a new branch in the repository:

$ bzr switch -b ../.inkscape-repo/killer-feature-2

Best Practices for Inkscape Project

Registering Bugfixes

Launchpad will automatically mark a bug "Fix Available" (rather than "Fix Committed") once somebody commits using the flag --fixes, e.g. (if you fix those two bugs in one commit):

bzr commit --fixes lp:123456 --fixes lp:123457 -m 'patch description'

Then, bugs can be changed automatically from "Fix Available" to "Fix Released"

Read more: "Changing the state in Launchpad while committing in Bazaar"

Proper way of merging

To repeat, don't do something like:

$ bzr branch lp:inkscape myproject
... work ...
$ bzr commit
$ bzr merge               # NOOOO!!! We are doomed!
$ bzr push lp:inkscape

It would obfuscate the revision history: trunk commits that happened between the time you branched and the time you pushed would get grouped into one. Additionally, to prevent this obfuscation, Inkscape's trunk is set to append-only, so the above sequence of commands would fail. Do the merge the other way around:

$ bzr branch trunk myproject
$ cd myproject
... work ...
$ bzr commit
$ cd ../trunk
$ bzr merge ../myproject  # correct!
$ bzr commit

You'll need a trunk checkout, but the revision history will be much less confusing, and it's useful to have a trunk checkout anyway for minor fixes.

Fixing a bug in both trunk and a release branch

This will assume this directory layout:

inkscape
 +-trunk
 |  +-src
 |  +-...
 +-0.48.x
 |  +-src
 |  +-...

Fix the bug in trunk and commit it, let's say it will be revision 1234. Go to the release branch directory, e.g. 0.48.x, and write

$ bzr merge -r 1233..1234 ../trunk

The operation can take a while. Resolve any conflicts, fix any compilation failures, then commit to the release branch, or post the diff to a Launchpad bug report.

External links