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