1
=== added file 'AUTHORS'
2
--- AUTHORS	1970-01-01 00:00:00 +0000
3
+++ AUTHORS	2013-08-21 01:40:39 +0000
4
@@ -0,0 +1,5 @@
5
1
Akshay Shekher <voldyman666@gmail.com>
6
2
Auroral Xylon <avlabs314@gmail.com>
7
3
Eduard Gotwig <gotwig@ubuntu.com>
8
4
Julien Spautz <spautz.julien@gmail.com
9
5
Tom Beckmann <tomjonabc@gmail.com>
10
0
6
11
=== added file 'HACKING'
12
--- HACKING	1970-01-01 00:00:00 +0000
13
+++ HACKING	2013-08-21 01:40:39 +0000
14
@@ -0,0 +1,121 @@
15
1
Developer Documentation
16
2
=======================
17
3
18
4
This document explains how cable works internally and what guidelines you should follow when developing for it.
19
5
20
6
Design Pattern
21
7
==============
22
8
23
9
The current design pattern could be called "Passive View", see http://martinfowler.com/eaaDev/PassiveScreen.html.
24
10
25
11
The View
26
12
--------
27
13
28
14
The View is a software layer that acts as an interface between the program and the user. The View can be acted upon by the user and notify the application of these events (using signals). But its state can also be changed by the application to present some content to the user or request input from the user.
29
15
30
16
In the ``src/View`` folder you will find interfaces that the Controller uses to communicate with the View. The actual implementation can be found in the ``src/Widgets`` folder. This separation bears the advantage that we can change the implementation of the View completely as long as we implement the interfaces. This makes the application independant of the GUI, and we could replace it by a text-based UI or even by a computer simulated UI to run unit tests.
31
17
32
18
Nota bene: The View does not know about any other module (except possibly ``src/Utils`` which contains functions accessible to everyone) 
33
19
34
20
The Model/Backend
35
21
-----------------
36
22
37
23
The traditional name 'Model' doesn't really fit Cable's architecture, as it is based on an interactive networking protocol (namely the IRC protocol) and not on a set of data or even a database. The following modules form the backend of the app and are more or less independant of each other.
38
24
39
25
**Irc**
40
26
41
27
The Irc namespace contains wrapper classes that provide convenient methods, properties and signals that map to dbus calls to the maki IRC daemon. Following naming conventions have been used:
42
28
43
29
    - All signals are prefixed with ``event_``
44
30
    - All methods that send commands to the server are prefixed with ``send_``
45
31
    - Most methods that yield an immediate return value are properties, if it makes sense
46
32
47
33
Examples:
48
34
49
35
    ``public void send_join (string key = "");``
50
36
51
37
    ``public void event_join (string from);``
52
38
53
39
    ``public bool joined { get; }``
54
40
55
41
**Settings**
56
42
57
43
The Settings namespace contains convenient interfaces to the dconf/gsettings using Granite.Services.Settings.
58
44
59
45
**Services**
60
46
61
47
The Services should (whenever possible) be static classes. Currently there is a ``Launcher`` class as interface to libunity and a ``Notification`` class as interface to libnotify. They should have an extremely simple API and contain only functions that are actually used in the app. For example, here you see the ``Cable.Services.Launcher`` API:
62
48
63
49
    ``public static int64 jobs { get; set }``
64
50
65
51
    ``public static double progress { get; set }``
66
52
67
53
    ``public static bool urgent { get; set }``
68
54
69
55
    ``public static void init ();``
70
56
71
57
**Utils**
72
58
73
59
This namespace contains some useful functions and classes that are used in multiple places in the app. The Network and Identity classes, for example, store all networks and identities in a convenient way and make sure no duplicates will be created.
74
60
75
61
The Controller
76
62
--------------
77
63
78
64
The controller is the brain of the app in the sense that it connects different classes that don't know about each other and contains most of the program logic. Conversely, no one knows about the Controller, which means no one can actively act upon the Controller. To communicate with other parts of the application, the Controller connects to their public signals, or uses their public methods and properties.
79
65
80
66
********************************************************************************
81
67
82
68
Tiers
83
69
=====
84
70
85
71
Now that you know about the separation of concerns implemented by the Passive View pattern, I want to explain a recurring pattern in the app which can be broken up into 3 (or 4) tiers, a tree-like hierarchial structure. It looks like this:
86
72
87
73
	Application Tier (one instance)
