From 36828cf89af8fa3b49c44286c156e61558a36a43 Mon Sep 17 00:00:00 2001
From: Daniel Narvaez <dwnarvaez@gmail.com>
Date: Fri, 01 Feb 2013 10:15:14 +0000
Subject: Initial commit

---
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5ca8286
--- /dev/null
+++ b/README.md
@@ -0,0 +1,103 @@
+### Premise
+
+XXX Improve the Sugar OS developer experience
+XXX Cross platform sugar activities -> future
+XXX What is Sugar.
+
+# Modules
+
+The framework is composed of various libraries, initially
+
+* activity
+* graphics
+* datastore
+* collaboration
+
+## Interface description
+
+Each module provides one or more interface descriptions which are language
+independent. A subset of object-oriented languages should be chosen, so that
+it's possible to implement these from all the languages we are interested
+to support. The description uses the Java syntax because unlike, for example,
+python and JavaScript it's explicit about types.
+
+For example, the datastore interface could look like
+
+class Datastore {
+    DatastoreObject load()
+    void save(DatastoreObject object);
+}
+
+XXX The interface is totally made up!
+
+## Implementation
+
+The implementation should be written as much as possible using web languages.
+But of course we will have the necessity to interact with native system
+components. The multi language nature of the interfaces will be useful here
+because it will allow to provide system specific implementation of certain
+interfaces and generically bridge to them from JavaScript. All the modules
+should provide a web fallback, which will allow to run the activity everywhere
+even if with degraded functionality.
+
+## Code style
+
+View source is a core part of the sugar experience, so any kind of code
+obfuscation should be avoided. This includes languages that compiles to
+JavaScript, like CoffeeScript.
+
+## Namespacing and package management
+
+We are using [volo](http://volojs.org) for namespacing and package management,
+both in the libraries and in the documentation.
+
+# Activities
+
+Activities are [open web apps](https://developer.mozilla.org/en-US/docs/Apps),
+their only specificity is that can make use of our libraries framework. On some
+platforms (Sugar OS for example) it might be necessary to generate boilerplate
+code, configuration or to package the app in a certain way to have it integrate
+with the system flawlessly. We will provide scripts to fully automate those
+tasks.
+
+# Random Sugar OS implementation notes
+
+* We should probably use firefox, as provided by upstream, to run activities.
+Chrome would probably be an equally good alternative. At some point we could
+just support both.
+* We should be able to customize it to look like a native activity without
+patching the code. We need to avoid showing any chrome UI (toolbar, menubar,
+etc) and to provide the X properties Sugar expects from an activity.
+* We can generate activity.info from the webapp manifest  when building a .xo.
+* The svg icon might be provided in a native/sugar-os directory of the web
+activity or something.
+* Communication between JavaScript and native code will be handled by a firefox
+extension and it will most likely go through DBus. pythonext might be an
+alternative but I'm not convinced we should get into pyxpcom again. We can use
+dom events to communicate between content and extension.
+* Icons should be shipped as part of the graphics library, we can write a
+script to sync them with the sugar-artwork repository.
+* The datastore interface should probably make use of HTML files support. I
+hope using local paths will work in a web activity.
+* To get full permission I suspect a web app needs to be installed. We will
+have to figure out if/how we can avoid that.
+
+# TODO
+
+Version 0.1
+
+* Write an helloworld open web activity. Or maybe just steal a cool one? Might
+make for a more shiny demo without any effort :)
+* Write a firefox activity using firefox as packaged in the distro. Will
+probably require an extension to disable the chrome UI cleanly.
+* Write the web activity -> sugar activity script, probably as a volo command.
+volo build sugar-os, or something.
+* Play with volo to see if there are any road blockers.
+* Write the activity library, with a close method. It should be enough to call
+window.close() on Sugar OS at least.
+* Document how to use volo to pull in the library.
+* Write the datastore library. This will involve writing an extension which
+will use DBus to communicate with the datastore and making sure we can
+communicate between content and extension.
+* Write the graphics library with initial toolbar implementation. It will
+require writing the script to sync the svg icons from sugar-artwork.
--
cgit v0.9.1