MAKE YOUR OWN SUGAR ACTIVITIES!
Making contributions to Sugar
by Daniel Francis
Why to contribute to Sugar?
I started contributing to Sugar itself when I was 14 years old after meeting some of the Sugar Labs developers. I saw that the same people maintain activities and fix the necessary bugs in Sugar to make those activities work. I noted that I can improve the Sugar activity development experience because the Sugar code and the activities code aren't very different and I think the free and open source software needs to be improved or fixed and the community can help on it.
Sometimes, as a user you may only report an issue to the developers, but in Sugar it is easier to know how to fix it and improve the Sugar components by yourself.
This can be the reason because at the moment I also have reported bugs in the GNOME bugzilla due some issues in Gtk and other libraries maintained by GNOME, but I only submitted code contributions to Sugar and its activities.
Identifying a bug in Sugar to work on
The way I found to exemplify a contribution to Sugar, is telling when I wanted to add accessibility to one of my activities through implementing key accelerators.Key accelerators are easy to implement in Sugar.
# First you create a button
toolbutton = ToolButton('gtk-quit')
toolbutton.props.tooltip = 'Bold font'
# And here you set the key accelerator
toolbutton.props.accelerator = '<Ctrl>Q'
When doing the same with a ToggleToolButton, I got an error because ToggleToolButtons didn't have the accelerator property. Of course a lot of activities weren't using key accelerators.
Reporting the bug
To discuss if it's really an issue and if must be solved, the usual procedure consists in open a ticket in bugs.sugarlabs.org
A bug tracker is a place where people report bugs and some developers add tasks. The result is a list to tell maintainers or contributors how can they fix the project source code. So, if you want to contribute to Sugar but you didn't find a bug or you don't have a great idea, you can search for tickets in the Sugar Labs bug tracker.
Some important ticket fields
- Summary
- Description
- Type
- Component
- Version
This is like the title of the ticket. The issue in few words.
In this case the summary was: Missing key accelerators at ToggleToolButton
All the details of the bug including steps to reproduce it (if any). If it's graphic, you can link to a screenshot. If you have a log, you can attach it or paste a trace of the log in the ticket description.
In this case it was: The accelerator property, typical in the Sugar ToolButtons isn't available for the Sugar ToggleToolButtons.
Defect, enhancement or task. A defect is when doesn't work as expected, an enhancement is when you want to add a new feature but it must be discussed and a task is when maintainers have a task which can be assigned and solved without a discussion or confirmation like adding activities to Pootle or adding components to this bugtracker.
This is the part of Sugar which must be modified. In the list there are activities, web services such as Pootle or bugs.sugarlabs.org which allows you to add your activity to the bugtracker and of course the Sugar environment which is divided in components. The components for the Sugar API are called sugar-toolkit(-gtk2) and sugar-toolkit-gtk3.
Here you can select the Sugar Version you are using or "Git as of bug date" if you are using jhbuild or sugar-build.
Waiting long time for a reply? Do it by yourself!
Using the Sugar development version
The latest version of the Sugar source code is in git.sugarlabs.org. A convenient tool for developers is 'sugar-build', which will build Sugar from git as a well as pull in any dependencies required by Sugar. (Sugar-build replaces sugar-jhbuild, which is no longer maintained.)
Sugar-build clones and installs sugar in its own directory, so you can change and test the sugar sources without any root administrative password.
Since both Sugar and sugar-build change very often, a description of the steps to build sugar would likely be obsolete before this book is published. However, you can read up-to-date documentation at:
http://sugarlabs.org/~dnarvaez/sugar-docs/
I usually don't test my patches to Sugar itself on an OLPC XO because it is inconvenient to use sugar-build on it and because, if my patch causes the computer to not start, I must reflash the computer and lose all the information on it.
After the patches work in a sugar-build environment and they are applied in the git repository, you can test them on an OLPC development build, which are released at least once a month.
The OLPC development builds are available at http://build.laptop.org/ and they are announced in the Olpc-devel Mailing List, http://lists.laptop.org/listinfo/devel
Modifying the Sugar source code
The first part of the work is find the code files related to the functionality you want to edit. In this case the sugar toolkit in gtk3 is cloned in sources/sugar and the module I edited is in src/sugar3/graphics/toggletoolbutton.py
You can see all the changes with a diff format in:
http://patchwork.sugarlabs.org/patch/1605/
I only had to copy code from toolbutton.py, here some parts I copied to the toggletoolbutton:
def _add_accelerator(tool_button):
if not tool_button.props.accelerator or \
not tool_button.get_toplevel() or \
not tool_button.get_child():
return
# TODO: should we remove the accelerator from the prev top level?
if not hasattr(tool_button.get_toplevel(), 'sugar_accel_group'):
logging.warning('No Gtk.AccelGroup in the top level window.')
return
accel_group = tool_button.get_toplevel().sugar_accel_group
keyval, mask = Gtk.accelerator_parse(tool_button.props.accelerator)
# the accelerator needs to be set at the child, so the
# Gtk.AccelLabel in the palette can pick it up. tool_button.get_child().add_accelerator('clicked', accel_group,
keyval, mask, Gtk.AccelFlags.LOCKED | Gtk.AccelFlags.VISIBLE)
def _hierarchy_changed_cb(tool_button, previous_toplevel):
_add_accelerator(tool_button)
def setup_accelerator(tool_button):
_add_accelerator(tool_button)
tool_button.connect('hierarchy-changed', _hierarchy_changed_cb)
class ToggleToolButton(Gtk.ToggleToolButton):
...
def set_accelerator(self, accelerator):
self._accelerator = accelerator
setup_accelerator(self)
def get_accelerator(self):
return self._accelerator
accelerator = GObject.property(type=str, setter=set_accelerator,
getter=get_accelerator)
Make a patch
Sugar-build clones from git all the Sugar components inside a directory called sources. After editing the code, you must build sugar again to test your changes following the instructions of the sugar-build documentation.
After editing and testing, you must commit your change and make a diff file the maintainers can review and push to the repository.
$ git add src/sugar3/graphics/toggletoolbutton.py $ #Note that SL#xxxx is the bugs.sl.org ticket number $ git commit -s -m "Add accelerator for toggletoolbutton SL#3774" $ git format-patch -1
After that, you will have generated a file like this and you only have to replace the word PATCH with PATCH sugar-toolkit or the component you are patching.
From: Daniel FrancisDate: Sat, 29 Dec 2012 14:10:34 -0200 Subject: [PATCH sugar-toolkit] Add accelerator for toggletoolbutton SL#3774 Signed-off-by: Daniel Francis ---- diff --git a/src/sugar3/graphics/toggletoolbutton.py b/src/sugar3/graphics/toggletoolbutton.py index 94cc6ae..f3a9c57 100644 --- a/src/sugar3/graphics/toggletoolbutton.py +++ b/src/sugar3/graphics/toggletoolbutton.py @@ -19,6 +19,8 @@ STABLE. """ +import logging + from gi.repository import GObject from gi.repository import Gtk @@ -26,6 +28,33 @@ from sugar3.graphics.icon import Icon from sugar3.graphics.palette import Palette, ToolInvoker +def _add_accelerator(tool_button): + if not tool_button.props.accelerator or\ + not tool_button.get_toplevel() or \ + not tool_button.get_child(): + return ....
You can send it as an email if you have installed and configured git-send-email or else you can attach the patch in the bugs.sugarlabs.org ticket. If you choice the first one, the correct procedure is comment the ticket telling that you patched it and giving a link to the mailing list archive.
If all is OK, the patch will be applied in the git repository, the commit title will appear in the release notes with your name as the author and will be part of an OLPC build after some time because OLPC releases builds about once or twice an year.
Benefit to other people
In this case, there was a bug ticket to add key accelerators in the Write activity and they already noted the issue. I fixed it first so they tested the patches and requested the sugar-toolkit maintainers to reply my bug ticket and review my patch faster.