Merge lp:~julien-spautz/cable/authors-hacking-thanks into lp:cable

[Julien Spautz]

added AUTHORS and THANKS files
renamed README to HACKING

[Tom Beckmann (tombeckmann)]

My email changed a while ago, it's tomjonabc(at)gmail(dot)com now, did you find it that way somewhere else? Maybe I should fix it there too. Thanks!

[Julien Spautz (julien-spautz)]

I found it in the src/Cable.vala file. Don't worry, I'll fix it for you.

[lp:~julien-spautz/cable/authors-hacking-thanks]

118. By Julien Spautz on 2013-08-20

fixed Tom's email

[Eduard Gotwig (gotwig)]

I would be glad if you could add

https://launchpad.net/~oppifjellet

and

https://launchpad.net/~nkanaev

to the contributors part.

They've done a great job on Cable development and bug fixing!

btw. when can we merge this?

review: Needs Fixing

[lp:~julien-spautz/cable/authors-hacking-thanks]

119. By Julien Spautz on 2013-08-21

added 2 more contributors

[Julien Spautz (julien-spautz)]

The branch is ready to be merged now.

> I would be glad if you could add
>
>
> https://launchpad.net/~oppifjellet
>
> and
>
> https://launchpad.net/~nkanaev
>
> to the contributors part.
>
> They've done a great job on Cable development and bug fixing!
>
> btw. when can we merge this?

=== added file 'AUTHORS'
--- AUTHORS	1970-01-01 00:00:00 +0000
+++ AUTHORS	2013-08-21 01:40:39 +0000
@@ -0,0 +1,5 @@
+Akshay Shekher <[e-mail]>
+Auroral Xylon <[e-mail]>
+Eduard Gotwig <[e-mail]>
+Julien Spautz <[e-mail]
+Tom Beckmann <[e-mail]>

