Monday, October 19, 2015

Lessons on being a good maintainer

What makes for a good maintainer? Although I do not know of a definite answer to this important but vague and controversial  question, maintaining various free software projects over the last many years, I've been learning some lessons on how to strive to be a good maintainer; some self-taught through experience, some from my colleagues (especially our awesome GNOME designers) and some from my GSoC students.

I wanted to share these lessons with everyone so I arranged a small BoF at GUADEC and thought it would be nice to share it on planet GNOME as well. Some points only apply to UIs here, some only to libraries (or D-Bus service or anything with a public API really) and some to any kind of project. Here goes:

Only accept use cases

There are no valid feature requests without a proper use case behind them. What's a proper use case you ask? In my opinion, it's based on what the user needs, rather than what they desire or think they need. "I want a button X that does Y" is not a use case, let alone a proper one. "I need to accomplish X" is potentially one.

Even when given a proper use case, does not necessarily mean that you should implement it. You still need to consider the following points before deciding to accept the feature request:
  • How many users do you think this impacts?
  • What's the impact of having this feature to user?
  • What's the impact on users that do not need that feature?
  • How does the expected number of users who need this feature compare to ones that do not.
  • How much work do you think this will be and do you think you (or anyone else in the team) will have the time and motivation to implement it?

Get a thicker skin

Everyone wants software to be tailored for them so unless you have only a few users of your software, you can not possibly satisfy all users. Sometimes users even demand contradictory features so if you are going to be a slave of user demands, you'll not last very long and your software will soon look like my bedroom: random stuff in random places and hard to find what you are looking for.

So don't be afraid of WONTFIX bug resolution. I do agree that this sounds harsh but I think the most important thing is to be honest with your users and not to give them false hopes.

A good API maintainer is a slave of apps

Your library or D-Bus service is as useful and important as the applications that use it. Never forget that while making decisions about public APIs.

Furthermore, if possible, try your best to be involved in at least one of the applications that use your API. Even better if you'd be maintaining one such application. There has been a few occasions where I had to had long debates with library developers about how their API could do much better and I felt that the debate could have been avoided if they had more insights about the applications that use their API. Also, they'd likely care more if they'd experience the pain of the problematic part of their API first hand.

History is important!

VCS (which translates to git for most of us these days) history, that is. I think this is something most developers would readily agree on and some readers must be thinking why do I need to even mention this. However, I've seen that while many would agree in principle to this, in practice they don't care too much. I've seen so many projects out there, where it's very hard or even impossible to find out why a particular line of code was changed in a particular way. Not only it makes maintenance hard, but also discourages new contributors since they'd not feel confident about changing an LOC if they can't be sure why it's how it is and not already what they think it should be like.

So kids, please try to follow some sane commit log rules. We have some here and Lasse has created an extensive version of that document with rationale for each point, for his project here.

Quality of code

This is a bit related to the previous point.  To be very honest, if you don't care about quality enough, you really should not be even working on software that effects others, let alone maintaining them.

How successful you are at maintaining high quality is another thing, and sometimes even not in your hands entirely, but you should always strive for highest quality. The two most important sub-goals in that direction in my opinion, are:


[Insert cliché Einstein quote about simple solutions here.] Each time you come up with a solution (or receive one in the form of patches), ask yourself how it can be done with fewer lines of code. The fewer lines of code you have, the fewer lines of code you'd need to maintain.


Come up with a (or adopt an existing) coding style with specific set of rules to follow and try your very best to follow them. Many contributors would simply dive directly into your project's source code and not read any coding style manual you provide and there is nothing wrong with that. If you are consistent in your code, they'll figure out at least most of your coding style while hacking on your sources.  Also chances are that your coding style would even grow on them and that'll save you a lot of time during your reviews of their patches. That's unlikely to happen if you are not very consistent with your coding style.


None, what so ever. Do what you think is right. This blog post is nothing more than my personal opinions so take it or leave it, it's all up to you!

Wednesday, October 14, 2015

Geoclue convenience library just got even simpler

After writing the blog post about the new Geoclue convenience library, I felt that while the helper API was really simple for single-shot usage, it still wasn't as simple as it should be for most applications, that would need to monitor location updates. They'll still need to make async calls (they could do it synchronously too but that is hardly ever a good idea) to create proxy for location objects on location updates.

So yesterday, I came up with even simpler API that should make interacting with Geoclue as simple as possible. I'll demonstrate through some gjs code that simply awaits for location updates forever and prints the location on console each time there is a location update:

const Geoclue =;
const MainLoop = imports.mainloop;

let onLocationUpdated = function(simple) {
   let location = simple.get_location ();

    print("Location: " +
          location.latitude + "," +

let onSimpleReady = function(object, result) {
    let simple = Geoclue.Simple.new_finish (result);
    simple.connect("notify::location", onLocationUpdated);

    onLocationUpdated (simple);
}; ("geoclue-where-am-i", /* Let's cheat */

Yup, that easy! If I had chosen to use the synchronous API, it would be even simpler. I have already provided a patch for Maps to take advantage of this and I'm planning to provide patches for other apps too.

Friday, October 9, 2015

New in Geoclue: Location sharing & convenience library

Apart from many fixes, Geoclue recently gained some new features as well.

Sharing location from phones

If you read planet GNOME, you must have seen my GSoC student, Ankit already posting about this. Basically his work enabled Geoclue to search for, and make use of any NMEA providers on the local network. The second part of this project, involved implementation of such a service for Android devices. I'm pleased that he managed to get the project working in time and even went the extra mile to fix issues with his code, after GSoC.

This is useful since GPS-based location from android is almost always going to be more accurate than WiFi-based one (assuming neighbouring WiFi networks are covered by Mozilla Location Service). This is especially useful for desktop machines since they typically do not have even WiFi hardware on them and have until now been limited to GeoIP, which at best gives city-level accurate location.

This feature was included in release 2.3.0 and you can download the Android app from here.

 Conveniece library

Almost since the beginning of Geoclue2 project, many people complained that using the new API is far from easy and simple, as it should be. While we have good reasons to keep D-Bus API as it is now, the fact that a lot of time passed since I got around to doing anything about this, meant that it was best if D-Bus API was not changed, Geoclue being a system service.

So this week, I took up the task of implementing a client-side library, that not only exposes gdbus-codegen generated API to communicate with the service but also added a convenience helper API to make things very simple. Basically, you just have to call a few functions now if you simply want to get a location fix quickly and don't care much about accuracy nor interested in subsequent location updates.

I only pushed the changes today to git master so if you have any input, now would be the best time to speak up. I wouldn't want to change API after release.