1 == IRC session: "Getting started with Launchpad development" ==
   2 
   3 ''Graham Binns conducted an IRC session entitled [[https://wiki.ubuntu.com/MeetingLogs/devweek0909/LPDevelopment|Getting started with Launchpad development]] on 2 September 2009, as part of Ubuntu Dev Week.  Here's a transcript:''
   4 
   5 {{{
   6 <gmb> My name's Graham Binns. I'm a member of the Launchpad Bugs
   7       development team.
   8 
   9 <gmb> I'm going to talk today about getting started with Launchpad
  10       development, in the hope that it might make it easier for you guys
  11       to contribute patches to scratch your least favourite itches.
  12 
  13 <gmb> Hopefully you'll have all completed the instructions at
  14       http://dev.launchpad.net/Getting so that you can follow along with
  15       this session. If not, you might struggle a bit, but you can always
  16       go back once the session is over and follow it through on your own
  17       time.
  18 
  19 <gmb> If you've any questions, please shout them out in
  20       #ubuntu-classroom-chat and prefix them with QUESTION so that I can
  21       see them easier :)
  22 
  23 <gmb> Okay, so, first things first, we need to find us a bug to fix. For
  24       the purposes of this session I've filed a made-up bug on staging
  25       for us to fix https://staging.launchpad.net/bugs/422299. I've gone
  26       with this because:
  27 
  28 <gmb> 1) It's fairly simple to fix. 2) It's easy to demonstrate our
  29       test-driven development process whilst we fix it, which is why I
  30       didn't pick a bug in the UI. 3) There were no really trivial bugs
  31       available for us to try this out on :).
  32 
  33 <gmb> When you're working on fixing a bug in Launchpad, you nearly
  34       always want to be doing it in a new branch.
  35 
  36 <gmb> We try to keep to one bug per branch, because that means that it's
  37       much easier to review the patches when they're done (because
  38       they're smaller, natch :))
  39 
  40 <gmb> So, let's create a branch in which to fix the bug.
  41 
  42 <gmb> If you've set up the Launchpad development environment properly
  43       according to http://dev.launchpad.net/Getting, you should be able
  44       to run the following command:
  45 
  46 <gmb> $ rocketfuel-branch getting-started-with-lp-bug-422299
  47 
  48 <gmb> Note that I've appended the bug number to the branch
  49 
  50 <gmb> so that I can always refer to it if I need to
  51 
  52 <gmb> but I've also given the branch a useful name to help me remember
  53       what it's for if I have to leave it for a while.
  54 
  55 <gmb> rocketfuel-branch takes a few seconds, so I'll just wait a minute
  56       for everyone to catch up.
  57 
  58 <gmb> (By the way, if anyone has any problems with rocketfuel-get or any
  59       other part of this lesson, please come find me afterwards in
  60       #launchpad and I'll try to help you out)
  61 
  62 <gmb> s/-get/-branch/ there, sorry.
  63 
  64 <gmb> Okay.
  65 
  66 <gmb> Now, at this point, once you'd decided how to fix the bug
  67 
  68 <gmb> but - importantly - before you start coding
  69 
  70 <gmb> you'd ideally have a chat with a member of the Launchpad
  71       development team about your intended fix.
  72 
  73 <gmb> We normally do this either on IRC or on Skype, depending on your
  74       preference.
  75 
  76 <gmb> You can usually find a Launchpad developer in #launchpad-dev on
  77       Freenode who'll be available for one of these calls.
  78 
  79 <gmb> The call gives you a chance to ensure that what you're doing is
  80       actually sane.
  81 
  82 <gmb> For some bugs there's only one possible fix, complex or
  83       otherwise. For others there may be many ways to do it, and it's
  84       important to pick the right one.
  85 
  86 <gmb> If your solution is particularly complex or you need to
  87       demonstrate *why* you want to do things the way you do, it may
  88       help to write some tests to reproduce the bug before you have the
  89       call.
  90 
  91 <gmb> Note that the tests should always fail at this point;
  92 
  93 <gmb> you shouldn't make any changes to the actual code until you've had
  94       the pre-implementation call or chat with an LP developer.
  95 
  96 <gmb> Okay, so that's the info-dumpy bit of this session over for now :)
  97 
  98 [*** gmb accidentally drops from channel for momentarily ***]
  99 
 100 <gmb> Sorry about that, all.
 101 
 102 <gmb> I have a rather flaky connection today :)
 103 
 104 <gmb> As I was saying...
 105 
 106 <gmb> Under lib/lp you'll find most of the Launchpad code, split up into
 107       its applications.
 108 
 109 <gmb> So, `ls lib/lp` in your new getting-started-with-lp-bug-422299
 110       branch should give you something like this:
 111 
 112 <gmb> $ ls lib/lp
 113 
 114 <gmb> answers           archiveuploader  buildmaster  coop
 115       registry  soyuz
 116 
 117 <gmb> app               blueprints       code         __init__.py
 118       scripts   testing
 119 
 120 <gmb> archivepublisher  bugs             codehosting  __init__.pyc
 121       services  translations
 122 
 123 <gmb> Now, we know that we're working in the bugs application, so lets
 124       take a look in there to see where to put our tests:
 125 
 126 <gmb> $ ls lib/lp/bugs
 127 
 128 <gmb> adapters        emailtemplates      help          model
 129       stories      windmill
 130 
 131 <gmb> browser         event               __init__.py   notifications
 132       subscribers  xmlrpc
 133 
 134 <gmb> configure.zcml  externalbugtracker  __init__.pyc  pagetests
 135       templates
 136 
 137 <gmb> doc             feed                interfaces    scripts
 138       tests
 139 
 140 <gmb> There are three types of test in Launchpad: doctests, which live
 141       in lib/lp/$app/doc; stories, which live in lib/lp/$app/stories and
 142       unittests, which live in lib/lp/$app/tests.
 143 
 144 <gmb> In this case we want to add to an existing doctest, so I'll stick
 145       with that for now and we can come back to what the others are for
 146       later.
 147 
 148 <gmb> So, in lib/lp/bugs/doc/ you'll find a file called
 149       externalbugtracker-trac.txt.
 150 
 151 <gmb> This is the test we want to modify, so feel free to open it in
 152       your text editor and take a look at line 110, which is where we're
 153       going to add our test.
 154 
 155 <gmb> For the sake of making this quicker, I've already created a diff
 156       of the change that I'd make here:
 157       http://pastebin.ubuntu.com/263869/plain/
 158 
 159 <gmb> You can save that to disk somewhere (e.g. /tmp/diff) and then
 160       apply it as a patch using `bzr patch /tmp/diff` in the root of
 161       your new Launchpad branch.
 162 
 163 <gmb> The test we've just added is really simple.
 164 
 165 <gmb> It passes 'frobnob' to the convertRemoteStatus() method of a Trac
 166       instance (which is just an abstraction that lets us talk to an
 167       actual Trac server)
 168 
 169 <gmb> and expects to get "Fix Released" back.
 170 
 171 <gmb> Of course, it doesn't since we haven't implemented that yet :).
 172 
 173 <gmb> Once we've written the test, we run it to make sure it fails.
 174 
 175 <gmb> This part is very important: your tests should always fail first
 176       and only after they fail do you write the code to make them pass.
 177 
 178 <gmb>  That means that you can use the tests to build a good spec of how
 179       your module / class / function / whatever should behave.
 180 
 181 <gmb> It also means that, like I said before, you can use the failing
 182       tests to demonstrate what your fix will actually change to whoever
 183       you have a call with.
 184 
 185 <gmb> To run this specific test only, we use the `bin/test` command:
 186 
 187 <gmb> $ bin/test -vvt externalbugtracker-trac.txt
 188 
 189 <gmb> That might take a short while to run (Launchpad's test suite can
 190       be frustratingly slow sometimes, but don't let that put you off;
 191       the payoff is worth it)
 192 
 193 <gmb> The output from which should look something like this:
 194       http://pastebin.ubuntu.com/263874/
 195 
 196 <gmb> Note the important bit:
 197 
 198 <gmb>     File "lib/lp/bugs/tests/../doc/externalbugtracker-trac.txt",
 199       line 111, in externalbugtracker-trac.txt
 200 
 201 <gmb>     Failed example:
 202 
 203 <gmb>         trac.convertRemoteStatus('frobnob').title
 204 
 205 <gmb>     Exception raised:
 206 
 207 <gmb>         Traceback (most recent call last):
 208 
 209 <gmb>           File
 210       "/home/graham/canonical/lp-sourcedeps/eggs/zope.testing-3.8.1-py2.4.egg/zope/testing/doctest.py",
 211       line 1361, in __run
 212 
 213 <gmb>             compileflags, 1) in test.globs
 214 
 215 <gmb>           File "<doctest externalbugtracker-trac.txt[line 111,
 216       example 35]>", line 1, in ?
 217 
 218 <gmb>           File
 219       "/home/graham/canonical/lp-branches/lesson/lib/lp/bugs/externalbugtracker/trac.py",
 220       line 265, in convertRemoteStatus
 221 
 222 <gmb>             raise UnknownRemoteStatusError(remote_status)
 223 
 224 <gmb>         UnknownRemoteStatusError: frobnob
 225 
 226 <gmb> This tells us that the test failed, which is exactly what we
 227       wanted.
 228 
 229 <gmb> (Yes, copying and pasting in IRC makes me a bad man.)
 230 
 231 <gmb> nvertRemoteStatus() raised an UnknownRemoteStatusError instead of
 232       giving us back the status we wanted.
 233 
 234 <gmb> Which was, of course, the 'Fix Released' status.
 235 
 236 <gmb> At this point, you might want to commit the changes:
 237 
 238 <gmb> $ bzr commit -m "Added tests for bug 422299."
 239 
 240 <gmb> Again - I can't emphasise this enough - the fact that your test
 241       fails is a Good Thing. If it didn't fail, it wouldn't be a good
 242       test, since we know that the bug actually exists in the code.
 243 
 244 <gmb> Now that we have a test that fails, we want to add some code to
 245       make it pass
 246 
 247 <gmb> We want to add this to lib/lp/bugs/externalbugtracker/trac.py.
 248 
 249 <gmb> Now, as it happens, I knew that before I started, but you can work
 250       it out by looking at the top of the doctest file that we just
 251       edited.
 252 
 253 <gmb> So, open lib/lp/bugs/externalbugtracker/trac.py now and take a
 254       look at line 258. We'll add our fix here.
 255 
 256 <gmb> The fix is really simple, and we can pretty much copy line 255 and
 257       alter it to suit our needs.
 258 
 259 <gmb> We want 'frobnob' to map to 'Fix Released', so we add the
 260       following line:
 261 
 262 <gmb>     ('frobnob', BugTaskStatus.FIXRELEASED),
 263 
 264 <gmb> I'll not go into the nitty-gritty of how status lookups work here,
 265       because it's unimportant.
 266 
 267 <gmb> Suffice it to say that in Trac's case it's a simple pair of
 268       values, (remote_status, launchpad_status).
 269 
 270 <gmb> Here's a diff of that change: http://pastebin.ubuntu.com/263882/
 271 
 272 <gmb> Now that we've added a fix for the bug, we run the test again:
 273 
 274 <gmb> $ bin/test -vvt externalbugtracker-trac.txt
 275 
 276 <gmb> This time, it should pass without any problems...
 277 
 278 <gmb> and it does
 279 
 280 <gmb> http://pastebin.ubuntu.com/263885/
 281 
 282 <gmb> So, now we commit our changes:
 283 
 284 <gmb> $ bzr ci -m "Fixed bug 422299"
 285 
 286 <gmb> (Note that this is a lame description of the fix; you should use
 287       something more descriptive).
 288 
 289 <gmb> So, we now have a branch that fixes a bug. Hurrah and all that.
 290 
 291 <gmb> Now we need to get it into the Launchpad tree.
 292 
 293 <gmb> Launchpad developers use the Launchpad code review system to
 294       review Launchpad branches.
 295 
 296 <gmb> You can't land a branch without having it reviewed first
 297 
 298 <gmb> This allows us to ensure that code quality stays high
 299 
 300 <gmb> And it also acts as a  sanity check to make sure that the
 301       developer hasn't done something unnecessarily odd in their fix.
 302 
 303 <gmb> So at this point, you need to push your branch to Launchpad using
 304       the `bzr push` command:
 305 
 306 <gmb> $ bzr push
 307 
 308 <gmb> Once the branch has been pushed up to Launchpad it gets its own
 309       page in the Launchpad web interface, which you can look at by
 310       running:
 311 
 312 <gmb> $ bzr lp-open
 313 
 314 <gmb> This should open the page in your default browser.
 315 
 316 <gmb> Now that you've fixed the bug and pushed the branch to Launchpad
 317       you need to request a review for it.
 318 
 319 <gmb> To do this, go to the branch page in your browser and click the
 320       "Propose for merging into another branch" link.
 321 
 322 <gmb> This will take you to a page that looks like this:
 323 
 324 <gmb> http://people.ubuntu.com/~gbinns/propose-merge.png
 325 
 326 <gmb> In the "Initial comment" box, you need to type a description of
 327       the branch.
 328 
 329 <gmb> For example, for this branch I'd write something like:
 330 
 331 <gmb> "This branch fixes bug 422299 by making Trac.convertRemoteStatus()
 332       map the "frobnob" status to Launchpad's Fix Released status."
 333 
 334 <gmb> After you've typed in your description, hit the "Propose merge"
 335       button and you should see a page that looks something like this:
 336       https://code.edge.launchpad.net/~gmb/launchpad/lesson/+merge/11068
 337 
 338 <gmb> You then need to head on over to #launchpad-reviews on Freenode
 339       and ask if anyone's available to review your branch.
 340 
 341 <gmb> If there's no-one available at the time, don't worry.
 342 
 343 <gmb> We have a reviewer schedule:
 344       http://dev.launchpad.net/ReviewerSchedule, so someone should take
 345       a look at it withing 24 hours.
 346 
 347 <gmb> The reviewer may ask you to make changes to your branch
 348 
 349 <gmb> To bring your fix into line with our coding standards
 350 
 351 <gmb> Or maybe to fix a bug that they've spotted in your fix.
 352 
 353 <gmb> Once the reviewer has signed off on the changes, they'll submit
 354       the branch for merging for you.
 355 
 356 <gmb> When a branch gets merged, the entire test suite is run against it
 357 
 358 <gmb> If any of the tests fail
 359 
 360 <gmb> The reviewer may ask you to help fix them
 361 
 362 <gmb> But it's likely that someone else will take care of it if you're
 363       not around at the time
 364 
 365 <gmb> And that's about all there is to simple Launchpad development :)
 366 
 367 <gmb> Are there any questions? Please shout them out in
 368       #ubuntu-classroom-chat
 369 
 370 <gmb> < ahe> QUESTION: When will launchpad be available as a package in
 371       the standard distribution?
 372 
 373 <gmb> ahe: At this point, there aren't any plans for that. We released
 374       the code for Launchpad because we wanted to let people help to
 375       improve the service, but we've no plans as far as I'm aware to
 376       distribute it as a package.
 377 
 378 <gmb> < Andphe> question: have you planned guys, offer launchpad in
 379       another languages than english, example spanish ?
 380 
 381 <gmb> Andphe: It's something that we've considered and that we would
 382       like to do at some point, at least for certain parts of the
 383       interface.
 384 
 385 <gmb> The problem is that launchpad is meant to be a global
 386       collaboration tool, and if we translate it wholesale into other
 387       languages that automatically means that a certain amount of
 388       collaboration will be lost
 389 
 390 <gmb> For exampel, if a user reads the interface in Spanish and files a
 391       bug in Spanish, how am I, an non-Spanish speaker, going to be able
 392       to deal with that bug report?
 393 
 394 <gmb> However, internationalisation would work quite well for the
 395       Answers application, and it's already built with that in mind.
 396 
 397 <gmb> < ahe> QUESTION: Do you deploy launchpad manually or are there
 398       some helper scripts or stuff like that to ease the deployment in a
 399       production environment?
 400 
 401 <gmb> It's a combination of the two.
 402 
 403 <gmb> edge.launchpad.net is deployed by a script every night, as is
 404       staging.launchpad.net.
 405 
 406 <gmb> The production servers are updated manually by our sysadmins at
 407       least once per cycle (though it's usually more than that since we
 408       discover urgent bugs that need to be fixed).
 409 
 410 <gmb> < Andphe> question: if answers already support another languages,
 411       how can we help to translate it ?
 412 
 413 <gmb> Andphe: It's built with translation in mind, but I don't know what
 414       work needs doing to make it translatable.
 415 
 416 <gmb> Andphe: Your best bet would be to join the Launchpad Developers
 417       mailing list (http://launchpad.net/~launchpad-dev) and post a
 418       question about it there.
 419 
 420 <gmb> I think that's about all we've got time for.
 421 
 422 <gmb> If you've any further questions, please feel free to join the
 423       Launchpad Dev list (above)
 424 
 425 <gmb> And ask there.
 426 
 427 <gmb> Everyone's welcome to contribute.
 428 
 429 <gmb> Thanks very much for your time.
 430 }}}