88
74
89
75
		↓ (n)
90
76
91
77
	Window Tier (n windows per application, unless artificially restricted)
92
78
93
79
		↓ (n)
94
80
95
81
	Server Tier (n server connections can be established per window)
96
82
97
83
		↓ (n)
98
84
99
85
	Channel Tier (n channels per server)
100
86
101
87
This means that the app owns multiple windows, each window has a list of servers, which in turn own any number of channels. This structure exists in many places in the program, which is why it is worth noticing. Obviously it exists in the View/Widgets layer, but also the controller is split into multiple classes, to get cleaner code.
102
88
103
89
In order to make communication between different parts of the application as clean and abstract as possible, it shall *only* occur via these tiers. That is you should not (and cannot) access, any widgets from the Controller, as all communication has to happen via ``View.Window``, ``View.Server`` or ``View.Channel``.
104
90
105
91
So instead of calling something like this from the controller:
106
92
107
93
	``channel_view.room.topic.text = new_topic;``
108
94
109
95
you would use:
110
96
111
97
	``channel_view.topic = new_topic;``
112
98
113
99
and the channel widget will take care of the forwarding.
114
100
115
101
********************************************************************************
116
102
117
103
Unit Testing
118
104
============
119
105
120
106
Unit Testing, Test Driven Development, Extreme Programming… What can we learn from these techniques?
121
107
122
108
GLib provides a very basic way to implement unit tests, and libgee built their TestCase class on it. It allows for simple unit tests, nothing fancy but really straight forward. The main question is where does it make sense to apply unit tests and how do we implement them in a sensible way.
123
109
124
110
Most (virtually all) of the logic lies in the Controller module, as intended. This allows us to bypass the View and replace it by a fake View that implements the same interface but is controlled by the programm. In the same way, we can replace the backend and imitate it's interface to provide a fake backend and simulate really weird server bugs that only happen very rarely and can therefore not be reproduced reliably in a real world environement.
125
111
126
112
Functions and classes in the Utils namespace can also easily be unit tested as they are not connected with the rest of the program. An example would be the URL parsing function.
127
113
128
114
Note that none of this has been implemented (except to a very simple test which can be run using the ``--unit-test`` CLI switch, just as a proof of concept).
129
115
130
116
********************************************************************************
131
117
132
118
Questions?
133
119
==========
134
120
135
121
If you have any questions relating to the architecture of the app, shoot me an email at <spautz.julien@gmail.com> or ask me on IRC (#elementary-dev or #elementary-apps on irc.freenode.net). My nick is julienspautz.
136
0
\ No newline at end of file
122
\ No newline at end of file
137
1
123
138
=== removed file 'README.rst'
139
--- README.rst	2013-08-06 15:32:12 +0000
140
+++ README.rst	1970-01-01 00:00:00 +0000
141
@@ -1,121 +0,0 @@
142
1
Developer Documentation
143
2
=======================
144
3
145
4
This document explains how cable works internally and what guidelines you should follow when developing for it.
146
5
147
6
Design Pattern
148
7
==============
149
8
150
9
The current design pattern could be called "Passive View", see http://martinfowler.com/eaaDev/PassiveScreen.html.
151
10
152
11
The View
153
12
--------
154
13
155
14
The View is a software layer that acts as an interface between the program and the user. The View can be acted upon by the user and notify the application of these events (using signals). But its state can also be changed by the application to present some content to the user or request input from the user.
156
15
157
16
In the ``src/View`` folder you will find interfaces that the Controller uses to communicate with the View. The actual implementation can be found in the ``src/Widgets`` folder. This separation bears the advantage that we can change the implementation of the View completely as long as we implement the interfaces. This makes the application independant of the GUI, and we could replace it by a text-based UI or even by a computer simulated UI to run unit tests.
158
17
159
18
Nota bene: The View does not know about any other module (except possibly ``src/Utils`` which contains functions accessible to everyone) 
160
19
161
20
The Model/Backend
162
21
-----------------
163
22
164
23
The traditional name 'Model' doesn't really fit Cable's architecture, as it is based on an interactive networking protocol (namely the IRC protocol) and not on a set of data or even a database. The following modules form the backend of the app and are more or less independant of each other.
165
24
166
25
**Irc**
167
26
168
27
The Irc namespace contains wrapper classes that provide convenient methods, properties and signals that map to dbus calls to the maki IRC daemon. Following naming conventions have been used:
169
28
170
29
    - All signals are prefixed with ``event_``
171
30
    - All methods that send commands to the server are prefixed with ``send_``
172
31
    - Most methods that yield an immediate return value are properties, if it makes sense
173
32
174
33
Examples:
175
34
176
35
    ``public void send_join (string key = "");``
177
36
178
37
    ``public void event_join (string from);``
179
38
180
39
    ``public bool joined { get; }``
181
40
182
41
**Settings**
183
42
184
43
The Settings namespace contains convenient interfaces to the dconf/gsettings using Granite.Services.Settings.
185
44
186
45
**Services**
187
46
188
47
The Services should (whenever possible) be static classes. Currently there is a ``Launcher`` class as interface to libunity and a ``Notification`` class as interface to libnotify. They should have an extremely simple API and contain only functions that are actually used in the app. For example, here you see the ``Cable.Services.Launcher`` API:
189
48
190
49
    ``public static int64 jobs { get; set }``
191
50
192
51
    ``public static double progress { get; set }``
193
52
194
53
    ``public static bool urgent { get; set }``
195
54
196
55
    ``public static void init ();``
197
56
198
57
**Utils**
199
58
200
59
This namespace contains some useful functions and classes that are used in multiple places in the app. The Network and Identity classes, for example, store all networks and identities in a convenient way and make sure no duplicates will be created.
201
60
202
61
The Controller
203
62
--------------
204
63
205
64
The controller is the brain of the app in the sense that it connects different classes that don't know about each other and contains most of the program logic. Conversely, no one knows about the Controller, which means no one can actively act upon the Controller. To communicate with other parts of the application, the Controller connects to their public signals, or uses their public methods and properties.
206
65
207
66
********************************************************************************
208
67
209
68
Tiers
210
69
=====
211
70
212
71
Now that you know about the separation of concerns implemented by the Passive View pattern, I want to explain a recurring pattern in the app which can be broken up into 3 (or 4) tiers, a tree-like hierarchial structure. It looks like this:
213
72
214
73
	Application Tier (one instance)
215
74
216
75
		↓ (n)
217
76
218
77
	Window Tier (n windows per application, unless artificially restricted)
219
78
220
79
		↓ (n)
221
80
222
81
	Server Tier (n server connections can be established per window)
223
82
224
83
		↓ (n)
225
84
226
85
	Channel Tier (n channels per server)
227
86
228
87
This means that the app owns multiple windows, each window has a list of servers, which in turn own any number of channels. This structure exists in many places in the program, which is why it is worth noticing. Obviously it exists in the View/Widgets layer, but also the controller is split into multiple classes, to get cleaner code.
229
88
230
89
In order to make communication between different parts of the application as clean and abstract as possible, it shall *only* occur via these tiers. That is you should not (and cannot) access, any widgets from the Controller, as all communication has to happen via ``View.Window``, ``View.Server`` or ``View.Channel``.
231
90
232
91
So instead of calling something like this from the controller:
233
92
234
93
	``channel_view.room.topic.text = new_topic;``
235
94
236
95
you would use:
237
96
238
97
	``channel_view.topic = new_topic;``
239
98
240
99
and the channel widget will take care of the forwarding.
241
100
242
101
********************************************************************************
243
102
244
103
Unit Testing
245
104
============
246
105
247
106
Unit Testing, Test Driven Development, Extreme Programming… What can we learn from these techniques?
248
107
249
108
GLib provides a very basic way to implement unit tests, and libgee built their TestCase class on it. It allows for simple unit tests, nothing fancy but really straight forward. The main question is where does it make sense to apply unit tests and how do we implement them in a sensible way.
250
109
251
110
Most (virtually all) of the logic lies in the Controller module, as intended. This allows us to bypass the View and replace it by a fake View that implements the same interface but is controlled by the programm. In the same way, we can replace the backend and imitate it's interface to provide a fake backend and simulate really weird server bugs that only happen very rarely and can therefore not be reproduced reliably in a real world environement.
252
111
253
112
Functions and classes in the Utils namespace can also easily be unit tested as they are not connected with the rest of the program. An example would be the URL parsing function.
254
113
255
114
Note that none of this has been implemented (except to a very simple test which can be run using the ``--unit-test`` CLI switch, just as a proof of concept).
256
115
257
116
********************************************************************************
258
117
259
118
Questions?
260
119
==========
261
120
262
121
If you have any questions relating to the architecture of the app, shoot me an email at <spautz.julien@gmail.com> or ask me on IRC (#elementary-dev or #elementary-apps on irc.freenode.net). My nick is julienspautz.
263
122
\ No newline at end of file
0
\ No newline at end of file
264
123
1
265
=== added file 'THANKS'
266
--- THANKS	1970-01-01 00:00:00 +0000
267
+++ THANKS	2013-08-21 01:40:39 +0000
268
@@ -0,0 +1,10 @@
269
1
The Cable team would like to thank the following code contributors:
270
2
271
3
Alexander Wilms <alexander.wilms@zoho.com>
272
4
Corentin Noël
273
5
Daniele Simonetti
274
6
Evan Banyash <ebanyash@gmail.com>
275
7
Kristjan Vool <tictac7x@gmail.com>
276
8
Mario Guerriero
277
9
nkanaev <nkanaev@live.com>
278
10
Paulo Galardi
279
0
11
280
=== modified file 'src/Cable.vala'
281
--- src/Cable.vala	2013-08-06 15:32:12 +0000
282
+++ src/Cable.vala	2013-08-21 01:40:39 +0000
283
@@ -66,8 +66,12 @@
284
66
        help_url = "https://answers.launchpad.net/cable";
66
        help_url = "https://answers.launchpad.net/cable";
285
67
        translate_url = "https://translations.launchpad.net/cable";
67
        translate_url = "https://translations.launchpad.net/cable";
286
68
68
289
69
        about_authors = {"Akshay Shekher <voldyman666@gmail.com", "Auroral Xylon <avlabs314@gmail.com>", "Eduard Gotwig <gotwig@ubuntu.com>", "Julien Spautz <spautz.julien@gmail.com", "Tom Beckmann <tombeckmann@online.de>"};
69
        about_authors = {"Akshay Shekher <voldyman666@gmail.com>",
290
70
        about_documenters = {"Tom Beckmann <tombeckmann@online.de>"};
70
                         "Auroral Xylon <avlabs314@gmail.com>",
291
71
                         "Eduard Gotwig <gotwig@ubuntu.com>",
292
72
                         "Julien Spautz <spautz.julien@gmail.com>",
293
73
                         "Tom Beckmann <tomjonabc@gmail.com>"};
294
74
        about_documenters = {};
295
71
        about_artists = {"Harvey Cabaguio <harveycabaguio@gmail.com"};
75
        about_artists = {"Harvey Cabaguio <harveycabaguio@gmail.com"};
296
72
        about_comments = _("Development release, not all features implemented");
76
        about_comments = _("Development release, not all features implemented");
297
73
        about_translators = "Launchpad Translators";
77
        about_translators = "Launchpad Translators";
Status:	Merged
Approved by:	Eduard Gotwig on 2013-08-21
Approved revision:	119
Merged at revision:	118
Proposed branch:	lp:~julien-spautz/cable/authors-hacking-thanks
Merge into:	lp:cable
Diff against target:	297 lines (+142/-123) 5 files modified AUTHORS (+5/-0) HACKING (+121/-0) README.rst (+0/-121) THANKS (+10/-0) src/Cable.vala (+6/-2)
To merge this branch:	bzr merge lp:~julien-spautz/cable/authors-hacking-thanks
Related bugs:	Link a bug report
Reviewer	Review Type	Date Requested	Status
Eduard Gotwig (community)		2013-08-20	Needs Fixing on 2013-08-20
Review via email: mp+180967@code.launchpad.net