• Updated at

A curated list of learning materials, references for GNOME Shell (bug-fixing) developers – very pragmatic.

DISCLAIM: Even at the time of writing, I was not following GNOME development as I used to be. So much of the claims on the states GNOME 3 might be out-righteously outdated.

The other day, my team leader asked me to give some guide for new colleagues in the team. I came up with a list of learning materials, references with strong personal opinions Any sane GNOME developers might scream at the incompleteness of the list.. After passing the list to the new member, I realized this is also an opportunity to review my understanding. So here is the guideline list plus my review.

Some Conventions: different materials have different importance. I didn’t bother going into fine grades of proficiency level. This brings up the memory about the college entry exam, when every student was supposed to know the required proficiency level of each subject. Only two levels are used: Master and General.

Materials

D-Bus

Master

D-Bus is the core RPC mechanism for Linux applications. As with any RPC mechanism, it’s unlikely you’ll love it. Its syntax is bewildering and verbose; few supportive tools are of relatively low quality – merely usable. Anyway, you still need to know it well for its ubiquity in gnome.

DBus would have been much more important if the kernel module kdbus had been merged into kernel. The farthest progress it made was into kernel-next. I’ve read some articles at phoronix talking about the main obstacle was about the security. As a mere side looker, I’ll not say more.

  1. D-Bus Tutorial

    The best introductory material.

  2. D-Bus Intro

    Slightly more theoretical. Read after the first.

Freedesktop.org Specs

Freedesktop.org specs are NOT standards but recommendations. Though most DEs have chosen to comply with some of these specs, the compliance level varies. Nevertheless, since they are somewhat ubiquitous in GNOME, developers are recommended to know at least the followings:

Most of these recommendations are relatively small and the Master level would require less than one day to achieve.

GNOME Shell Wiki

The main hub for GNOME-specific knowledge. Here I’ve listed some more important ones: Things might have improved much these days. For a long time, only some C libraries have some decent API documents. The introspection bindings to Gjs is not complete but only a pragmatic subset. Shell UI components are completely undocumented and have no external API for programming/theming. Code and Wiki might be the only official documents for whatever the help they might offer.

JavaScript

I like JavaScript, but some do not. However, since GNOME Shell UI part is almost written completely in JavaScript, we all need to know it well.

X.org

You really do not want to learn too much about X, but you really need to learn much about it. Despite the mess, X is still the dominant If not the only viable option, Wayland is still far from being an feasible alternative. display technology in Linux Desktop. For us, X is too arcane to dive deep, too important to ignore. I would recommend the book X Power Tools for the introduction. This book is not only about X, but also covers the whole Desktop software stack. Personally, I would recommend the whole book.

GNOME 3 Application Development Beginner’s Guide

A book I only recommend because its high relevance to our work. In general, do not bother with vala, anjuta, Gtk+ if you only work with Shell UI. And read the following chapters first, other parts are not recommended though.

This book was the one my old team leader recommended to me, 3 years ago. There was a Chinese translation project for it as well. I was listed as an translator, but never found enough interests to really work on it. The project itself seems to be abandoned long ago as well with only the first translated chapter released.

With the breaking changes introduced in each GNOME 3 releases, many examples might not work at all. It’s not recommended to try to fix those demos as they might depend on internal Shell implementation and thus hard to fix. The book uses seed, the rumored next JS binding for GNOME. seed has not replaced gjs, maybe never will. Before the latest update, it is the only one that has some documents.

SLE Classic

This part is actually about a SUSE-specific GNOME feature.

At the beginning of SLE 12 development, the drastic deviation of GNOME 3 from old desktop design of GNOME 2 (in SLE 11) was considered a regression for users. In case you are curious about why GNOME 3 was picked back then, the answer is very human: the remaining staff at Desktop Department were only familiar with GNOME. The irony is that GNOME 3 is anything but a familiar GNOME. To tackle this issue, a feature was proposed which is basically an incarnation of SLE 11 desktop look&feel. For the record, Mate and Cinnamon are popular GNOME-forked desktops which have done a much better job in preserving the traditional desktop design. The reason not to pick one of them was the concern over upstream community support. I’ll avoid another irony comment ;P

The repo at Bitbucket was my personal repo to track the development of SLE Classic. It has some useful notes and can serve a good reference for maintaining SLE Classic. The commit log might also be of some interest but the old history is incomplete and convoluted as I was also beginner back then. At present, I believe it is merely an interim hack to help users migrate to newer desktop and should be discontinued in future SLE releases.

Final Notes

Mentality

Beginners for Shell might be surprised by the breaking changes GNOME 3 introduces every release, the lack of documentation in JavaScript part and the pragmatic set of bindings offered to the JavaScript space. That’s all right, GNOME 3 strives to be something new and they are still in the process to be something more. Despite being bitten by these issues in the past, I have come to the revelation that most of the time developers work with insufficient knowledge and instability might just be the norm in this line of work. In retrospect, I wrote a post about this quite a while ago.

Nevertheless, these will still cause inconvenience in the future but at least you are warned. Instead of wasting hours of searching in the doubt of one’s own inability to find necessary information. Been there, done that ;P

“道生一, 一生二，二生三，三生万物”.

Things have to come in order.

I think the following order is appropriate for a beginner:

  1. GNOME Shell Main Wiki
  2. D-Bus Tutorial
  3. JavaScript core
  4. GNOME 3 Application Development Beginner’s Guide: the recommended parts.
  5. X Power Tool: really worth reading, but can be hard at the beginning.


∎

Tags • tech • gnome • bugfix
Comment: Github Issue