4
SchoolTool uses Bazaar_ VCS. Be sure to install it first::
6
~$ sudo apt-get install bzr
8
Install `build dependencies`_ like compilers, development libraries and fonts::
10
~$ sudo make ubuntu-environment
12
.. _Bazaar: http://bazaar-vcs.org/
18
"But I just want to look at it!"
20
This is not a preferred way to develop SchoolTool, but it will give you a quick taste::
22
~$ bzr co lp:schooltool schooltool
25
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.
27
To *use* SchoolTool for anything (beyond calendaring) you need plugins.
29
Enable plugins (optional).
31
To enable plugins, edit buildout.cfg to contain::
36
schooltool.lyceum.journal
37
schooltool.intervention
39
Build and run schooltool::
41
~/schooltool$ make run
43
Open http://localhost:7080/ in your browser.
45
If you want to change enabled plugins, edit buildout.cfg, and run SchoolTool again::
47
~/schooltool$ make run
50
Setting up a development sandbox
51
--------------------------------
53
Set your buildout eggs and cache directories
54
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
56
Create ~/.buildout/default.cfg and add::
59
eggs-directory = /home/*your-user*/.buildout/eggs
60
download-cache = /home/*your-user*/.buildout/cache
61
extends-cache = /home/*your-user*/.buildout/extends
63
Buildout does not understand the unix ~ notation, so use the full
66
Create the cache directories::
68
~$ mkdir -p ~/.buildout/eggs
69
~$ mkdir -p ~/.buildout/cache
70
~$ mkdir -p ~/.buildout/extends
73
Create the shared repository
74
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
76
Create the bzr shared repository::
78
~$ mkdir schooltool_sandbox
79
~$ bzr init-repo schooltool_sandbox
81
(http://bazaar-vcs.org/SharedRepositoryTutorial)
87
For a list of projects, see::
89
https://launchpad.net/schooltool-project
91
Get the project you want to work on
92
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
94
Let's assume you worked on schooltool.gradebook super ajax feature and your launchpad
95
username is "ideveloper". Parts you are expected to change depending on who you are or what you
96
are working on are underlined::
98
~$ cd schooltool_sandbox
99
~/schooltool_sandbox$ bzr branch lp:schooltool.gradebook schooltool.gradebook_super_ajax
101
~/schooltool_sandbox$ cd schooltool.gradebook_super_ajax
103
It's slow for the first copy of the project. Shared repository at least speeds up the second branch.
105
Ensure you have all needed dev tools::
107
~/schooltool_sandbox/schooltool.gradebook_super_ajax$ sudo make ubuntu-environment
109
Now, build the project::
111
~/schooltool_sandbox/schooltool.gradebook_super_ajax$ make
113
Congratulations, you can run the server now::
115
~/schooltool_sandbox/schooltool.gradebook_super_ajax$ make run
121
Push your branch to Launchpad::
123
~/schooltool_sandbox/schooltool.gradebook$ bzr push lp:~ideveloper/schooltool/schooltool.gradebook_super_ajax
124
---------- -------------------------------
126
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.
128
Don't forget to update the eggs from time to time to the latest released versions::
130
~/schooltool_sandbox/schooltool.gradebook_super_ajax$ make update
133
Publishing your changes
134
~~~~~~~~~~~~~~~~~~~~~~~
136
If you worked on a bugfix, now is a good time to link your branch to the bug in Launchpad::
138
https://code.launchpad.net/~ideveloper/schooltool/schooltool.gradebook_super_ajax
139
----------- -------------------------------
141
Finally, propose a merge (to development focus branch) in the Launchpad branch's page (same link above).
143
Once it's reviewed, the feature will be merged to trunk and new development eggs will be released.
149
**Create a new branch for every feature**
151
Having every feature and every bugfix in a separate branch allows
152
reviewing checkins **easier**, because every branch has only 1 goal. If a
153
bugfix is not complete or it **did not pass the review** - you can
154
**continue working** on it in that **same branch** so all the related changes
155
are in the same place and not 20 unrelated checkins apart. And most importantly,
156
they are **not mixed with other features**. It also makes the **backporting** to
157
older SchoolTool versions a lot easier for the maintainers.
159
**Work on a single plugin at a time**
161
Have a separate checkout directory for each project. Do not modify buildout.cfg
162
unless you really need to. Avoid cross-dependencies between plugins. Select carefully
163
to which plugin the feature should logically belong to. Keep things simple. Thanks!
165
**Commit often. Write tests.**
167
Commit often and in small chunks. Write/update unit and functional tests to
168
pass with each commit. The more you practice this rule, the fewer bugs you'll
171
If you're fixing an unobvious bug, it's a good idea to write a test that ensures the
172
bug won't be reimplemented again.
175
Developing multiple plugins at the same time
176
-----------------------------------------------------
178
WARNING: we recommend avoiding this scenario when possible.
180
Let's assume you want to work on both SchoolTool core and the Gradebook plugin.
182
First, check out branches (lp:schooltool and lp:schooltool.gradebook) to your sandbox::
184
~/schooltool_sandbox$ bzr branch lp:schooltool schooltool_dev
185
~/schooltool_sandbox$ bzr branch lp:schooltool.gradebook schooltool.gradebook_dev
187
Edit ``buildout.cfg`` in the directory you run the server from (say, schooltool.gradebook_dev).
189
Change develop to include both SchoolTool and Gradebook::
191
develop = . ../schooltool_dev
193
Check if all desired eggs are included::
200
Push both directories to separate branches in Launchpad, request merges on both at the
201
same time. I believe it's obvious that dealing with multiple branch merging increases
202
chances of human error.
205
.. _build dependencies:
210
On Ubuntu you can simply ``sudo make ubuntu-environment``. On other systems,
211
below is what you need:
215
$ apt-get install build-essential gettext
217
Contains gcc, make and other tools needed to build software.
219
Python 2.6 or 2.7 with development headers::
221
$ apt-get install python-dev
223
Development libraries::
225
$ apt-get install libicu-dev libxslt1-dev libfreetype6-dev libjpeg-dev enscript
227
You also need virtualenv and both Ubuntu and Liberation fonts::
229
$ apt-get install python-virtualenv ttf-ubuntu-font-family ttf-liberation
added
removed
i18n/hi/build/html/_sources/dev_sandbox.txt
