Difference between revisions of "Working with Bazaar"

From Inkscape Wiki
Jump to navigation Jump to search
Line 28: Line 28:
 
Then fetch Inkscape's trunk
 
Then fetch Inkscape's trunk
 
  $ bzr branch lp:inkscape
 
  $ bzr branch lp:inkscape
 
==Using a decentralized workflow==
 
 
In this case you will be working locally until you are ready to publish your changes. This is the way git works by default.
 
 
'''NOTE:''' this workflow has been updated to avoid the "other people's commits become subrevisions of your commit" problem.
 
 
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
 
 
Now, 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'
 
 
 
==Using a centralized (SVN-like) workflow==
 
==Using a centralized (SVN-like) workflow==
  
Line 107: Line 76:
 
-->
 
-->
  
==Using branches==
+
==Using a decentralized workflow==
 +
 
 +
In this case you will be working locally until you are ready to publish your changes.
 +
 
 +
'''NOTE:''' this workflow has been updated to avoid the "other people's commits become subrevisions of your commit" problem.
 +
 
 
This will asumme this directory layout:
 
This will asumme this directory layout:
 
  inkscape
 
  inkscape
Line 116: Line 90:
 
   |  +-po
 
   |  +-po
 
   |  +-...
 
   |  +-...
   +-my-branch
+
   +-myproject
 
   +-some-other-branch
 
   +-some-other-branch
  
 
===Repository setup===
 
===Repository setup===
If you are working on several things at once, it's better to use one branch per feature. Here is how to work with branches.
 
  
* Create a shared repository for your branches. This brings significant space savings if you have several branches, but is not mandatory: <tt>bzr init-repo --rich-root inkscape</tt>. This will create the directory <tt>inkscape</tt>, which will contain a shared repository used by all branches within it, in the rich root format. This is the format currently used by our Launchpad repository - if you choose another format, you might not be able to push your branches to Launchpad. Enter the directory just created: <tt>cd inkscape</tt>
+
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 new branch: <tt>bzr branch lp:inkscape my-branch</tt>. This will retrieve the main branch of Inkscape and put it in the subdirectory <tt>my-branch</tt>.
 
* Make changes. Commit them locally using <tt>bzr commit</tt>. Note that this doesn't touch the trunk on Launchpad; you are only committing to your local repository.
 
* If somebody else modified the trunk, resync with it: <tt>bzr merge</tt> (merging will automatically use the parent branch if none is specified)
 
  
===Publishing branches on Launchpad===
+
Create a shared repository and enter it:
To publish branches on Launchpad, you have to add an SSH key to your account. You can generate a key using the program <tt>ssh-keygen</tt>.
+
$ bzr init-repo --rich-root inkscape
 +
$ cd inkscape
  
When you added a key to your account, you can now use the Launchpad integration features.
+
===Working locally===
  
* First you have to log in: <tt>bzr launchpad-login ''launchpad-username''</tt>. You need to use your username, not your display name.
+
Get Inkscape's code
* Publish your branch on Launchpad: <tt>bzr push lp:~''launchpad-username''/inkscape/my-branch</tt>. Of course if you're working with a different project, substitute <tt>inkscape</tt> with its Launchpad name.
+
$ bzr branch lp:inkscape myproject
* The push location will be saved. To update the branch on Launchpad, write <tt>bzr push</tt> after your commits.
 
* If you want to always commit directly to the remote branch on Launchpad, write <tt>bzr bind lp:~''launchpad-username''/inkscape/my-branch</tt> after the initial push. This will convert your local branch into a checkout of the remote branch. Note that you won't be able to commit offline.
 
  
===Merging branches into trunk===
+
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. Avoid uncommitting while working 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.
 +
$ bzr branch myproject myproject-dead-end
 +
$ cd myproject
 +
$ bzr uncommit -r 954
 +
$ bzr revert
 +
 
 +
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 <tt>~/.ssh/id_rsa</tt> or <tt>~/.ssh/id_dsa</tt>) 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.
 +
$ bzr push lp:~johnq/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 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
  
Way A: commit to a checkout of the trunk. This requires a trunk checkout, but for some people is more logical.
+
If you already have one on hand, make sure it's up to date:
 +
  $ cd trunk
 +
  $ bzr update
  
* Navigate to a checkout of the trunk.
+
Now that you have a local checkout of the current trunk:
* Execute <tt>bzr merge ''branch-url''</tt>. This will modify the files to receive the changes from the specified branch but will not modify the trunk.
+
  $ bzr merge ../myproject
* After verifying the changes (e.g. compile the program and see whether it doesn't crash on startup), execute <tt>bzr commit</tt> to apply the changes from the merge to the trunk.
+
  $ bzr commit -m'added my feature'
  
<strike>Way B: merge from trunk, then push. It doesn't require a trunk checkout, but it may be less obvious what is happening.</strike> Never use this method! It will change the numbering of revisions on the trunk.
+
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.
<!--
 
* Navigate to the branch you want to merge.
 
* Execute <tt>bzr merge ''trunk-location''</tt>, where ''trunk-location'' might be your local trunk checkout or <tt>lp:inkscape</tt>
 
* Verify the changes, then execute <tt>bzr commit</tt>.
 
* Push to trunk: <tt>bzr push lp:inkscape</tt>
 
-->
 
  
 
===Local branching===
 
===Local branching===
Line 166: Line 182:
  
 
[http://doc.bazaar-vcs.org/bzr.dev/en/tutorials/using_bazaar_with_launchpad.html#changing-the-state-in-launchpad-while-committing-in-bazaar Read more: "Changing the state in Launchpad while committing in Bazaar"]
 
[http://doc.bazaar-vcs.org/bzr.dev/en/tutorials/using_bazaar_with_launchpad.html#changing-the-state-in-launchpad-while-committing-in-bazaar Read more: "Changing the state in Launchpad while committing in Bazaar"]
 +
 +
To repeat, NEVER do something like:
 +
$ bzr branch lp:inkscape myproject
 +
... work ...
 +
$ bzr commit
 +
$ bzr merge              # NOO!!!
 +
$ 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:
 +
$ bzr branch lp:inkscape myproject
 +
$ cd myproject
 +
... work ...
 +
$ bzr commit
 +
$ bzr checkout lp:inkscape ../trunk
 +
$ cd ../trunk
 +
$ bzr merge ../myproject
 +
$ bzr commit
 +
 +
It's slightly more work, but the revision history is much less confusing, and it's useful to have a trunk checkout anyway.
  
 
==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 00:24, 29 December 2009

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
  • 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, they take roughly O(size of changes).
  • Bind is the process of converting a non-diverged local branch into a checkout.
  • 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 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 branch 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, rather than a branch:

$ 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 BZR branch

Get Inkscape's code the regular bzr way:

$ 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.

Using a decentralized workflow

In this case you will be working locally until you are ready to publish your changes.

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

This will asumme this directory layout:

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

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 --rich-root 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. Avoid uncommitting while working 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.

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

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 or ~/.ssh/id_dsa) 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.

$ bzr push lp:~johnq/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 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'

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.

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.

Best Practicals 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"

To repeat, NEVER do something like:

$ bzr branch lp:inkscape myproject
... work ...
$ bzr commit
$ bzr merge               # NOO!!!
$ 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:

$ bzr branch lp:inkscape myproject
$ cd myproject
... work ...
$ bzr commit
$ bzr checkout lp:inkscape ../trunk
$ cd ../trunk
$ bzr merge ../myproject
$ bzr commit

It's slightly more work, but the revision history is much less confusing, and it's useful to have a trunk checkout anyway.

External links