Tips for contributing code to open source projects

I've spent a lot of time over the years contributing to and reviewing code changes to open source projects. It can take a lot of work for the submitter and reviewer to get a change accepted and often they don't make it. Here are the things in my experience that successful contributions do.

Use the issue tracker. Having an open issue means there is always something to point to with all the history of the change that wont get lost. Submit patches using the appropriate method (merge proposals, pull requests, attachments in the issue tracker etc).

Sell your idea. The change is important to you but the maintainers may not think so. You may be a 1% use case that doesn't seem worth supporting. If the change fixes a bug describe exactly how to reproduce the issue and how serious it is. If the change is a new feature then show how it is useful.

Always follow the existing coding style. Even if you don't like it. If the existing code uses tabs, then use them too. Match brace style. If the existing code is inconsistent, match the code nearest to the changes you are making.

Make your change as small as possible. Put yourself in the mind of the reviewer. The longer the patch the more time it will take to review (and the less appealing it will be to do). You can always follow up later with more changes. First time contributors need more review - over time you can propose bigger changes and the reviewers can trust you more.

Read your patch before submitting it. You will often find bits you should have removed (whitespace, unrelated variable name changes, debugging code).

Be patient. It's OK to check back on progress - your change might have be forgotten about (everyone gets busy). Ask if there's any more you can do to make it easier to accept.

Writing applications for Ubuntu Phone

I've just released my fifth application for the Ubuntu phone and I thought I'd do a write up of my experiences developing for Ubuntu Phone. In summary, it's been pretty positive!

The good:

