1
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
5
<html xmlns="http://www.w3.org/1999/xhtml">
7
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
9
<title>Developing SchoolTool — The SchoolTool Book</title>
11
<link rel="stylesheet" href="_static/flourish.css" type="text/css" />
12
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
14
<script type="text/javascript">
15
var DOCUMENTATION_OPTIONS = {
18
COLLAPSE_INDEX: false,
23
<script type="text/javascript" src="_static/jquery.js"></script>
24
<script type="text/javascript" src="_static/underscore.js"></script>
25
<script type="text/javascript" src="_static/doctools.js"></script>
26
<script type="text/javascript" src="_static/jquery.colorbox-min.js"></script>
27
<script type="text/javascript" src="_static/flourish.js"></script>
28
<link rel="shortcut icon" href="_static/favicon.ico"/>
29
<link rel="author" title="About these documents" href="about.html" />
30
<link rel="top" title="The SchoolTool Book" href="index.html" />
31
<link rel="up" title="Developers’ Handbook" href="developers.html" />
32
<link rel="next" title="Devmode for Developers" href="dev_devmode.html" />
33
<link rel="prev" title="Developers’ Handbook" href="developers.html" />
34
<link rel="stylesheet" type="text/css" href="http://fonts.googleapis.com/css?family=Ubuntu:regular,bold&subset=Latin" />
38
<div class="schooltool">
41
<a href="http://www.schooltool.org/">
42
<span class="school">school</span><span class="tool">tool</span>
43
<img alt="Logo" src="_static/logo-small.png" />
46
<ul class="navigation">
48
<a href="http://schooltool.org/">
53
<a href="features.html">
58
<a href="http://launchpad.net/schooltool-project/+announcements">
63
<a href="screenshots.html">
68
<a href="system-requirements.html">
83
<script type="text/javascript">
84
$(document).ready(function() {
85
$(window).scroll(function() {
86
var scrollTop = $(window).scrollTop();
88
$('div.related').css('position', 'fixed');
89
$('div.related').css('top', '0');
91
$('div.related').css('position', 'absolute');
92
$('div.related').css('top', '64px');
101
<li class="right" style="margin-right: 10px">
102
<a href="dev_devmode.html" title="Devmode for Developers"
103
accesskey="N">next</a></li>
105
<a href="developers.html" title="Developers’ Handbook"
106
accesskey="P">previous</a> |</li>
107
<li><a href="index.html">The SchoolTool Book</a> »</li>
108
<li><a href="developers.html" accesskey="U">Developers’ Handbook</a> »</li>
112
<div id="search-box">
113
<form class="search-form" id="google-appliance-search-form" method="get"
114
accept-charset="UTF-8"
115
action="search.html">
117
<div id="edit-keys-wrapper" class="form-item">
118
<input type="text" class="form-text"
119
onfocus="if(this.value=='Type to search'){this.value=''}"
120
onblur="if(this.value==''){this.value='Type to search';}"
121
value="Type to search" size="20" id="edit-keys" name="q"
123
<input type="hidden" value="yes" name="check_keywords" />
124
<input type="hidden" value="default" name="area" />
126
<img src="_static/arrow.png" class="form-submit"
127
onclick="$(this).closest('form').submit()"
128
style="cursor: pointer" />
132
<!-- End Search Bar -->
136
<div class="document">
137
<div class="documentwrapper">
138
<div class="bodywrapper">
141
<div class="section" id="developing-schooltool">
142
<h1>Developing SchoolTool<a class="headerlink" href="#developing-schooltool" title="Permalink to this headline">¶</a></h1>
143
<p>SchoolTool uses <a class="reference external" href="http://bazaar-vcs.org/">Bazaar</a> VCS. Be sure to install it first:</p>
144
<div class="highlight-python"><div class="highlight"><pre>~$ sudo apt-get install bzr
147
<p>Install <a class="reference internal" href="#build-dependencies">build dependencies</a> like compilers, development libraries and fonts:</p>
148
<div class="highlight-python"><div class="highlight"><pre>~$ sudo make ubuntu-environment
151
<div class="section" id="quickstart">
152
<h2>Quickstart<a class="headerlink" href="#quickstart" title="Permalink to this headline">¶</a></h2>
153
<p>“But I just want to look at it!”</p>
154
<p>This is not a preferred way to develop SchoolTool, but it will give you a quick taste:</p>
155
<div class="highlight-python"><div class="highlight"><pre>~$ bzr co lp:schooltool schooltool
159
<p>The <strong>schooltool</strong> package just contains the “core” functionality of SchoolTool: gets the server up and running, lets you define the structure of the school and the calendar.</p>
160
<p>To <em>use</em> SchoolTool for anything (beyond calendaring) you need plugins.</p>
161
<p>Enable plugins (optional).</p>
162
<p>To enable plugins, edit buildout.cfg to contain:</p>
163
<div class="highlight-python"><div class="highlight"><pre>[package]
166
schooltool.lyceum.journal
167
schooltool.intervention
170
<p>Build and run schooltool:</p>
171
<div class="highlight-python"><div class="highlight"><pre>~/schooltool$ make run
174
<p>Open <a class="reference external" href="http://localhost:7080/">http://localhost:7080/</a> in your browser.</p>
175
<p>If you want to change enabled plugins, edit buildout.cfg, and run SchoolTool again:</p>
176
<div class="highlight-python"><div class="highlight"><pre>~/schooltool$ make run
180
<div class="section" id="setting-up-a-development-sandbox">
181
<h2>Setting up a development sandbox<a class="headerlink" href="#setting-up-a-development-sandbox" title="Permalink to this headline">¶</a></h2>
182
<div class="section" id="set-your-buildout-eggs-and-cache-directories">
183
<h3>Set your buildout eggs and cache directories<a class="headerlink" href="#set-your-buildout-eggs-and-cache-directories" title="Permalink to this headline">¶</a></h3>
184
<p>Create ~/.buildout/default.cfg and add:</p>
185
<div class="highlight-python"><div class="highlight"><pre>[buildout]
186
eggs-directory = /home/*your-user*/.buildout/eggs
187
download-cache = /home/*your-user*/.buildout/cache
188
extends-cache = /home/*your-user*/.buildout/extends
191
<p>Buildout does not understand the unix ~ notation, so use the full
193
<p>Create the cache directories:</p>
194
<div class="highlight-python"><div class="highlight"><pre>~$ mkdir -p ~/.buildout/eggs
195
~$ mkdir -p ~/.buildout/cache
196
~$ mkdir -p ~/.buildout/extends
200
<div class="section" id="create-the-shared-repository">
201
<h3>Create the shared repository<a class="headerlink" href="#create-the-shared-repository" title="Permalink to this headline">¶</a></h3>
202
<p>Create the bzr shared repository:</p>
203
<div class="highlight-python"><div class="highlight"><pre>~$ mkdir schooltool_sandbox
204
~$ bzr init-repo schooltool_sandbox
207
<p>(<a class="reference external" href="http://bazaar-vcs.org/SharedRepositoryTutorial">http://bazaar-vcs.org/SharedRepositoryTutorial</a>)</p>
210
<div class="section" id="working-on-a-project">
211
<h2>Working on a project<a class="headerlink" href="#working-on-a-project" title="Permalink to this headline">¶</a></h2>
212
<p>For a list of projects, see:</p>
213
<div class="highlight-python"><div class="highlight"><pre>https://launchpad.net/schooltool-project
216
<div class="section" id="get-the-project-you-want-to-work-on">
217
<h3>Get the project you want to work on<a class="headerlink" href="#get-the-project-you-want-to-work-on" title="Permalink to this headline">¶</a></h3>
218
<p>Let’s assume you worked on schooltool.gradebook super ajax feature and your launchpad
219
username is “ideveloper”. Parts you are expected to change depending on who you are or what you
220
are working on are underlined:</p>
221
<div class="highlight-python"><div class="highlight"><pre>~$ cd schooltool_sandbox
222
~/schooltool_sandbox$ bzr branch lp:schooltool.gradebook schooltool.gradebook_super_ajax
224
~/schooltool_sandbox$ cd schooltool.gradebook_super_ajax
227
<p>It’s slow for the first copy of the project. Shared repository at least speeds up the second branch.</p>
228
<p>Ensure you have all needed dev tools:</p>
229
<div class="highlight-python"><div class="highlight"><pre>~/schooltool_sandbox/schooltool.gradebook_super_ajax$ sudo make ubuntu-environment
232
<p>Now, build the project:</p>
233
<div class="highlight-python"><div class="highlight"><pre>~/schooltool_sandbox/schooltool.gradebook_super_ajax$ make
236
<p>Congratulations, you can run the server now:</p>
237
<div class="highlight-python"><div class="highlight"><pre>~/schooltool_sandbox/schooltool.gradebook_super_ajax$ make run
241
<div class="section" id="develop-your-feature">
242
<h3>Develop your feature<a class="headerlink" href="#develop-your-feature" title="Permalink to this headline">¶</a></h3>
243
<p>Push your branch to Launchpad:</p>
244
<div class="highlight-python"><div class="highlight"><pre>~/schooltool_sandbox/schooltool.gradebook$ bzr push lp:~ideveloper/schooltool/schooltool.gradebook_super_ajax
245
---------- -------------------------------
248
<p>Now you can begin your work. Commit using <tt class="docutils literal"><span class="pre">bzr</span> <span class="pre">ci</span></tt> diff using <tt class="docutils literal"><span class="pre">bzr</span> <span class="pre">diff</span></tt> update your branch using <tt class="docutils literal"><span class="pre">bzr</span> <span class="pre">pull</span></tt>. Commit often and in small chunks.</p>
249
<p>Don’t forget to update the eggs from time to time to the latest released versions:</p>
250
<div class="highlight-python"><div class="highlight"><pre>~/schooltool_sandbox/schooltool.gradebook_super_ajax$ make update
254
<div class="section" id="publishing-your-changes">
255
<h3>Publishing your changes<a class="headerlink" href="#publishing-your-changes" title="Permalink to this headline">¶</a></h3>
256
<p>If you worked on a bugfix, now is a good time to link your branch to the bug in Launchpad:</p>
257
<div class="highlight-python"><div class="highlight"><pre>https://code.launchpad.net/~ideveloper/schooltool/schooltool.gradebook_super_ajax
258
----------- -------------------------------
261
<p>Finally, propose a merge (to development focus branch) in the Launchpad branch’s page (same link above).</p>
262
<p>Once it’s reviewed, the feature will be merged to trunk and new development eggs will be released.</p>
265
<div class="section" id="general-guidelines">
266
<h2>General guidelines<a class="headerlink" href="#general-guidelines" title="Permalink to this headline">¶</a></h2>
267
<p><strong>Create a new branch for every feature</strong></p>
268
<p>Having every feature and every bugfix in a separate branch allows
269
reviewing checkins <strong>easier</strong>, because every branch has only 1 goal. If a
270
bugfix is not complete or it <strong>did not pass the review</strong> - you can
271
<strong>continue working</strong> on it in that <strong>same branch</strong> so all the related changes
272
are in the same place and not 20 unrelated checkins apart. And most importantly,
273
they are <strong>not mixed with other features</strong>. It also makes the <strong>backporting</strong> to
274
older SchoolTool versions a lot easier for the maintainers.</p>
275
<p><strong>Work on a single plugin at a time</strong></p>
276
<p>Have a separate checkout directory for each project. Do not modify buildout.cfg
277
unless you really need to. Avoid cross-dependencies between plugins. Select carefully
278
to which plugin the feature should logically belong to. Keep things simple. Thanks!</p>
279
<p><strong>Commit often. Write tests.</strong></p>
280
<p>Commit often and in small chunks. Write/update unit and functional tests to
281
pass with each commit. The more you practice this rule, the fewer bugs you’ll
283
<p>If you’re fixing an unobvious bug, it’s a good idea to write a test that ensures the
284
bug won’t be reimplemented again.</p>
286
<div class="section" id="developing-multiple-plugins-at-the-same-time">
287
<h2>Developing multiple plugins at the same time<a class="headerlink" href="#developing-multiple-plugins-at-the-same-time" title="Permalink to this headline">¶</a></h2>
288
<p>WARNING: we recommend avoiding this scenario when possible.</p>
289
<p>Let’s assume you want to work on both SchoolTool core and the Gradebook plugin.</p>
290
<p>First, check out branches (lp:schooltool and lp:schooltool.gradebook) to your sandbox:</p>
291
<div class="highlight-python"><div class="highlight"><pre>~/schooltool_sandbox$ bzr branch lp:schooltool schooltool_dev
292
~/schooltool_sandbox$ bzr branch lp:schooltool.gradebook schooltool.gradebook_dev
295
<p>Edit <tt class="docutils literal"><span class="pre">buildout.cfg</span></tt> in the directory you run the server from (say, schooltool.gradebook_dev).</p>
296
<p>Change develop to include both SchoolTool and Gradebook:</p>
297
<div class="highlight-python"><div class="highlight"><pre>develop = . ../schooltool_dev
300
<p>Check if all desired eggs are included:</p>
301
<div class="highlight-python"><div class="highlight"><pre>[schooltool]
307
<p>Push both directories to separate branches in Launchpad, request merges on both at the
308
same time. I believe it’s obvious that dealing with multiple branch merging increases
309
chances of human error.</p>
311
<div class="section" id="build-dependencies">
312
<span id="id1"></span><h2>Build dependencies<a class="headerlink" href="#build-dependencies" title="Permalink to this headline">¶</a></h2>
313
<p>On Ubuntu you can simply <tt class="docutils literal"><span class="pre">sudo</span> <span class="pre">make</span> <span class="pre">ubuntu-environment</span></tt>. On other systems,
314
below is what you need:</p>
315
<p>Build essentials:</p>
316
<div class="highlight-python"><div class="highlight"><pre>$ apt-get install build-essential gettext
319
<p>Contains gcc, make and other tools needed to build software.</p>
320
<p>Python 2.6 or 2.7 with development headers:</p>
321
<div class="highlight-python"><div class="highlight"><pre>$ apt-get install python-dev
324
<p>Development libraries:</p>
325
<div class="highlight-python"><div class="highlight"><pre>$ apt-get install libicu-dev libxslt1-dev libfreetype6-dev libjpeg-dev enscript
328
<p>You also need virtualenv and both Ubuntu and Liberation fonts:</p>
329
<div class="highlight-python"><div class="highlight"><pre>$ apt-get install python-virtualenv ttf-ubuntu-font-family ttf-liberation
339
<div class="sphinxsidebar">
340
<div class="sphinxsidebarwrapper">
341
<h3><a href="index.html">Table Of Contents</a></h3>
343
<li><a class="reference internal" href="#">Developing SchoolTool</a><ul>
344
<li><a class="reference internal" href="#quickstart">Quickstart</a></li>
345
<li><a class="reference internal" href="#setting-up-a-development-sandbox">Setting up a development sandbox</a><ul>
346
<li><a class="reference internal" href="#set-your-buildout-eggs-and-cache-directories">Set your buildout eggs and cache directories</a></li>
347
<li><a class="reference internal" href="#create-the-shared-repository">Create the shared repository</a></li>
350
<li><a class="reference internal" href="#working-on-a-project">Working on a project</a><ul>
351
<li><a class="reference internal" href="#get-the-project-you-want-to-work-on">Get the project you want to work on</a></li>
352
<li><a class="reference internal" href="#develop-your-feature">Develop your feature</a></li>
353
<li><a class="reference internal" href="#publishing-your-changes">Publishing your changes</a></li>
356
<li><a class="reference internal" href="#general-guidelines">General guidelines</a></li>
357
<li><a class="reference internal" href="#developing-multiple-plugins-at-the-same-time">Developing multiple plugins at the same time</a></li>
358
<li><a class="reference internal" href="#build-dependencies">Build dependencies</a></li>
363
<h4>Previous topic</h4>
364
<p class="topless"><a href="developers.html"
365
title="previous chapter">Developers’ Handbook</a></p>
367
<p class="topless"><a href="dev_devmode.html"
368
title="next chapter">Devmode for Developers</a></p>
371
<div class="clearer"></div>
374
<p class="copyright">
375
© Copyright 2014, the Shuttleworth Foundation. This work is licensed under the Creative Commons Attribution 3.0 Unported License.
378
Last updated on May 22, 2014.
379
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.2.2.
380
<a href="_sources/dev_sandbox.txt"
381
rel="nofollow">Show Source</a>
b'\\ No newline at end of file'
added
removed
i18n/hi/build/html/dev_sandbox.html
