Revision 2 as of 2009-09-04 09:00:52

Clear message

Dev Week -- Being productive with bzr and LP code hosting - rockstar -- Thu Sep 3rd, 2009


   1 [20:05] <rockstar> Welcome to my session on Advanced Usage of Launchpad and Bazaar.
   2 [20:05] <rockstar> My name is Paul Hummer and I work on the Launchpad Code team.
   3 [20:05] <rockstar> To give you a good background on the format of this session, I need to share with you a pet peeve of mine.
   4 [20:05] <rockstar> I have made a few attempts to become a MOTU, but each time I look at the documentation, I'm presented with LOTS of choices.  This makes me feel like I'm reading one of those "Choose Your Own Adventure" games.
   5 [20:05] <rockstar> Having the choice is great, and LP and Bazaar workflows can be VERY dynamic.  However, today, I'm going to show you how _I_ do my work, answer any questions you might have, and hopefully prime you to be able to develop your own optimized workflow.
   6 [20:06] <rockstar> s/games/books
   7 [20:06] <mok0> heh
   8 [20:06] <rockstar> So, first things first: Configuring Bazaar
   9 [20:07] <rockstar> I'm assuming here that you're relatively familiar with the basics or Bazaar, and the basics of Launchpad.
  10 [20:08] <rockstar> You'll want to have your GPG and ssh keys set up, etc.
  11 [20:08] <rockstar> I'm also assuming that you have `bzr whoami` configured with an email address that LP knows about.
  12 [20:09] <rockstar> If it's wrong, those revisions will never be able to be fixed.  You'll have to create new revisions if you want the karma. (We get this question asked a lot)
  13 [20:09] <rockstar> Now, I like to keep my branch repositories and my working area separate, so when I set up to work on a new project, my process is something similar to this (in the context of a project called bzr-launchpadplus)
  14 [20:09] <rockstar> mkdir ~/Projects/repos/bzr-launchpadplus
  15 [20:09] <rockstar> bzr init-repo ~/Projects/repos/bzr-launchpadplus --no-trees
  16 [20:09] <rockstar> mkdir ~/Projects/bzr-launchpadplus
  17 [20:10] <mok0> rockstar: shall we repeat this?
  18 [20:10] <rockstar> Also, I'll stick in here that if you're not using bzr 2.0rc, you REALLY missing out.  The default formats are much better than earlier versions.
  19 [20:10] <rockstar> mok0, no, you don't have to, or you can follow along with another project.
  20 [20:11] <rockstar> Okay, now I have a basic shell to work off of.  I put the repository where all my branches will live inside of ~/Projects/repos/launchpadplus, and the corresponding workspace at ~/Projects/bzr-launchpadplus
  21 [20:11] <rockstar> No questions so far?
  22 [20:11] <rockstar> Now I need to teach Bazaar about this layout, so it knows to put branches in one place and trees in another.
  23 [20:12] <rockstar> I do this with the following lines in ~/.bazaar/locations.conf:
  24 [20:12] <rockstar> [~/Projects]
  25 [20:12] <rockstar> cbranch_target = /home/rockstar/Projects/repos
  26 [20:12] <rockstar> cbranch_target:policy = appendpath
  27 [20:12] <rockstar> mok0, you can find bzr 2.0 rc1 in the bzr team PPA
  28 [20:13] <rockstar> As LarstiQ pointed out (and I was getting on my way to pointing out), you'll need bzrtools.
  29 [20:13] <rockstar> Frankly, having bzr without bzrtools is just silly.  It provides a lot of convenience.
  30 [20:14] <rockstar> The lines above tell Bazaar that when I call `bzr cbranch` in my ~/Projects/bzr-launchpadplus it knows that it needs to put a branch in the corresponding repos folder, and then create a checkout in ~/Projects/bzr-launchpadplus/<name-of-folder-provided>
  31 [20:14] <rockstar> (I should add that I have cbranch aliased to cbranch --lightweight in my ~/.bazaar/bazaar.conf)
  32 [20:15] <rockstar> As a sidenote, your locations.conf should probably contain something like this:
  33 [20:15] <rockstar> [~/Projects/repos]
  34 [20:15] <rockstar> push_location = lp:~<username>
  35 [20:15] <rockstar> push_location:policy = appendpath
  36 [20:15] <rockstar> public_branch = lp:~<username>
  37 [20:15] <rockstar> public_branch:policy = appendpath
  38 [20:15] <rockstar> This means that you can just `bzr push` and not have to worry about where it's going (provided you named your repository folder the same as the lp-project).
  39 [20:16] <rockstar> This seems like a lot of boilerplate, but remember this is "advanced" stuff.  I've spent almost two years of everyday use tweaking this.
  40 [20:17] <rockstar> Alright, so now let's get the bzr-launchpadplus working tree into our working area.  We do this with:
  41 [20:17] <rockstar> cd ~/Projects/bzr-launchpadplus
  42 [20:17] <rockstar> bzr cbranch lp:bzr-launchpadplus
  43 [20:18] <rockstar> And now I have a working tree at ~/Projects/bzr-launchpadplus/bzr-launchpadplus and the corresponding branch at ~/Projects/repos/bzr-launchpadplus/bzr-launchpadplus
  44 [20:18] <rockstar> Alright, now let's get to hacking:
  45 [20:18] <rockstar> So bzr-launchpadplus is a curiousity created by Jono Lange to get more glue stuffs between Launchpad and Bazaar.  I merged my bzr-autoreview plugin into it, and will be adding some more features to it soon.
  46 [20:18] <rockstar> So let's create a branch from bzr-launchpadplus "trunk" and start hacking on something new.
  47 [20:19] <rockstar> cd ~/Projects/bzr-launchpadplus
  48 [20:19] <rockstar> bzr cbranch bzr-launchpadplus add-more-mojo
  49 [20:19] <rockstar> cd add-more-mojo
  50 [20:19] <rockstar> Now we have a branch that I've named "add-more-mojo"
  51 [20:20] <rockstar> QUESTION: rockstar, you have all your projects in one repo?
  52 [20:21] <rockstar> ANSWER: No, I have a repo for each project.  Bazaar 2.0 has the format issue worked out, but not everyone has upgraded, so rich-roots don't play well with others.
  53 [20:21] <rockstar> So, for instance, my launchpad repo is at ~/Projects/repos/launchpad and my entertainer repo is at ~/Projects/repos/entertainer
  54 [20:22] <rockstar> Alright, back to our hacking scenario.
  55 [20:22] <rockstar> If hacking takes more than a few hours, it's common courtesy to push up changes at a regular interval to let others know what's going on.  If it doesn't, you might not even need to push at all (more on that coming).
  56 [20:22] <rockstar> Okay, so we have some commits, we've been working for only two hours, and we're ready to get this code landed.
  57 [20:22] <rockstar> QUESTION: as far as i know, for each separate branch in bzr user should make separate folder. Does bazaar have some type of branches, when they keep in the same folder as the whole project (like in git, for example)?
  58 [20:23] <rockstar> ANSWER: TECHNICALLY, in my setup, it's possible to mimic the behavior of git/hg.  In fact, bzr-pipelines works that way.
  59 [20:24] <rockstar> However, it also complicates the issue, i.e. git pull and git push don't work the same way.
  60 [20:24] <rockstar> Okay, so in our scenario, we're ready to submit for review.
  61 [20:25] <rockstar> Let's add one line to ~/.bazaar/bazaar.conf
  62 [20:25] <rockstar> submit_to = merge@code.launchpad.net
  63 [20:25] <rockstar> This tells Bazaar that when you want to send a new patch, this is the default email to send it to (you can override this on a case-by-case basis).
  64 [20:25] <rockstar> Now, with my mojo branch as the current working directory, I can do `bzr send` and my mail client should open and prepopulate a message to merge@code.launchpad.net and add what Bazaar calls a "bundle" as an attachment.  A bundle basically has all the revision data for the revisions that would be merged with this branch.
  65 [20:26] <rockstar> Now, describe your change in the message and make sure the subject is correct.  I usually use `bzr send -m "<Subject line here>"` because I always forget otherwise.
  66 [20:26] <rockstar> If you'd like to request a specific reviewer, you can use the email interface to do so.  If you've used this interface for bugs, you'll be familiar with this. In a blank line, add a single space, and then "reviewer <lp-username"
  67 [20:27] <rockstar> For instance, if you wanted me to review your branch, you could do:
  68 [20:27] <rockstar>  reviewer rockstar
  69 [20:27] <rockstar> Now, whether or not you've requested a reviewer, you need to sign this email with your GPG key.  This confirms to LP that it really is you that is proposing the merge.
  70 [20:27] <rockstar> Send your email.
  71 [20:28] <rockstar> There were some versions of bzr that were a little funky about figuring out your mail client.  In that case, you'll want to specify it in ~/.bazaar/bazaar.cony
  72 [20:28] <rockstar> Er, ~/.bazaar/bazaar.conf
  73 [20:28] <rockstar> QUESTION: I don't get all this mail stuff. Why don't you just use LPs interface? Much easier IMHO
  74 [20:29] <rockstar> Well, because I actually don't find the LP interface to be easier.  It's getting there (that's what I currently do every day), but sending off emails is easy.  I can do it all from my editor.
  75 [20:30] <rockstar> Also, MANY (more than I would have thought) open source projects do their reviews via email.
  76 [20:30] <rockstar> QUESTION: do you need to manually gpg sign the email or would enabling gpg signing of commits via "create_signatures = always" in bazaar.conf be sufficient?
  77 [20:31] <rockstar> ANSWER: You do indeed need to sign the email.  When you sign your revisions, it's a verification on the revision, not an the message that you're writing to go along with your merge proposal.
  78 [20:31] <rockstar> There are a few things to note about the email you just sent.
  79 [20:32] <rockstar> Did you forget to push to Launchpad before you sent this proposal?  Don't worry!  Launchpad will create the branch for you!
  80 [20:32] <rockstar> Did you push, but then make some more changes and forget to push those?  Launchpad will also update the branch for you.
  81 [20:32] <rockstar> Now, let's switch over to the reviewer for a second.
  82 [20:32] <rockstar> You'll get an email with the patch attached to it.  Look it over, make your suggestions, etc.
  83 [20:33] <rockstar> Maybe you're fine with this branch.  You want to vote approve, and, if you're the only one who needs to approve, mark the proposal as Approved.
  84 [20:33] <rockstar> You can do this by email with the following commands:
  85 [20:33] <rockstar>  review approve
  86 [20:33] <rockstar>  merge approved
  87 [20:33] <rockstar> These commands are documented at https://help.launchpad.net/Code/Review
  88 [20:33] <rockstar> Also, this email needs to be GPG signed as well.
  89 [20:34] <rockstar> QUESTION: So, "merge@code.lp.net" does the same as a merge request?
  90 [20:34] <rockstar> ANSWER: Yes, the email to that address is processed like a merge request.
  91 [20:35] <rockstar> Okay, so let's move on to some more really fun stuff.
  92 [20:35] <rockstar> Since Launchpad now knows about my mojo branch (whether I pushed it, or LP made one based on my email), I can do `bzr lp-open` and it'll open the branch page in a browser for me.
  93 [20:35] <rockstar> When this feature was implemented in Bazaar, I thought, "That's silly." but I use it ALL THE TIME.  Seriously, it's amazing.
  94 [20:36] <rockstar> Once your code is reviewed, you need to get it landed.
  95 [20:36] <rockstar> This means you can set up something like PQM (be prepared to spend a few days on it), merge it manually (which sucks if you have a busy project), or, use Tarmac.
  96 [20:37] <rockstar> Tarmac is my project, is very young, but gets the job done.
  97 [20:38] <rockstar> Tarmac is a script that will go out to Launchpad, check for approved merge proposals against a project's development focus, and merge them.
  98 [20:39] <rockstar> It also has support for running tests on the merge, and not merging if the tests fail.  It has a plugin system that ships with plugins for notifying CIA and modifying commit messages to a given template.
  99 [20:39] <rockstar> I'd like to create one that will build a source package and send it to a PPA on post-commit.  If you'd like to help out with that (I'm not great at packaging), find me afterwards.
 100 [20:40] <rockstar> One plugin that has recently been developed by Aaron Bentley that I think is invaluable in bzr-pipes.  It allows me to lay a "pipeline" of branches that build one on top of another.
 101 [20:40] <rockstar> The benefit of this is that you can break your work up into smaller chunks and get them reviewed and landed that way.
 102 [20:40] <rockstar> There is nothing I hate more than a 2500 line diff I need to review.  Break it up into 5 500 line diffs and I'll be a little happier.
 103 [20:42] <rockstar> bzr-pipelines only works with this separated work area and repository set up that I have.  Let's say that, while the previous "mojo" branch is being reviewed, I'd like to still work on something that required code in the mojo branch.
 104 [20:43] <rockstar> All I'd need to do is `bzr add-pipe mojo-phase-deux` and it creates a new pipe, and changes me into it.
 105 [20:44] <rockstar> This goes back to what ia was asking about earlier.  The implementation of pipes basically creates a branch in the ~/Projects/repos/bzr-launchpadplus folder, and then makes my working tree match the branch.  So I haven't changed dirs, but I've changed branches.
 106 [20:44] <rockstar> I can see the whole pipeline by doing `bzr show-pipeline`
 107 [20:44] <rockstar> Now I hack on this new branch, and commit a few times.
 108 [20:45] <rockstar> QUESTION: I get this: bzr: ERROR: Can't find cbranch_target in locations.conf
 109 [20:45] <rockstar> ANSWER: Earlier in the session, I posted my config far cbranch_target that I put in locations.conf
 110 [20:45] <rockstar> s/far/for
 111 [20:46] <rockstar> <rockstar> [~/Projects]
 112 [20:46] <rockstar> <rockstar> cbranch_target = /home/rockstar/Projects/repos
 113 [20:46] <rockstar> <rockstar> cbranch_target:policy = appendpath
 114 [20:47] <rockstar> Alright, so I've been doing work in this second pipe.
 115 [20:47] <rockstar> But wait, the reviewer wants changes for my first mojo branch.  Not to worry.  I can switch back to that pipeline with `bzr switch-pipe add-more-mojo`
 116 [20:47] <rockstar> Then I make the changes and commit and push.
 117 [20:48] <rockstar> Then I need to pump the changes up the pipeline with `bzr pump` and all branches (or "pipes") get those changes.
 118 [20:48] <rockstar> Get it?  You "pump" changes up the "pipeline"?  abentley is so clever.
 119 [20:48] <rockstar> :)
 120 [20:50] <rockstar> A word to the wise: Make sure you don't have too many pipes in progress.  Think of them as plates spinning on small sticks, and you aren't a circus clown.  It won't be too long before you have a mess on your hands; I tried plate spinning as a child and ended up grounded for a very long time.  YMMV.
 121 [20:51] <rockstar> If you're going to use bzr-pipelines in your regular workflow (and I suggest you do), here are some aliases I use with pipes that you might want to add to your [ALIASES] section of ~/.bazaar/bazaar.conf
 122 [20:51] <rockstar> next = switch-pipe :next
 123 [20:51] <rockstar> prev = switch-pipe :prev
 124 [20:51] <rockstar> send-pipe = send -r branch::prev..
 125 [20:51] <rockstar> diff-pipe = diff -r branch::prev
 126 [20:51] <rockstar> pipes = show-pipeline
 127 [20:51] <rockstar> Now, instead of `bzr send` for pipes, I can use `bzr send-pipe` and it will generate the diff only for the changes specific to this pipe.
 128 [20:51] <rockstar> The same for diff-pipe.
 129 [20:52] <rockstar> (The LP Code team is currently strategizing on how to handle branches based on other branches that haven't landed yet.  No one wants to review code that's already been reviewed)
 130 [20:52] <rockstar> I didn't want to type out "show-pipeline" so I shortened it to "pipes".
 131 [20:53] <rockstar> Also, I never remember the names of my pipes, so I just use `bzr prev` and `bzr next` to navigate the pipeline.
 132 [20:54] <rockstar> ...and in closing, I'd like to share some of the aliases that I use in my workflow regularly.
 133 [20:54] <rockstar> [ALIASES]
 134 [20:54] <rockstar> cbranch = cbranch --lightweight
 135 [20:54] <rockstar> ci = commit --strict
 136 [20:54] <rockstar> sdiff = cdiff -r submit:
 137 [20:54] <rockstar> unpushed = missing --mine-only :push
 138 [20:54] <rockstar> st = status --short
 139 [20:55] <rockstar> As mentioned before, cbranch --lightweight creates lightweight checkouts.
 140 [20:55] <rockstar> `bzr ci` will not commit unless I've dealt with all the unknown files.  How many times have you forgotten to add a file to the branch, and then someone else can't run your branch because it's missing?
 141 [20:55] <rockstar> --strict on commit fixes that.
 142 [20:57] <rockstar> `bzr sdiff` generates a color diff of the changes against my submit branch.  cdiff is part of bzrtools.  If you don't want color (or are piping to less or something), use regular diff.
 143 [20:57] <rockstar> `bzr unpushed` will show me all the revisions I haven't pushed yet.  I don't use it often, but I always forget the syntax when I need it, so I just aliased it.
 144 [20:58] <rockstar> And `bzr st` is just because I'm too lazy to type out 'status'  :)
 145 [20:58] <rockstar> Any other questions?
 146 [20:59] <rockstar> QUESTION: do you have a quick ref url? for the bzr commands?
 147 [21:00] <rockstar> ANSWER: `bzr help commands` should give you all your commands, and `bzr help commit` will show you the various options for commit.
 148 [21:01] <rockstar> Alright, I think that's all I've got before Castro comes.  Thanks everyone!