Dev Week -- LoCo Directory Hacking -- mhall119 -- Wed, Mar 2nd, 2011
1 [17:02] <mhall119> Hello everyone 2 [17:02] <mhall119> my name is Michael Hall, and I'm one of the developers of the Ubuntu LoCo Directory 3 [17:03] <mhall119> I hope you've all been to http://loco.ubuntu.com already, but does anybody not know what it is? 4 [17:04] <mhall119> alright, quick overview then 5 [17:05] <mhall119> the loco directory is a community-driven project, meaning decisions and implementation are determined by the community, not Canonical 6 [17:05] <ClassBot> techbreak asked: mhall119, idk what is this sessoin about ? loco directory ??? 7 [17:05] <mhall119> techbreak_: http://loco.ubuntu.com 8 [17:05] <mhall119> this session is going to get you ready to start hacking and contributing to it 9 [17:06] <mhall119> the loco-directory is written in Python, and uses the Django web framework 10 [17:06] <mhall119> you will need at least working knowledge of python, and some basic understanding of Django to work on LD 11 [17:07] <mhall119> if you don't currently have Django knowledge, don't worry, it's very easy and I'll go over some of it this hour 12 [17:07] <mhall119> the main developers of LD are myself, cjohnston, dholbach, Ronnie and daker 13 [17:07] <mhall119> we all hang out in #ubuntu-locoteams, and that's usually where we discuss LD development 14 [17:08] <mhall119> since loco.ubuntu.com is hosted on one of Canonical's servers running Ubuntu 10.04, we're restricted to the versions software in those repositories 15 [17:09] <mhall119> specifically python 2.6, Django 1.1, jQuery 1.3 and jQuery-ui 1.7 16 [17:09] <mhall119> if you're running Lucid, you're all set 17 [17:09] <mhall119> if you're running Maverick or Natty, you'll need to grab those versions manually 18 [17:11] <mhall119> < YoBoY> QUESTION : we can't develop with earlier versions of python, django, ... or 19 [17:11] <mhall119> it's just recomended ? 20 [17:12] <mhall119> since we develop on 2.6, and it'll be running 2.6 in production, it's generally a good idea for you to use 2.6 21 [17:12] <mhall119> I can't say for sure that it won't work with 2.4, but it's likely 22 [17:13] <mhall119> I'm assuming you have all been introduced to the basics of bzr by now, but if not just ask about it as I go 23 [17:13] <mhall119> alright, lets get the code! 24 [17:13] <mhall119> cd to where you want it to live 25 [17:13] <mhall119> then run: bzr branch lp:loco-directory 26 [17:13] <mhall119> that'll get you a copy of the latest trunk 27 [17:14] <mhall119> trunk is almost always stable 28 [17:14] <ClassBot> RawChid asked: IS there a manual or webpage which describes how to do this? 29 [17:14] <mhall119> not that I know if, but ask us in #ubuntu-locoteams (after this session) and we can help you with it 30 === cmagina is now known as cmagina-lunch 31 [17:15] <mhall119> okay, by now you should all have a local branch of loco-directory 32 [17:15] <mhall119> so cd loco-directory and let's take a look 33 [17:16] <mhall119> quick Django info: 34 [17:16] <mhall119> Django projects are divided between the root 'project' folder, and sub 'application' folders 35 [17:17] <mhall119> in the root of the branch, 'loco_directory' is the django project folder 36 [17:17] <mhall119> so cd loco_directory 37 [17:17] <mhall119> under there you'll see 'common', 'events', 'meetings', 'services', 'teams', 'userprofiles' and 'venues' 38 [17:18] <mhall119> those are all of the Django applications that make up LD 39 [17:18] <mhall119> 'common' is just what it sounds like, it's for things that don't fit elsewhere 40 [17:19] <mhall119> 'teams' contains all the code for LoCo Team records 41 [17:19] <mhall119> ls ./teams/ 42 [17:19] <mhall119> a Django app typically has several standard files 43 [17:20] <mhall119> models.py is where you define your data models, Django will automatically turn these into SQL tables for you (you'll see that later) 44 [17:20] <mhall119> views.py is where you write the code that is responsible for responding to an HTTP request 45 [17:21] <mhall119> and urls.py maps a URL pattern to a view 46 [17:21] <mhall119> any questions so far? 47 [17:21] <mhall119> ok, moving on 48 [17:22] <mhall119> the 'events' and 'venues' are the apps that handle LD's event tracker, if you've used LD before you'll know what they do 49 [17:22] <mhall119> they have the same basic structure as 'teams', with models.py, views.py and urls.py 50 [17:23] <mhall119> same for 'meetings' and 'userprofiles' 51 [17:23] <mhall119> now, Django has a built-in templating system that we use. Our views.py code will usually make use of one or more templates in rendering an HTTP response 52 [17:24] <mhall119> templates live under the 'templates' directory in the project folder 53 [17:24] <mhall119> if you ls ./templates/ you'll see that they're separated out by app as well 54 [17:24] <mhall119> so, to recap 55 [17:25] <mhall119> if you want to change data structures, it'll likely be in a models.py 56 [17:25] <mhall119> if you want to change the logic behind a display, it'll likely be in a views.py 57 [17:25] <mhall119> and if you want to change the interface (html), it'll likely be in the templates 58 [17:25] <mhall119> everybody with me so far? 59 [17:26] <mhall119> alright, let's get you guys setup with a working instance of LD 60 [17:27] <mhall119> first things first, lets look at settings.py in the project folder 61 [17:27] <mhall119> there's a lot of stuff in here, but the key piece is down around line 116: INSTALLED_APPS 62 [17:27] <mhall119> this is a list of apps that Django will use for this project 63 [17:28] <ClassBot> monish001 asked: does Django works on MVC (model view controller framework)? 64 [17:28] <mhall119> yes, though they call it Model-View-Template, and things are slighting shifted 65 [17:29] <mhall119> specifically, the typical 'controller' logic is in the view, and most of the display stuff is in the templates 66 [17:29] <mhall119> okay, lets loot at INSTALLED_APPS 67 [17:29] <mhall119> the first 4 are the standard Django apps, auth gives us User and Group models, plus permissions 68 [17:30] <mhall119> contenttypes is really internal stuff you won't likely ever need to worry about 69 [17:30] <mhall119> sessions gives us automatic session tracking, just like any good web framework should 70 [17:30] <mhall119> admin is the best of them all, it'll give you a fully functional interface to manage the data in your database for all your defined models 71 [17:31] <mhall119> if you look in most of the application folders, you'll see amdin.py, which tells the admin app how to present your models 72 [17:31] <mhall119> the next 6 items in INSTALLED_APPS are the LD apps we've already gone over 73 [17:32] <mhall119> django_openid_auth is what let's us tie our users and groups to the Ubuntu Single Signon 74 === Mkaysi is now known as OmgBot 75 [17:32] <mhall119> south is a special Django app, by default Django will create DB tables based on your models, but it won't change existing tables, which means once you create them you have to make any future changes manually 76 === OmgBot is now known as Guest83509 77 [17:33] <mhall119> south lets you track your model structure, and will provide migration scripts whenever you make changes to them 78 [17:33] <mhall119> we make good use of south in the loco directory 79 === Guest83509 is now known as Mkaysi 80 [17:33] <mhall119> if you look under most of the application folders, you'll see a 'migrations' folder, these are the south scripts 81 [17:33] <mhall119> ok, that's all for settings.py 82 [17:34] <mhall119> next step, copy local_settings.py.sample to local_settings.py 83 [17:34] <mhall119> we use local_settings.py for settings that are specific to a running instance of LD, they aren't checked into bzr 84 [17:35] <mhall119> there's not really anything you need to do with it right now, except make the copy 85 [17:35] <mhall119> everyone with me still? The next part is setting it all up 86 [17:36] <mhall119> alright, lets get our database 87 [17:36] <mhall119> from the project folder, run "./manage.py syncdb" 88 [17:36] <mhall119> it will ask you for a superuser, select yes and give it a username, email and password 89 [17:37] <mhall119> syncdb is the Django command that created your initial database tables 90 [17:37] <mhall119> by default, LD will use a local sqlite3 file for it's database 91 [17:37] <mhall119> in production, it runs against postgres 92 [17:38] <mhall119> you're also free to use MySQL 93 [17:38] <mhall119> when syncdb finishes, you'll see a message about some apps not being synced because they're under south's migration control 94 [17:38] <mhall119> so after syncdb, run: ./manage.py migrate 95 [17:39] <mhall119> this will cause South to run through all of it's migration scripts 96 [17:39] <mhall119> which will leave you with the proper table structures 97 [17:39] <mhall119> if you're using sqlite, you'll see some warnings because it doesn't support some contraints, don't worry about those 98 [17:40] <mhall119> finally, we'll need to initialize your setup, so run: ./manage.py init-ld 99 [17:41] <mhall119> init-ld does several things, it'll setup a group in your database for the LoCo Council, it will create necessary symlinks for jquery, and finally it'll grab a copy of lp:ubuntu-website/light-django-theme 100 [17:41] <mhall119> that last bit is important 101 [17:41] <mhall119> light-django-theme provides the base templates and CSS for several Django powered Ubuntu sites 102 [17:42] <mhall119> loco.ubuntu.com (of course), but also summit.ubuntu.com and 10.cloud.ubuntu.com 103 [17:42] <mhall119> everybody run all of those steps okay? 104 [17:42] * mhall119 looks at the clock 105 [17:44] <mhall119> okay, typically the next step is to either refresh your database with data from Launchpad,or refresh it with data from loco.ubuntu.com 106 [17:44] <mhall119> but, both of those take a while to run, so we're going to skip them and I'll just have you download a copy of loco_directory.db 107 [17:44] <mhall119> http://ubuntuone.com/p/fn1/ 108 [17:44] <mhall119> put that into your project folder (over-writing the one you made with syncdb) 109 [17:45] <mhall119> for reference, "./manage.py lpupdate" will refresh teams and some users from Launchpad, but won't get events, venues or meetings 110 [17:45] <mhall119> "./manage.py import-live-data" will use LD's REST/Json services to download data from loco.ubuntu.com 111 [17:46] <mhall119> once you have the database file, run: ./manage.py runserver 112 [17:46] <mhall119> this will run django's built in webserver on localhost:8000 113 [17:47] <mhall119> which you can then visit in your browser to see your local instance running 114 [17:48] <mhall119> oh yes, Ronnie brings up a point that I missed 115 [17:48] <mhall119> INSTALL file in the root of the branch has instructions for getting things setup 116 [17:48] <mhall119> one of the lines is a long apt-get install, which will get you all the dependencies 117 [17:49] <mhall119> okay, hopefully I've gotten you guys a working (or mostly working) isntance of the LD code 118 [17:50] <mhall119> the next step is to find a bug at https://bugs.launchpad.net/loco-directory to work on 119 [17:50] <mhall119> if you need help figuring out what needs to be done, just ask us in #ubuntu-locoteams 120 [17:51] <ClassBot> There are 10 minutes remaining in the current session. 121 [17:51] <mhall119> but remember, data=models.py, logic=views.py, UI=templates 122 [17:51] <mhall119> that'll get you to the right place 90% of the time 123 [17:51] <mhall119> after you make the fix, test it locally first 124 [17:51] <mhall119> once you're happy with it, run: bzr commit -m "You message" --fixes lp:12345 125 [17:51] <mhall119> where 12345 is the bug number you're working on 126 [17:52] <mhall119> that'll help launchpad associate your code with that bug 127 [17:52] <mhall119> then: bzr push lp:~you/loco-directory/fixes-12345 128 [17:52] <mhall119> agian, I hope you've all been introduced to bzr and distributed development, so this should be familiar 129 [17:53] <mhall119> then go to https://code.launchpad.net/loco-directory, select your branch, and click the "Propose for merging" link 130 [17:54] <mhall119> then one of the main developers will review your code (when we have time, we all have actual jobs too) 131 [17:54] <mhall119> < chadadavis> QUESTION, doe the push statement make a new branch as well, or just 132 [17:54] <mhall119> upload the current branch? 133 [17:55] <mhall119> it will create a new branch in Launchpad, based off the lp:loco-directory branch 134 [17:55] <mhall119> these are very lightweight in launchpad, so don't hesitate to push stuff 135 [17:55] <mhall119> we typically have one branch per fix or feature 136 [17:56] <ClassBot> There are 5 minutes remaining in the current session. 137 [17:56] <mhall119> once your code bases a review, we will merge it into lp:loco-directory 138 [17:56] <mhall119> from there it will get translated and wait for the next release of LD 139 [17:56] <mhall119> anything that lands in trunk will be in the next release 140 [17:57] <mhall119> we don't have a fixed release schedule though, so it's hard to say if it'll take days or weeks to get it out 141 [17:57] <mhall119> < YoBoY> QUESTION : can you point us some easy bugs to start working on ? 142 [17:58] <mhall119> we try to mark small/easy fixes as 'bitesize' in launchpad, you can get a list of them from https://bugs.launchpad.net/loco-directory/+bugs?field.tag=bitesize 143 [17:58] <mhall119> if you get stuck or have other questions, come find one of us in #ubuntu-locoteams 144 [17:58] <mhall119> and happy hacking!