Ubuntu Wiki

Ubuntu Open Week - Bazaar: Beyond The Basics - David Futcher - Mon, Nov 3rd, 2008

(03:59:29 PM) jcastro: ok, moving on with bazaar still, but now into more advanced topics
(03:59:35 PM) jcastro: this is the last session of the day
(03:59:44 PM) jcastro: so basically we can go until bobbo passes out.
(03:59:53 PM) jcastro: take it away bobbo!
(04:00:02 PM) bobbo: thanks jcastro :D
(04:00:10 PM) bobbo: right hey everyone!
(04:00:29 PM) emmajane: I'll stick around in -chat as well if people still have beginner questions. :)
(04:00:29 PM) bobbo: Now Emma Jane has covered the basics of using Bazaar, I'm going to go into a little more detail and show you some of the more
(04:00:31 PM) bobbo: complex things you can do with Bzr, including branching, merging and tagging.
(04:00:52 PM) bobbo: so everyone ready to get started?
(04:01:33 PM) bobbo: right, before we get properly started this session is called "Beyond The basics" but we wont go into the hardcore details that will bore you all to death
(04:01:57 PM) bobbo: instead i'll show you some cool practical stuff, that will hopefully help you in using bzr
(04:02:23 PM) bobbo: if you havent done so already plese run "sudo apt-get install bzr bzr-tools" to get bzr and bzr-tools installed
(04:03:05 PM) LarstiQ: Shouldn't that be bzrtools without the dash?
(04:03:07 PM) bobbo: shout when its installed and you are ready to go
(04:03:19 PM) bobbo: LarstiQ: probably!
(04:03:54 PM) bobbo: ok onto section 1 : Branching and Merging
(04:04:07 PM) bobbo: Branching & Merging are two of the core concepts in Bzr.
(04:04:20 PM) bobbo: A branch is "an ordered set of revisions that describe the history of a set of files". A bit of an abstract and confusing concept if you have never worked with bzr before, but it will all become clear after using it for a little.
(04:05:05 PM) bobbo: a branch can also be described as "a line of development for a project"
(04:05:26 PM) bobbo: A merge is simply taking code from one branch and joining (merging) it with another. Here is an example workflow to help you understand:
(04:05:38 PM) bobbo:   1 - Project foobar is a little command line application with a "trunk" bzr branch
(04:05:40 PM) bobbo:    2 - A developer decides it needs a gui, so creates a new branch, based on the old "trunk" branch
(04:05:41 PM) bobbo:    3 - The GUI developer works on the GUI until it is ready to go into the main project code
(04:05:43 PM) bobbo:    4 - Another developer checks the code, decides it is ok and merges it into the trunk. So now the trunk has:
(04:05:44 PM) bobbo:             - All the original code (from before the GUI work started)
(04:05:46 PM) bobbo:             - All the code from the GUI branch
(04:05:47 PM) bobbo:             - Any changes that have been made in trunk since the GUI branch was created (more on this in a second)
(04:06:33 PM) bobbo: If that (not so awesome) description flies right over your head, heres a shiny diagram i made earlier (ignore the big black things, I have no idea what Inkscape was up to earlier): http://bobbo.me.uk/ubuntu/openweek/bzr-branching-merging.svg
(04:07:18 PM) bobbo: shout if you understand and want to move on, or dont get it and want some more explanation :D
(04:08:15 PM) bobbo: right so lets have do a practical example of this
(04:08:29 PM) bobbo: We will use Terminator as an example because it has quite a few branches that implement new features (and it is a really cool project). First we need to grab Terminator's trunk branch:
(04:08:42 PM) bobbo:     bzr branch lp:terminator
(04:08:43 PM) bobbo:     cd terminator
(04:09:35 PM) bobbo: Now we have the "trunk" branch of Terminator. This is where the core authors of the project put most of their bugfixes etc, but most large feature changes are done outside of trunk, in their own special branches
(04:10:07 PM) bobbo: This lets developers make large changes to the code, without breaking the main project code
(04:11:07 PM) bobbo:  <james_w> if you grabbed a checkout of terminator in the last session then "cd terminator" and run "bzr unbind" and you will be in the same state as from bobbo's talk <-- Do that :P
(04:11:33 PM) bobbo: Right everyone in a (working) Terminator trunk directory?
(04:11:40 PM) meastp: How can you merge, or rather copy changes between trunk and, say, a stable serie?
(04:12:08 PM) bobbo: OK, so now we are going to merge in another branch
(04:12:51 PM) bobbo: this is based on Terminator trunk, but instead of implementing all the bugfixes etc going into the main project, this branches author has decided to implement a shiny new feature
(04:13:35 PM) bobbo: So now we run "bzr merge lp:~richiek/terminator/altctrlwin-num_tab_change" to try and merge the new branch into our copy of trunk
(04:14:05 PM) bobbo: Once this has completed it should give you a message like:
(04:14:07 PM) bobbo:    1 conflicts encountered.
(04:14:08 PM) bobbo: This means that bzr tried to automatically merge the two branches together, but since the new author branched terminators trunk, a change has been made (in trunk) that conflicts with the new code (in the branch).
(04:14:25 PM) bobbo: (I could have worded that a little better, everyone understanding?)
(04:15:23 PM) bobbo: So lets go fix the conflict. Run:
(04:15:25 PM) bobbo:     bzr conflicts
(04:15:26 PM) bobbo: This will show you where all the conflicts in the source tree are. It should say "terminatorlib/terminator.py", so lets edit it and find where the conflict is.
(04:15:28 PM) bobbo:     gedit terminatorlib/terminator.py
(04:15:29 PM) bobbo: The conflict can be found in between these markers (around line 865):
(04:15:31 PM) bobbo:     <<<<<<< TREE
(04:15:32 PM) bobbo:     =======
(04:15:34 PM) bobbo:     >>>>>>> MERGE-SOURCE
(04:15:35 PM) bobbo:     
(04:15:37 PM) bobbo: everything above the ='s and below <<<<<<< TREE is what is currently in the trunk and everything below the ='s and above >>>>>>> MERGE-SOURCE is what is currently in the branch you are merging
(04:16:18 PM) bobbo: I wont show you completely how to manually merge these, because that requires knowledge of the application and libraries etc. and each merge is different so there is no real need,
(04:16:55 PM) bobbo: But basically you have to work out a way for those two piece of code to co-exist, in a way that doesnt cause the application to explode, but also implement the new feature or bugfix in the branch
(04:17:37 PM) bobbo: So for educational purposes, lets just pretend that we have managed to fix the conflict and are now ready to commit our merge
(04:17:58 PM) bobbo: First off we need to tell bazaar we have actuall fixed the conflict, otherwise it wont let us commit the merge
(04:18:20 PM) bobbo: run "bzr resolve terminatorlib/terminator.py" to tell bzr that everything is fixed.
(04:19:01 PM) bobbo: we would need to repeat the above process for every file that has merge conflicts in it, so merging big patches, after big patches have been applied in trunk can be a little messy and time consuming
(04:19:52 PM) bobbo: finally we need to commit the merge to our copy of trunk: bzr commit -m "Merged in lp:~richiek/terminator/altctrlwin-num_tab_change"
(04:20:21 PM) bobbo: congratulations! You just completed your first bzr merge!
(04:20:35 PM) bobbo: anyone need any time to catch up?
(04:21:07 PM) bobbo: right, onto section 2: Tagging!
(04:21:26 PM) bobbo: QUESTION:how can bazaar tell that two sections of code are in conflict ( and will actually break the software) ?
(04:22:49 PM) bobbo: x_dimitri: I am not sure how it works in the internals of bazaar, but it must check whether the branch and the trunk have changed the same pieces of code
(04:23:26 PM) LarstiQ: bobbo: could you repeat x_dimitri's question?
(04:23:29 PM) bobbo: x_dimitri: it would probably be a good idea to ask a developer about how it works inside bazaar, because it must be pretty complex (as in I dont know, sorry)
(04:23:39 PM) bobbo: LarstiQ:  QUESTION:how can bazaar tell that two sections of code are in conflict ( and will actually break the software) ?
(04:23:58 PM) bobbo: meastp: ask away, though I cant be sure i'll know the answer :D
(04:24:53 PM) bobbo: OK, section 2: Tagging!
(04:25:12 PM) bobbo: Bazaar has a useful feature, called tagging, which lets you give a commit to a branch a sensible, human understandable name like "0.2.0-release" or "fixes-bug-375838". This is can be used for tagging releases, release candidates, or whenever you are going to need to easily find a revision number.
(04:25:53 PM) bobbo: i think svn and other "traditional" VCS's have tagging of some sort too, but I have never had the pleasure of working with them, so wouldnt really know :)
(04:26:18 PM) bobbo: So lets try this out in our Terminator branch. You can add a tag to a branch very easily using "bzr tag":
(04:26:28 PM) bobbo:     bzr tag "test-tag"
(04:26:37 PM) bobbo: This will give the latest revision (the last one committed to the branch) the tag "test-tag".
(04:27:13 PM) bobbo: you can delete tags using:
(04:27:26 PM) bobbo:     bzr tag --delete test-tag
(04:27:52 PM) bobbo: To tag an already existing revision we can use:
(04:28:02 PM) bobbo:     bzr tag -r 123 "release-0.1a"
(04:28:17 PM) bobbo: This tags revision 123 with the tag "release-0.1a"
(04:29:06 PM) bobbo: <NetSKaVeN> QUESTION: can you delete any tag or only the last?
(04:29:23 PM) bobbo: You can delete any tag, but it wont delete the revision, just the tagging of that revision
(04:30:01 PM) bobbo: it is also possible to give a revision more than one tag
(04:30:15 PM) bobbo: <andresmujica> QUESTION: Is possible to list the existing tags? how?
(04:30:36 PM) bobbo: yes, running "bzr tags" gives you a full list of all the current tags in the branch
(04:31:07 PM) bobbo: <mbt> QUESTION:  Can you easily retrieve stable revision identifiers from bzr that are consistent between branches and merges?
(04:31:20 PM) bobbo: mbt: Sorry, I have never tried it, so I'm not sure
(04:31:47 PM) LarstiQ: mbt: yes, bzr revision ids are stable
(04:31:52 PM) bobbo: It is also possible to revert to a revision using its tag, for example:
(04:31:57 PM) LarstiQ: mbt: you can see them in log for example with bzr --show-ids log
(04:32:19 PM) LarstiQ: mbt: and use them with revid:, so bzr diff -r revid:<your revid here>
(04:32:22 PM) bobbo:     bzr revert -r tag:release-0.1a
(04:32:38 PM) bobbo: <meastp> Hi, I have recently added my project to lp, with bzr. Currently I have a trunk, and branches for features. But how should I manage releases? E.g if I branch trunk as 1.0 and add to the 1.0 series, how should I keep trunk and the 1.0 series' bugfixes synchronised (with bzr)?
(04:33:43 PM) bobbo: meastp: the way I do it (may not be the best or most efficient way but it works) is to have have the release-1.0 branched from trunk, put all bugfixes etc into trunk and then merge them into the release-1.0 branch (does that make sense?)
(04:34:19 PM) bobbo: The beauty of bazaar is that you can have release-1.0 specific code in the release branch, but also be able to pull in changes from trunk when they are needed
(04:34:54 PM) bobbo: meastp: does that answer your question?
(04:35:33 PM) bobbo: For even more on reading tagging in Bazaar check out http://bazaar-vcs.org/Specs/Tagging
(04:36:18 PM) bobbo: <Tonio__> QUESTION: I have made some uggly modifications and put my hown tag and then commit all that stuff and its ok. But I am not logged to the launchpad. So what does commit exactly ?
(04:36:32 PM) meastp: bobbo: yes, thanks... I'm a bit confused by this workflow. Will look at the link, thanks
(04:36:41 PM) bobbo: Commit in bzr works completely differently to committing in svn or cvs.
(04:37:06 PM) bobbo: IN bazaar, "commit" puts revisions into the local branch (which is sitting on your HD or pen drive)
(04:37:29 PM) bobbo: You need to "push" them onto launchpad (using bzr push) before they will show up there
(04:38:03 PM) bobbo: Tonio__: is that what you were looking for?
(04:38:38 PM) Tonio__: bobbo: Thanks it's clear for me (I am a SVN user)
(04:39:09 PM) bobbo: Tonio__: yeah, it is one of the biggest confusing things for svn users when they come to bzr, the same words meaning almost completely different things :D
(04:39:47 PM) bobbo: Right Section 3 : Extensibility and Modules
(04:40:15 PM) bobbo: On the best things about bazaar (IMO) is that it is very easily extensible.
(04:40:32 PM) bobbo: It is very simple to plug in your own functionalities to the system
(04:41:57 PM) bobbo: There are hundreds of plugins, ranging from useful little tools like creating diffstats (little "graphical" representations of a patch that at a glance tell you how much the patch is changing) to  big complex things like adding dbus or rsync support
(04:42:38 PM) bobbo: There are also several plugins that help you integrate with other version control systems
(04:43:20 PM) bobbo: including support for importing SVN branches into bzr, which is always very handy when you already have existing project infrastructure that you want to move over to bzr
(04:44:03 PM) bobbo: There is a huge big list of plugins on the bazaar website at http://bazaar-vcs.org/BzrPlugins
(04:45:00 PM) bobbo: Most of these will be installable via a setup.py file shipped in their source tar.gz, but if you dont fancy doing that, Debian/Ubuntu also has several (more important) bzr plugins packaged up and in the repositories
(04:45:07 PM) bobbo: You can see a list of these at http://packages.ubuntu.com/search?suite=default&section=all&arch=any&searchon=names&keywords=bzr-
(04:45:51 PM) bobbo: As with all software in the repos, you can just run "suo apt-get install bzr-rebase" and have rebasing support in bazaar
(04:46:37 PM) bobbo: Well thats pretty much all I planned for. Are the any questions?
(04:47:15 PM) bobbo: <biomass> QUESTION: What's rebasing ?
(04:47:44 PM) bobbo: Rebasing is the process of taking a branch and modifying the history so that it appears to start from a different point
(04:48:07 PM) bobbo: This can be useful to clean up the history before submitting your changes. The tree at the end of the process will be the same as if you had merged the other branch, but the history will be different.
(04:48:47 PM) bobbo: You can read more about it at http://bazaar-vcs.org/Rebase
(04:49:18 PM) bobbo: Anymore questions?
(04:49:47 PM) bobbo: nope? Looks like we can all get away early then!
(04:49:58 PM) bobbo: thanks for listening!
(04:50:07 PM) NetSKaVeN: great session bobbo