Ubuntu Wiki

Dev Week -- Introduction to BZR - DavidFutcher -- Tue, Sep 2

(01:01:48 PM) bobbo: Hey! My name is David Futcher and today I'll be giving you a simple introduction to the Bazaar (BZR) Distributed Version Control system (dont worry if you dont know what that means, we'll get to that a bit later on).
(01:02:05 PM) bobbo: I like to answer questions, so, if you have any, please do not hesitate to ask. Prefix your question with QUESTION: and ask it in #ubuntu-classroom-chat.
(01:02:05 PM) bobbo: I have never done a UDW session before, so this session may be quite short or even run over, but we will cross that bridge when we come to it. If I am going too fast at any point, please shout and #-chat and I'll slow down :)
(01:02:28 PM) bobbo: So who is all here? Raise your hand in #-chat so I can see it!
(01:02:47 PM) sebner: \o/
(01:03:06 PM) pdragon: o/
(01:03:12 PM) bobbo: wahey, we have some people!
(01:03:13 PM) ***palango raises his hand
(01:03:19 PM) bobbo: Before we get started we need to install some packages. Run sudo apt-get install bzr bzrtools to make sure you have everything we will need. It would also be handy if you have a Launchpad account (I guess most of you do), though its not absolutely necessary, but you might have to skip out some of the session later on.
(01:03:48 PM) charliecb left the room (quit: Read error: 104 (Connection reset by peer)).
(01:03:52 PM) bobbo: shout when you have all this installed and we can get started :)
(01:04:45 PM) bobbo: Awesome, everyone seems to be ready, lets get started!
(01:05:00 PM) bobbo: ## What is BZR?
(01:05:00 PM) bobbo: (This section is a bit heavy on reading, but we will get to some practical examples soon)
(01:05:20 PM) bobbo: azaar is a tool for helping people collaborate on open-source software. It tracks the changes that you and other people make to a group of files - such as software source code - to give you snapshots of each stage of their evolution.
(01:05:49 PM) bobbo: Using that information, Bazaar can effortlessly merge your work with other people's.
(01:06:03 PM) bobbo: Tools like Bazaar are called version control systems (VCS) and have long been popular with software developers.
(01:06:27 PM) bobbo: Bazaar's ease of use, flexibility and simple setup make it ideal not only for software developers but also for other groups who work together on files and documents, such as technical writers, web designers and translators. (I used Bzr when writing this session)
(01:07:01 PM) bobbo: Many traditional VCS tools require a central server which provides the change history or repository for a tree of files.
(01:07:17 PM) bobbo: To work on the files, users need to connect to the server and checkout the files. This gives them a directory or working tree in which a person can make changes.
(01:07:38 PM) bobbo: To record or commit these changes, the user needs access to the central server and they need to ensure they have merged their work with the latest version stored before trying to commit. This approach is known as the centralized model and its not too great.
(01:08:06 PM) bobbo: The centralized model has proven useful over time but it can have quite a few drawbacks. It makes it harder for new developer to come to the project and make more than a few small patches, while with Bzr, a developer can easily create a branch that adds large new features or massive code changes.
(01:08:31 PM) bobbo: Distributed VCS tools (like bzr) let users and teams have multiple repositories rather than just a single central one. In Bazaar's case, the history is normally kept in the same place as the code that is being version controlled.
(01:08:52 PM) bobbo: This allows the user to commit their changes whenever it makes sense, even when offline. Network access is only required when publishing changes or when accessing changes in another location.
(01:08:57 PM) bobbo: Everyone with me so far?
(01:09:11 PM) dholbach left the room (quit: "Ex-Chat").
(01:09:16 PM) palango: yes
(01:09:21 PM) takdir: yup
(01:09:25 PM) pdragon: yep
(01:09:29 PM) Tindor: yep
(01:09:32 PM) swingnjazz: yes
(01:09:34 PM) bobbo: great!
(01:09:39 PM) jpds: ANSWER: Yep.
(01:09:40 PM) chienchouchen: yes
(01:09:45 PM) bobbo: Thats the end of the boring reading stuff, now onto some examples
(01:10:01 PM) bobbo: OK, so now you what what BZR is, and what it allows us to do, lets try it out. We are going to create a branch of GNU Hello. We need to grab the programs tarball and extract it:
(01:10:10 PM) bobbo: Open up a terminal and run:
(01:10:16 PM) bobbo:     wget http://bobbo.me.uk/ubuntu/udw/hello-2.3.tar.gz
(01:10:25 PM) bobbo:     tar -xvf hello-2.3.tar.gz
(01:10:31 PM) bobbo:     cd hello-2.3
(01:10:49 PM) bobbo: QUESTION: What are the differences between bzr and git?
(01:11:21 PM) bobbo: nemphis: I am not too sure (I have never used Git), but reading http://bazaar-vcs.org/BzrVsGit should tell you all you need to know :)
(01:11:56 PM) bobbo: Running 'ls' in your newly extracted hello-2.3 dir should show you the whole source tree for GNU Hello
(01:12:10 PM) bobbo: now we need to tell bzr to look after this source for us
(01:12:24 PM) bobbo:     bzr init
(01:12:39 PM) bobbo: (everything indented with 4 spaces should be run in a terminal :)
(01:12:53 PM) bobbo: <okar_> QUESTION: what does ubuntu/cannonical use bazaar for?
(01:13:11 PM) bobbo: okar_: Ubuntu/Canonical use it for quite a few things
(01:13:26 PM) bobbo: mainly just for storing source code to applications we maintain
(01:13:45 PM) bobbo: but it is also used for storing documentation and for application packaging for the MOTU team
(01:14:52 PM) bobbo: bzr init will create all the files and directories that bzr needs to be able to add revisions in ./.bzr. You normally wont need to touch anything in that directory, but its good to know it is there so you dont accidentally hose it and lose all your revision history, which isnt too awesome.
(01:15:48 PM) arkara is now known as wantilles
(01:15:59 PM) bobbo: OK, now we have told Bzr to setup revision control in the directory, we need to tell it where all out files are:
(01:16:03 PM) wantilles is now known as arkara
(01:16:08 PM) bobbo:     bzr add
(01:16:31 PM) bobbo: This should recurse through all the directories and add all the files it can find to bzr.
(01:16:46 PM) bobbo: You will need to do this whenever you add a file to your source code (or whatever else you are making).
(01:17:53 PM) bobbo: Now bzr knows where your files are, we are ready to make our first "commit"
(01:18:07 PM) bobbo: This basically takes a 'snapshot' or 'version' (hence version control system) of the current code:
(01:18:25 PM) bobbo:     bzr commit -m "Initial commit of GNU Hello"
(01:18:56 PM) bobbo: The -m flag supplies a little message that you should use to explain what you have changed in this revision. You will see a bit more about that in a second.
(01:20:14 PM) bobbo: Now we are going to make a little edit to the GNU Hello source.
(01:20:26 PM) bobbo:     cd src
(01:20:26 PM) bobbo:     sed -i 's/world/universe/g' hello.c
(01:20:26 PM) bobbo:     cd ..
(01:21:19 PM) bobbo: We can now use bzr to generate a diff of the changes we just made (note: we dont need to do this all the time, just generating a diff is really useful):
(01:21:28 PM) bobbo:     bzr diff
(01:21:58 PM) bobbo: This is handy for creating a patch in order to fix a bug. Just pull the branch down, make the changes and attach the output of bzr diff to the bug.
(01:22:36 PM) bobbo: Oli``: QUESTIONS: Do bzr commands always have to be in the same dir as you ran the init? Or can you run them from child dirs?
(01:22:51 PM) bobbo: Oli``: They can be run from any child directory :)
(01:23:00 PM) Oli``: Superawesome
(01:23:27 PM) bobbo: Now we can commit our changes to the branch. We will use the -m flag to describe what we have done to the code: "Replace 'world' with 'universe' in hello.c"
(01:23:34 PM) bobbo:     bzr commit -m "Replace 'world' with 'universe' in hello.c"
(01:25:39 PM) bobbo: Now we can look at our branches history:
(01:25:42 PM) bobbo:     bzr log
(01:26:30 PM) bobbo: Each time you commit to a branch an entry is added to the log. This is handy so you can check back and see where and when you might have introduced a bug and what you changed to introduce it. This is obviously much easier than blindly hunting for a way to fix a bug.
(01:27:01 PM) bobbo: Everyone ready to move on?
(01:27:10 PM) pdragon: i am
(01:27:22 PM) Tindor: me too
(01:27:24 PM) palango: yes
(01:27:32 PM) bobbo: ## Launchpad Integration
(01:27:59 PM) bobbo: Bzr integrates with Launchpad.net quite easily (both Bzr and Launchpad are developed or at least sponsored by Canonical). Launchpad provides free code hosting for bazaar branches, which I am going to show you just now.
(01:28:43 PM) bobbo: This bit will require you to have your LP account setup correctly with SSH keys, which can be fiddly, but I'll try to help you if you get any problems :)
(01:29:04 PM) bobbo: Jump onto Launchpad.net and log into your account.
(01:31:33 PM) bobbo: Now you should hit the "Code" tab, which will take you to a page showing all the branches that you have registered before or are watching etc. (If you havent used Launchpad code hosting at all before, this page will be pretty empty).
(01:32:27 PM) bobbo: Hit the "Register Branch" button in the top right corner and it should take you to a form where we can setup hosting for a bzr branch.
(01:32:53 PM) bobbo: You can skip the owners box as this branch is just for demonstration purposes, but in the future you can use this to register branches under team names etc. (Useful for when you need to give more than one person access to branch, you setup a team, get your fellow devs to join and they will automatically be able to push to branches hosted under that team name).
(01:33:41 PM) bobbo: We dont need to give a project name (Launchpad puts any branch that doesnt belong to a project in a pseudo-project called '+junk'. See the branch location in bold at the very top of the form).
(01:34:31 PM) bobbo: <tuxmaniac> QUESTION: not really a question. But bzr seems to have svn import facility. How reliable is this? does it import all change histories and every other detail ?
(01:35:04 PM) bobbo: I am not completely sure (I have never used SVN, jumped straight in with bzr), but http://bazaar-vcs.org/BzrForeignBranches/Subversion#limitations should tell you any problems you will have
(01:35:13 PM) bobbo: The name is just a short name for the branch, so in this case we could use something like 'gnu-hello' or 'bzr-example'.
(01:35:15 PM) tuxmaniac: thanks bobbo
(01:35:47 PM) bobbo: For branch type we want "Hosted", so that Launchpad does all the hosting for us (we dont need to setup our own servers to host the code, though this is perfectly possible and very handy if you are using Bzr at work, where you can have a server sitting, controlling your version control).
(01:36:33 PM) bobbo: For title put something like "GNU Hello Branch to Demonstrate BZR's Awesomeness" and set the description to "UDW Demonstration branch to show how to use BZR".
(01:36:56 PM) bobbo: Check it all looks ok and hit submit. We should now be on a summary page for your branch.
(01:37:05 PM) bobbo: shout in #-chat when you are there!
(01:37:54 PM) bobbo: In the right hand bar it will show you who owns the branch (in this case it is you) and who subscribes to the branch (it is possible to subscribe to a branch, so you get emailed everytime someone pushes some new revisions).
(01:38:36 PM) bobbo: On the top it has the branch name and description you specified, but the really useful part of this page for us is the bit in bold underneath the description. The bzr command next to "Update this branch" (which should look something like "bzr push lp:~bobbo/+junk/bzr-example". This command can just be copied and pasted into a terminal and should upload all your new changes to the branch.
(01:39:28 PM) bobbo: but dont paste it in just yet!
(01:39:41 PM) bobbo: first of all we need to tell bzr we will be working with Launchpad
(01:40:00 PM) bobbo:     bzr launchpad-login
(01:40:17 PM) bobbo: sorry:
(01:40:25 PM) bobbo:     bzr launchpad-login <your_lp_id>
(01:41:05 PM) bobbo: *now* run the command Launchpad just generated for you
(01:41:56 PM) bobbo:  This should ask you for your Launchpad SSH key password and then upload your branch to launchpad.
(01:43:06 PM) bobbo: sorry!
(01:43:31 PM) bobbo: we need to push with the --use-existing-dir flag because this is the first push we are doing of this branch
(01:43:46 PM) bobbo: bzr push <location_lp_gave_you> --use-existing-dir
(01:44:06 PM) bobbo: tuxmaniac> QUESTION: Is it because no project name was given and everybody is using the same branch or some such?
(01:44:34 PM) bobbo: nope, I dont think so, Launchpad just has hissy fits if you dont do things the way it wants to :P
(01:45:18 PM) bobbo: Right everyone managed to upload their branch?
(01:46:46 PM) pdragon: worked for me
(01:47:02 PM) bobbo: Great, seems to have worked for most people
(01:47:20 PM) bobbo: Ok now to check on your Launchpad hosted branch. Refresh the page in your browser (or surf back to it if you closed the tab/window).
(01:48:07 PM) bobbo: <swingnjazz> What is meant by  <your_lp_id> in the bzr launchpad-login?
(01:48:36 PM) bobbo: swingnjazz: Just your normal launchpad username
(01:49:26 PM) bobbo: Has everyone managed to get that to work?
(01:50:08 PM) bobbo: Success everybody. Well done!
(01:50:52 PM) bobbo: We have about ten minutes left, I was going to talk about the concept of branching and merging, but if I start now we will probably run out of time...
(01:51:26 PM) bobbo: <mok0> QUESTION: how would you go about maintainiing a package in bzr?
(01:52:06 PM) bobbo: mok0: I havent personally done it yet, but james_w (Resident Ubuntu BZR Guru) is hosting a session on Thursday that will cover exactly that
(01:52:18 PM) mok0: Cool
(01:52:36 PM) bobbo: Anyone that is interested in packaging with bzr, I would highly recommend you go along to that
(01:53:32 PM) bobbo: Correction: I messed up, James_w's session is on Wednesday
(01:53:46 PM) bobbo: <ktenney> QUESTION at one time I had the branch revision # in my prompt, how is that done?
(01:53:49 PM) mok0: ... tomorrow
(01:54:08 PM) bobbo: you can view the current revision number by running "bzr revno"
(01:54:28 PM) bobbo: <tacone> QUESTION: how can I plug another abbreviation like lp: in bzr ? like work: or dev: or..
(01:54:58 PM) bobbo: I think this is all handled from within Bzr's codebase itself
(01:55:22 PM) bobbo: but BZR is highly modular, so it probably wouldnt be impossible to plug in other prefixes
(01:56:10 PM) bobbo: Has anyone got any more questions?
(01:57:23 PM) tuxmaniac: bobbo: you missed mine
(01:57:45 PM) bobbo: tuxmaniac: sorry!
(01:57:47 PM) bobbo: <tuxmaniac> question: what if i want to use a hosting service other than LP? how do I indicate that to bzr. (like we do bzr launchpad-login <userid>)
(01:58:56 PM) bobbo: Bzr servers can be setup fairly easily, but of course (as I said above) you will lose out on being able to use the lp: quick prefixes
(01:59:41 PM) bobbo: so instead of bzr push lp:name/project/branch it would be "bzr push bzr+ssh://server/branch_location" or something similar
(01:59:57 PM) bobbo: ktenney> QUESTION can you run bzr commands from outside the checkout tree?
(02:00:24 PM) superm1: i think time is up on the last talk, bobbo could you wrap up so I would be able to get started?
(02:00:24 PM) bobbo: No, you have to run bzr commands from within the directory you ran 'bzr init' in, or any of its child directories
(02:00:34 PM) bobbo: superm1: sorry!
(02:00:45 PM) bobbo: OK, I'll be happy to answer anymore questions in /msg