Hacking

Differences between revisions 10 and 11
⇤ ← Revision 10 as of 2012-07-05 00:35:37 →
Size: 6446
Editor: 99-41-167-234
Comment:
← Revision 11 as of 2012-07-05 01:36:14 → ⇥
Size: 8977
Editor: 99-41-167-234
Comment:
Deletions are marked like this. Additions are marked like this.
Line 37: Line 37:
== Ubuntu Accomplishments Web Editor == == Ubuntu Accomplishments Web Gallery ==
Line 39: Line 39:
This is the Django-based web editor for editing Ubuntu Accomplishments online. This is the Django-based web gallery for displaying Ubuntu Accomplishments online.
Line 42: Line 42:
  * Code - https://code.launchpad.net/ubuntu-accomplishments-web-editor
  * Bugs - https://bugs.launchpad.net/ubuntu-accomplishments-web-editor		   * Code - https://code.launchpad.net/ubuntu-accomplishments-web
  * Bugs - https://bugs.launchpad.net/ubuntu-accomplishments-web
Line 84: Line 84:

== General Notes ==

Ubuntu Accomplishments uses a client/server approach. We provide a daemon which can have any number of clients connect to it. As an example, we have a GUI GTK client and an Ubuntu Unity Lens client, both of which work by asking the daemon for data and displaying it.

The daemon does almost all of the work required for the clients to be useful (more on this later). The daemon also works asynchronously and we use Twisted so we can perform this async work and not block the clients.

Many of our projects (daemon, viewer, battery) are Quickly projects. This means that you can use Quickly commands such as `quickly edit`, `quickly run`, `quickly design`, and `quickly package` when you work on them. The daemon does not support `quickly run` and you can instead start it from your trunk branch with:

{{{
twistd -noy bin/accomplishments-daemon
}}}

For those of you unfamiliar with `twistd`; it is a tool that allows you to start a service like a daemon and provides suitable logging.


== The Daemon ==

The Daemon is where most of the work happens in the system. The daemon provides an extensive API (in `ubuntu-accomplishments-daemon/accomplishments/daemon/api.py`) that performs a series of functions:

 * Reading in accomplishments collections.
 * Reading and writing the configuration files and logging.
 * Running accomplishments scripts.
 * Creating `.trophy` files.
 * Receiving verified trophies and ensuring that they are valid.
 * Providing an API for clients so they can display trophies and information in different ways.

An important part of the daemon is that it presents an API to clients. the logic for this is in `api.py` and these methods are exposed via DBUS to clients (the DBUS interface is specified in `dbusapi.py`).

Methods inside `api.py` that start with a `_` (e.g. `_this_method()`) are internal methods that are not exposed to clients.

The Daemon has two core classes:

 * `Accomplishments()` - this is where the majority of the API and functionality lives.
 * `AsyncAPI()` - this is where methods that need to talk Asynchronously via Twisted live. These methods typically use Deferreds, so we keep them together in this class.

=== Running ===

You can run the daemon and see it's output with:

{{{
twistd -noy bin/accomplishments-daemon
}}}

Be sure that before you run this that the daemon isn't already running. You can kill any instances of it with:

{{{
killall -9 twistd
}}}

=== Logging ===

Loggin i


== The Viewer ==

Hacking on Ubuntu Accomplishments

This page provides some guidance for how you can contribute to the Ubuntu Accomplishments system, help fix bugs, and make it better. Thanks to every one of you who contributes to help make it better for our users.

Where We Live

You can see a general overview of the entire project at:

You can also see an overview of all bugs at https://bugs.launchpad.net/ubuntu-accomplishments

Core Ubuntu Accomplishments System

Here is where you can find the different resources as part of the project:

This is the Django-based web gallery for displaying Ubuntu Accomplishments online.

The Architecture

The Ubuntu Accomplishments system is inspired by accomplishments systems used in other systems such as the Sony Playstation 3 trophies, StackExchange Badges, and FitBit Badges. The goal here is to create an accomplishments system that is extensible enough to be used by by local applications on a computer and contributions made to the Ubuntu community.

In performing this work, these are some core goals:

  • Extensible - this system should be flexible enough that accomplishments at a desktop level (e.g. “Sent Email From Thunderbird” or “Sent First Tweet In Gwibber”) can be achieved, as well as project contributions (e.g. “Filed First Bug”).

  • Discoverable - the user should be able to see what trophies are available and find out how to achieve them.

  • Highly Distributed - the solution should be as de-centralized as possible so as to reduce the need for an extensive central service.

  • Integrated - the solution should be tightly integrated into Ubuntu itself and not just a series of disconnected web-pages.