• Installing the SDK is as easy as installing any application in Ubuntu.
• Writing applications is fast. You can throw together something fairly nice in a few hours.
• Click packages are so easy to build! It makes .deb packages feel like something from the 1990s. Which is appropriate, because they are from the 1990s.
• The deployment process is incredibly fast. You create a click package from the SDK, upload it to the store in a web form and it lands on my (or anyone else's) phone in under a minute normally. A freaking minute! That's amazing!

The bad / ugly:

• The Ubuntu SDK (aka Qt Creator) still reinforces why I don't like IDEs. While it's better than older IDEs it's still overly complicated and cluttered with buttons. I only use it to dogfood the process and the command line tools aren't great for building and deploying applications (yet).
• QML is... OK. It has all the technology of a modern toolkit (e.g. transitions, it's declarative, you can develop using a dynamic language) which is good. But it feels like it was put together in a rush. It's often not clear what the best way is to solve a problem and some components seem to be missing useful functionality (e.g. containers).
• Javascript is great for small applications but quickly becomes unwieldy for large ones. The default other option is to use C++ which is just an enormous step backwards into complexity. I haven't yet tried Go QML but hopefully that will be a better combination.
• The Ubuntu store interface is very basic. There's no way to list apps by ranking, you can't see new applications, there's no web interface. I'm sure it will get better soon but it's currently hard to find what's available (which is a big part of why I'm writing this blog post).

Here's what I've made; all these applications are released under the GPL 3 license and available on Launchpad. You can get the source for any of them by typing "bzr branch lp:euchre" from an Ubuntu machine.

Euchre

My first Ubuntu phone application. It's a classic four player trick taking card game with a basic AI.  I learnt a lot about animation in QML developing this. It's all written in Javascript which is really pushing the limits of maintainability for an application like this (1833 lines of QML). While it is the oldest it is also the least downloaded of my applications I think because Euchre is a bit of a niche game and I don't have any in game help.

Animal Farm

The inspiration for this was my daughter enjoying applications like this on Android. You touch the animals and they shake and meow / baa etc. It's trivially small (157 lines of QML).

Dotty

Dotty is a clone of the very successful iOS / Android game Dots. I thought I'd see if copying a popular game would transfer into success in Ubuntu and it has. This is my most popular game with 362 users currently compared to 160 for Animal Farm which is the next most popular. I learnt how to do dynamic components (i.e. the lines and the dots falling down) with this. A good size at 605 lines of QML.

Five Letters

Like Dotty I was looking for the type of games that are already popular on existing platforms. Word games are quite successful and I was thinking of games like 7 little words when designing this. The "making words from five letters" is a common newspaper game. I spent a lot of time trimming the dictionary of possible games to remove anything offensive or obscure so it should be reasonably possible to solve all the puzzles (there's about 1300 of them). 406 lines of QML.

Pairs

My newest game! Released last night. Like Animal Farm I was thinking of something my children might like to play. You turn over the cards two at a time and try and find the matching colours. The colours I've used actually make it quite difficult and fun to play as an adult. 409 lines of QML.

Using EGL with GTK+

I recently needed to port some code from GTK+ OpenGL code from GLX to EGL and I couldn't find any examples of how to do this. So to seed the Internet here is what I found out.

This is the simplest example I could make to show how to do this. In real life you probably want to do a lot more error checking. This will only work with X11; for other systems you will need to use equivalent methods in gdk/gdkwayland.h etc. For anything modern you should probably use OpenGL ES instead of OpenGL - to do this you'll need to change the attributes to eglChooseConfig and use EGL_OPENGL_ES_API in eglBindAPI.

Compile with:
gcc -g -Wall egl.c -o egl `pkg-config --cflags --libs gtk+-3.0 gdk-x11-3.0` -lEGL -lGL

#include <gtk/gtk.h>
#include <gdk/gdkx.h>
#include <EGL/egl.h>
#include <GL/gl.h>

static EGLDisplay *egl_display;
static EGLSurface *egl_surface;
static EGLContext *egl_context;

static void realize_cb (GtkWidget *widget)
{
    EGLConfig egl_config;
    EGLint n_config;
    EGLint attributes[] = { EGL_RENDERABLE_TYPE, EGL_OPENGL_BIT,
                            EGL_NONE };

    egl_display = eglGetDisplay ((EGLNativeDisplayType) gdk_x11_display_get_xdisplay (gtk_widget_get_display (widget)));
    eglInitialize (egl_display, NULL, NULL);
    eglChooseConfig (egl_display, attributes, &egl_config, 1, &n_config);
    eglBindAPI (EGL_OPENGL_API);
    egl_surface = eglCreateWindowSurface (egl_display, egl_config, gdk_x11_window_get_xid (gtk_widget_get_window (widget)), NULL);
    egl_context = eglCreateContext (egl_display, egl_config, EGL_NO_CONTEXT, NULL);
}

static gboolean draw_cb (GtkWidget *widget)
{
    eglMakeCurrent (egl_display, egl_surface, egl_surface, egl_context);

    glViewport (0, 0, gtk_widget_get_allocated_width (widget), gtk_widget_get_allocated_height (widget));

    glClearColor (0, 0, 0, 1);
    glClear (GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);

    glMatrixMode (GL_PROJECTION);
    glLoadIdentity ();
    glOrtho (0, 100, 0, 100, 0, 1);

    glBegin (GL_TRIANGLES);
    glColor3f (1, 0, 0);
    glVertex2f (50, 10);
    glColor3f (0, 1, 0);
    glVertex2f (90, 90);
    glColor3f (0, 0, 1);
    glVertex2f (10, 90);
    glEnd ();

    eglSwapBuffers (egl_display, egl_surface);

    return TRUE;
}

int main (int argc, char **argv)
{
    GtkWidget *w;

    gtk_init (&argc, &argv);

    w = gtk_window_new (GTK_WINDOW_TOPLEVEL);
    gtk_widget_set_double_buffered (GTK_WIDGET (w), FALSE);
    g_signal_connect (G_OBJECT (w), "realize", G_CALLBACK (realize_cb), NULL);
    g_signal_connect (G_OBJECT (w), "draw", G_CALLBACK (draw_cb), NULL);

    gtk_widget_show (w);

    gtk_main ();

    return 0;
}

GTK+ applications in Unity 8 (Mir)

Ryan Lortie and I have been tinkering away with making getting GTK+ applications to run in Unity 8 and as you can see below it works!

This shows me running the Unity 8 preview session. Simple Scan shows up as an option and can be launched and perform a scan.

This is only a first start, and there's still lots of work to be done. In particular:

• Applications need to set X-Ubuntu-Touch=true in their .desktop files to show in Unity 8.
• Application icons from the gnome theme do not show (bug).
• GTK+ applications don't go fullscreen (bug).
• No cursors changes (bug).
• We only support single window applications because we can't place/focus the subwindows yet (bug). We're currently faking menus and tooltips by drawing them onto the same surface.

If you are using Ubuntu 14.10 you can install the packages for this from a PPA:

$ sudo apt-add-repository ppa:ubuntu-desktop/gtk-mir
$ sudo apt-get update
$ sudo apt-get upgrade

The PPA contains a version of GTK+ with Mir support, fixes for libraries that assume you are running in X and a few select applications patched so they show in Unity 8.

The Mir backend currently on the wip/mir branch in the GTK+ git repository. We will keep developing it there until it is complete enough to propose into GTK+ master. We have updated jhbuild to support Mir so we can easily build and test this backend going forward.

errors.ubuntu.com

One of the most useful tools I use is errors.ubuntu.com. This shows statistics for the crash reports that are sent from users machines. Before I would trawl through Launchpad trying to work out which crash reports were more significant. Now we have numbers to see what's important.

Here is a graph showing the crash reports received for the last six releases over the last year:

Some interesting things from the graph:

• We get more crash reports on weekdays than weekends (see the ripple in the 12.04 and 12.10 lines which otherwise seem quite stable).
• Apparently people stop using Ubuntu development releases around Christmas (huge dip in the middle of the Ubuntu 14.04 line). Stable releases are unaffected.
• You can see a step in crash reports for the 14.04 beta release (March). Looks like there was an outage then too as every release has a dip in reports before.
• It looks like as soon as 14.04 was released (April) there's been a rapid migration from 13.10 users to 14.04 so there is now probably less than half the number of 13.10 users there were before.
• If you look closely you can also see a slight decrease in crash reports from 12.04 after the 14.04 release, so people are migrating LTS to LTS.
• I guess the 12.10 users love it because they don't seem to have started migrating at all.
• We get a huge number of crash reports from release days and these very smoothly drop off over approximately three months. I guess this is due to the bugs being fixed and the users slowly updating.
• Sorry, I don't get the vertical axis any more than you do other than to say "bigger means more crash reports" (bug). The X axis also show months from 2013/2014 (bug).
• Not sure why the left hand side is so high - have we really reduced crash reports that much?

Why the display server doesn't matter

Display servers are the component in the display stack that seems to hog a lot of the limelight. I think this is a bit of a mistake, as it's actually probably the least important component, at least to a user.

In the modern display stack there are five main components:

• Hardware
• Driver
• Display Server / Shell
• Toolkit / Platform API
• Applications

The hardware we have no control over. We just get to pick which hardware to buy. The driver we have more control over - drivers range from completely closed source to fully open source. There's a tug of war between the hardware manufacturers who are used to being closed (like their hardware) and the open source community which wants to be able to modify / fix the drivers.

For (too) many years we've lived with the X display server in the open source world. But now we are moving into next generation display servers (as Apple and Microsoft did many years ago). At the moment there are two new classes of contender for X replacement, Mir and a set of Wayland based compositors (e.g. weston, mutter-wayland etc).

Applications use toolkits and platform APIs to access graphical functionality. There are plenty of toolkits out there (e.g. GTK+, Qt) and existing libraries are growing more broad, consistent and stable to be considered as a complete platform API (which is great for developers).

If you read the Internet you would think the most important part in this new world is the display server. But actually it's just a detail that doesn't matter that much.

• Applications access the display server via a toolkit. All the successful toolkits support multiple backends because there's more than one OS out there today. In general you can take a GTK+ application and run it in Windows and everything just works.
• The hardware and drivers are becoming more and more generic. Video cards used to have very specialised functionality and OpenGL used to provide only a fixed function function. Now video cards are basically massively parallel processors (see OpenCL) and OpenGL is a means of passing shaders and buffer contents.

The result of this is the display server doesn't matter much to applications because we have pretty good toolkits that already hide all this information from us. And it doesn't matter much to drivers as they're providing much the same operations to anything that uses them (i.e. buffer management and passing shaders around).

So what does matter now?

• It does matter that we have open drivers. Because there will be different things exercising them we need to be able to fix drivers when display server B hits a bug but A doesn't. We saw this working with Mir on Android drivers. Since these drivers are only normally used by SurfaceFlinger there are odd bugs if you do things differently. Filing a bug report is no substitute to being able to read and fix the driver yourself.
• The shell matters a lot more. We're moving on from the WIMP paradigm. We have multiple form factors now. The shell expresses what an application can do and different shells are likely to vary in what they allow.

I hope I've given some insight into the complex world of display stacks and shown we have plenty of room for innovation in the middle without causing major problems to the bits that matter to users.