=== added file 'HACKING'
--- HACKING	1970-01-01 00:00:00 +0000
+++ HACKING	2013-08-21 01:40:39 +0000
@@ -0,0 +1,121 @@
+Developer Documentation
+=======================
+
+This document explains how cable works internally and what guidelines you should follow when developing for it.
+
+Design Pattern
+==============
+
+The current design pattern could be called "Passive View", see http://martinfowler.com/eaaDev/PassiveScreen.html.
+
+The View
+--------
+
+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.
+
+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.
+
+Nota bene: The View does not know about any other module (except possibly ``src/Utils`` which contains functions accessible to everyone) 
+
+The Model/Backend
+-----------------
+
+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.
+
+**Irc**
+
+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:
+
+    - All signals are prefixed with ``event_``
+    - All methods that send commands to the server are prefixed with ``send_``
+    - Most methods that yield an immediate return value are properties, if it makes sense
+
+Examples:
+
+    ``public void send_join (string key = "");``
+
+    ``public void event_join (string from);``
+
+    ``public bool joined { get; }``
+
+**Settings**
+
+The Settings namespace contains convenient interfaces to the dconf/gsettings using Granite.Services.Settings.
+
+**Services**
+
+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:
+
+    ``public static int64 jobs { get; set }``
+
+    ``public static double progress { get; set }``
+
+    ``public static bool urgent { get; set }``
+
+    ``public static void init ();``
+
+**Utils**
+
+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.
+
+The Controller
+--------------
+
+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.
+
+********************************************************************************
+
+Tiers
+=====
+
+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:
+
+	Application Tier (one instance)
+
+		↓ (n)
+
+	Window Tier (n windows per application, unless artificially restricted)
+
+		↓ (n)
+
+	Server Tier (n server connections can be established per window)
+
+		↓ (n)
+
+	Channel Tier (n channels per server)
+
+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.
+
+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``.
+
+So instead of calling something like this from the controller:
+
+	``channel_view.room.topic.text = new_topic;``
+
+you would use:
+
+	``channel_view.topic = new_topic;``
+
+and the channel widget will take care of the forwarding.
+
+********************************************************************************
+
+Unit Testing
+============
+
+Unit Testing, Test Driven Development, Extreme Programming… What can we learn from these techniques?
+
+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.
+
+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.
+
+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.
+
+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).
+
+********************************************************************************
+
+Questions?
+==========
+
+If you have any questions relating to the architecture of the app, shoot me an email at <[e-mail]> or ask me on IRC (#elementary-dev or #elementary-apps on irc.freenode.net). My nick is julienspautz.
\ No newline at end of file

=== removed file 'README.rst'
--- README.rst	2013-08-06 15:32:12 +0000
+++ README.rst	1970-01-01 00:00:00 +0000
@@ -1,121 +0,0 @@
-Developer Documentation
-=======================
-
-This document explains how cable works internally and what guidelines you should follow when developing for it.
-
-Design Pattern
-==============
-
-The current design pattern could be called "Passive View", see http://martinfowler.com/eaaDev/PassiveScreen.html.
-
-The View
---------
-
-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.
-
-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.
-
-Nota bene: The View does not know about any other module (except possibly ``src/Utils`` which contains functions accessible to everyone) 
-
-The Model/Backend
------------------
-
-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.
-
-**Irc**
-
-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:
-
-    - All signals are prefixed with ``event_``
-    - All methods that send commands to the server are prefixed with ``send_``
-    - Most methods that yield an immediate return value are properties, if it makes sense
-
-Examples:
-
-    ``public void send_join (string key = "");``
-
-    ``public void event_join (string from);``
-
-    ``public bool joined { get; }``
-
-**Settings**
-
-The Settings namespace contains convenient interfaces to the dconf/gsettings using Granite.Services.Settings.
-
-**Services**
-
-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:
-
-    ``public static int64 jobs { get; set }``
-
-    ``public static double progress { get; set }``
-
-    ``public static bool urgent { get; set }``
-
-    ``public static void init ();``
-
-**Utils**
-
-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.
-
-The Controller
---------------
-
-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.
-
-********************************************************************************
-
-Tiers
-=====
-
-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:
-
-	Application Tier (one instance)
-
-		↓ (n)
-
-	Window Tier (n windows per application, unless artificially restricted)
-
-		↓ (n)
-
-	Server Tier (n server connections can be established per window)
-
-		↓ (n)
-
-	Channel Tier (n channels per server)
-
-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.
-
-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``.
-
-So instead of calling something like this from the controller:
-
-	``channel_view.room.topic.text = new_topic;``
-
-you would use:
-
-	``channel_view.topic = new_topic;``
-
-and the channel widget will take care of the forwarding.
-
-********************************************************************************
-
-Unit Testing
-============
-
-Unit Testing, Test Driven Development, Extreme Programming… What can we learn from these techniques?
-
-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.
-
-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.
-
-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.
-
-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).
-
-********************************************************************************
-
-Questions?
-==========
-
-If you have any questions relating to the architecture of the app, shoot me an email at <[e-mail]> or ask me on IRC (#elementary-dev or #elementary-apps on irc.freenode.net). My nick is julienspautz.
\ No newline at end of file

=== added file 'THANKS'
--- THANKS	1970-01-01 00:00:00 +0000
+++ THANKS	2013-08-21 01:40:39 +0000
@@ -0,0 +1,10 @@
+The Cable team would like to thank the following code contributors:
+
+Alexander Wilms <[e-mail]>
+Corentin Noël
+Daniele Simonetti
+Evan Banyash <[e-mail]>
+Kristjan Vool <[e-mail]>
+Mario Guerriero
+nkanaev <[e-mail]>
+Paulo Galardi

=== modified file 'src/Cable.vala'
--- src/Cable.vala	2013-08-06 15:32:12 +0000
+++ src/Cable.vala	2013-08-21 01:40:39 +0000
@@ -66,8 +66,12 @@
         help_url = "https://answers.launchpad.net/cable";
         translate_url = "https://translations.launchpad.net/cable";
 
-        about_authors = {"Akshay Shekher <[e-mail]", "Auroral Xylon <[e-mail]>", "Eduard Gotwig <[e-mail]>", "Julien Spautz <[e-mail]", "Tom Beckmann <[e-mail]>"};
-        about_documenters = {"Tom Beckmann <[e-mail]>"};
+        about_authors = {"Akshay Shekher <[e-mail]>",
+                         "Auroral Xylon <[e-mail]>",
+                         "Eduard Gotwig <[e-mail]>",
+                         "Julien Spautz <[e-mail]>",
+                         "Tom Beckmann <[e-mail]>"};
+        about_documenters = {};
         about_artists = {"Harvey Cabaguio <[e-mail]"};
         about_comments = _("Development release, not all features implemented");
         about_translators = "Launchpad Translators";