there are two core types of accomplishments:

  • Local Accomplishments - accomplishments that are local to your specific computer and do not require verification elsewhere (e.g. completing a level in a game).

  • Global Accomplishments - accomplishments that require verification from a third party (e.g. filing your first bug in Ubuntu).

All accomplishments have the same kind of format and schema, but local and global accomplishments differ in how they generate trophies.

For local accomplishments (e.g. completing a level on a game on your system), the following files are involved:

  • .accomplishment - this file outlines some cosmetic details about the accomplishment such as the name (e.g. ‘Level 2 Completed’), an icon (e.g. ‘level2.png’) and what other accomplishments should be completed before this one can be unlocked (e.g. ‘mygame/level1complete’).

  • .trophy - this file is the generated trophy that represents the completed accomplishment. libaccomplishments-daemon generates it.

Here the .accomplishment file describes the accomplishment and when that accomplishment occurs (e.g. in a game you complete Level 2) the app would call the accomplishments system to process the .accomplishment file and generate the .trophy. This trophy would be added to the Ubuntu One Share for the local trophies.

For Global Accomplishments we need to poll external services to check if an accomplishment has been achieved (e.g. Filing Your First Bug in Launchpad). To perform this polling we need the following:

  • .accomplishment - this file outlines some cosmetic details about the accomplishment such as the title (e.g. ‘First Bug Filed’), an icon (e.g. ‘default.png’) and what other accomplishments should be completed before this one can be unlocked (e.g. ‘ubuntu-community/registered-on-launchpad’).

  • A script (for global accomplishments) - a file that contains the logic for determining if an accomplishment has been achieved (e.g. for a ‘First Bug Filed’ accomplishment this is a small Python script that connects to Launchpad to see if you have filed a bug yet).

At regular intervals, the daemon looks to see, for each user on the system, which global accomplishments they have not yet accomplished. For each accomplishment, the system then runs the corresponding script.

A script is expected to exit with a specific exit code:

  • 0 - for “the accomplishment is now accomplished”
  • 1 - for “the accomplishment is not yet accomplished”
  • 2 - for “there was an error”.

If the logic script indicates that the accomplishment was successfully accomplished, the system creates the appropriate .trophy file. However, because this is a global accomplishment, it needs to be validated by a separate service to ensure the user isn’t faking it. As such, this separate hosted service has the same script and verifies it, and then signs it if successfully verified.

General Notes

Ubuntu Accomplishments uses a client/server approach. We provide a daemon which can have any number of clients connect to it. As an example, we have a GUI GTK client and an Ubuntu Unity Lens client, both of which work by asking the daemon for data and displaying it.

The daemon does almost all of the work required for the clients to be useful (more on this later). The daemon also works asynchronously and we use Twisted so we can perform this async work and not block the clients.

Many of our projects (daemon, viewer, battery) are Quickly projects. This means that you can use Quickly commands such as quickly edit, quickly run, quickly design, and quickly package when you work on them. The daemon does not support quickly run and you can instead start it from your trunk branch with: 

twistd -noy bin/accomplishments-daemon

For those of you unfamiliar with twistd; it is a tool that allows you to start a service like a daemon and provides suitable logging.

The Daemon

The Daemon is where most of the work happens in the system. The daemon provides an extensive API (in ubuntu-accomplishments-daemon/accomplishments/daemon/api.py) that performs a series of functions:

  • Reading in accomplishments collections.
  • Reading and writing the configuration files and logging.
  • Running accomplishments scripts.

  • Creating .trophy files.

  • Receiving verified trophies and ensuring that they are valid.
  • Providing an API for clients so they can display trophies and information in different ways.

An important part of the daemon is that it presents an API to clients. the logic for this is in api.py and these methods are exposed via DBUS to clients (the DBUS interface is specified in dbusapi.py).

Methods inside api.py that start with a _ (e.g. _this_method()) are internal methods that are not exposed to clients.

The Daemon has two core classes:

  • Accomplishments() - this is where the majority of the API and functionality lives.

  • AsyncAPI() - this is where methods that need to talk Asynchronously via Twisted live. These methods typically use Deferreds, so we keep them together in this class.

Running

You can run the daemon and see it's output with: 

twistd -noy bin/accomplishments-daemon

Be sure that before you run this that the daemon isn't already running. You can kill any instances of it with: 

killall -9 twistd

Logging

Loggin i

The Viewer

Accomplishments/GetInvolved/Hacking (last edited 2012-08-02 14:19:25 by ip72-218-233-75)