A learning guide for GNOME Shell bug fixing
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.
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
The best introductory material.
Slightly more theoretical. Read after the first.
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:
- Desktop base directory spec: Master
- Desktop Entry specification: Master
- The Autostart specification: General
- The XSETTINGS: General
- The File URI specification : General
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
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.
- General Information: Master, helpful for debugging
- Technology: General, you need to know the capacity of each component.
- Looking Glass：Master. Not as useful as it claims to be but this is the only built-in tool we have.
- Development guide for GNOME Shell：General, this is more about feature development and upstream involvement.
SpiderMonkeyversion 17., a relatively recent JS engine. However, GNOME has only utilized a small set of JS features in a C-like fashion.
You really do not want to learn too much about
X, but you really need to learn
much about it. Despite
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
Gtk+ if you only work
with Shell UI. And read the following chapters first, other parts are not
- Chapter 3
- Chapter 4
- Chapter 10
- Chapter 11: General
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
never will. Before
the latest update,
it is the only one that has some documents.
This part is actually about a SUSE-specific GNOME feature.
At the beginning of
SLE 12 development, the drastic deviation of
from old desktop design of
GNOME 2 (in
SLE 11) was considered a regression
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
Beginners for Shell might be surprised by the breaking changes GNOME 3
introduces every release, the lack of documentation in
the pragmatic set of bindings offered to the
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
Recommended Learning Order
Things have to come in order.
I think the following order is appropriate for a beginner:
- GNOME Shell Main Wiki
- D-Bus Tutorial
- GNOME 3 Application Development Beginner’s Guide: the recommended parts.
- X Power Tool: really worth reading, but can be hard at the beginning.