SchoolTool uses Bazaar VCS. Be sure to install it first:
~$ sudo apt-get install bzr
If you don’t already have it, you need make to bootstrap the process:
~$ sudo apt-get install make
To get started with a sandbox:
~$ bzr co lp:schooltool schooltool ~$ cd schooltool
Install build dependencies like compilers, development libraries and fonts:
~$ sudo make ubuntu-environment
Next, pull down additional libraries via PIP and get everything in place:
~$ make develop
The schooltool 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.
To use SchoolTool for anything (beyond calendaring) you need plugins.
Enable plugins (optional).
To enable plugins, edit buildout.cfg to contain, for example:
[package] eggs += schooltool schooltool.gradebook schooltool.lyceum.journal schooltool.intervention
Build and run schooltool:
~/schooltool$ make run
If you want to change enabled plugins, edit buildout.cfg, and run SchoolTool again:
~/schooltool$ make run
Create ~/.buildout/default.cfg and add:
[buildout] eggs-directory = /home/*your-user*/.buildout/eggs download-cache = /home/*your-user*/.buildout/cache extends-cache = /home/*your-user*/.buildout/extends
Buildout does not understand the unix ~ notation, so use the full path.
Create the cache directories:
~$ mkdir -p ~/.buildout/eggs ~$ mkdir -p ~/.buildout/cache ~$ mkdir -p ~/.buildout/extends
For a list of projects, see:
Let’s assume you worked on schooltool.gradebook super ajax feature and your launchpad username is “ideveloper”. Parts you are expected to change depending on who you are or what you are working on are underlined:
~$ cd schooltool_sandbox ~/schooltool_sandbox$ bzr branch lp:schooltool.gradebook schooltool.gradebook_super_ajax ----------- ~/schooltool_sandbox$ cd schooltool.gradebook_super_ajax
It’s slow for the first copy of the project. Shared repository at least speeds up the second branch.
Ensure you have all needed dev tools:
~/schooltool_sandbox/schooltool.gradebook_super_ajax$ sudo make ubuntu-environment
Now, build the project:
~/schooltool_sandbox/schooltool.gradebook_super_ajax$ make develop
Congratulations, you can run the server now:
~/schooltool_sandbox/schooltool.gradebook_super_ajax$ make run
Push your branch to Launchpad:
~/schooltool_sandbox/schooltool.gradebook$ bzr push lp:~ideveloper/schooltool/schooltool.gradebook_super_ajax ---------- -------------------------------
Now you can begin your work. Commit using bzr ci; diff using bzr diff; update your branch using bzr pull. Commit often and in small chunks.
Don’t forget to update the eggs from time to time to the latest released versions:
~/schooltool_sandbox/schooltool.gradebook_super_ajax$ make update
If you worked on a bugfix, now is a good time to link your branch to the bug in Launchpad:
https://code.launchpad.net/~ideveloper/schooltool/schooltool.gradebook_super_ajax ----------- -------------------------------
Finally, propose a merge (to development focus branch) in the Launchpad branch’s page (same link above).
Once it’s reviewed, the feature will be merged to trunk and new development eggs will be released.
Create a new branch for every feature
Having every feature and every bugfix in a separate branch allows reviewing checkins easier, because every branch has only 1 goal. If a bugfix is not complete or it did not pass the review - you can continue working on it in that same branch so all the related changes are in the same place and not 20 unrelated checkins apart. And most importantly, they are not mixed with other features. It also makes the backporting to older SchoolTool versions a lot easier for the maintainers.
Work on a single plugin at a time
Have a separate checkout directory for each project. Do not modify buildout.cfg unless you really need to. Avoid cross-dependencies between plugins. Select carefully to which plugin the feature should logically belong to. Keep things simple. Thanks!
Commit often. Write tests.
Commit often and in small chunks. Write/update unit and functional tests to pass with each commit. The more you practice this rule, the fewer bugs you’ll eventually make.
If you’re fixing an unobvious bug, it’s a good idea to write a test that ensures the bug won’t be reimplemented again.
WARNING: we recommend avoiding this scenario when possible.
Let’s assume you want to work on both SchoolTool core and the Gradebook plugin.
First, check out branches (lp:schooltool and lp:schooltool.gradebook) to your sandbox:
~/schooltool_sandbox$ bzr branch lp:schooltool schooltool_dev ~/schooltool_sandbox$ bzr branch lp:schooltool.gradebook schooltool.gradebook_dev
Edit buildout.cfg in the directory you run the server from (say, schooltool.gradebook_dev).
Change develop to include both SchoolTool and Gradebook:
develop = . ../schooltool_dev
Check if all desired eggs are included:
[schooltool] eggs += schooltool schooltool.gradebook <...>
Push both directories to separate branches in Launchpad, request merges on both at the same time. I believe it’s obvious that dealing with multiple branch merging increases chances of human error.
On Ubuntu you can simply sudo make ubuntu-environment. On other systems, below is what you need:
$ apt-get install build-essential gettext
Contains gcc, make and other tools needed to build software.
Python 2.6 or 2.7 with development headers:
$ apt-get install python-dev
$ apt-get install libicu-dev libxslt1-dev libfreetype6-dev libjpeg-dev enscript
You also need virtualenv and both Ubuntu and Liberation fonts:
$ apt-get install python-virtualenv ttf-ubuntu-font-family ttf-liberation
See also Testing SchoolTool with Virtual Servers if you want to manage several sandboxes using VirtualBox.