1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
|
Developing SchoolTool
=====================
SchoolTool uses Bazaar_ VCS. Be sure to install it first::
~$ sudo apt-get install bzr
Install `build dependencies`_ like compilers, development libraries and fonts::
~$ sudo make ubuntu-environment
.. _Bazaar: http://bazaar-vcs.org/
Quickstart
----------
"But I just want to look at it!"
This is not a preferred way to develop SchoolTool, but it will give you a quick taste::
~$ bzr co lp:schooltool schooltool
~$ cd schooltool
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::
[package]
eggs += schooltool
schooltool.gradebook
schooltool.lyceum.journal
schooltool.intervention
Build and run schooltool::
~/schooltool$ make run
Open http://localhost:7080/ in your browser.
If you want to change enabled plugins, edit buildout.cfg, and run SchoolTool again::
~/schooltool$ make run
Setting up a development sandbox
--------------------------------
Set your buildout eggs and cache directories
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
Create the shared repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Create the bzr shared repository::
~$ mkdir schooltool_sandbox
~$ bzr init-repo schooltool_sandbox
(http://bazaar-vcs.org/SharedRepositoryTutorial)
Working on a project
--------------------
For a list of projects, see::
https://launchpad.net/schooltool-project
Get the project you want to work on
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
Congratulations, you can run the server now::
~/schooltool_sandbox/schooltool.gradebook_super_ajax$ make run
Develop your feature
~~~~~~~~~~~~~~~~~~~~
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
Publishing your changes
~~~~~~~~~~~~~~~~~~~~~~~
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.
General guidelines
------------------
**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.
Developing multiple plugins at the same time
-----------------------------------------------------
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.
.. _build dependencies:
Build dependencies
------------------
On Ubuntu you can simply ``sudo make ubuntu-environment``. On other systems,
below is what you need:
Build essentials::
$ 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
Development libraries::
$ 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
|