Thank you for coming to the the 1st Contribution Hackathon at GUADEC 2023. As the name implies, in this event, we’ll teach you how to make your first code contribution to GNOME. Buckle up!
There are three components that we need for making the contribution: flatpak, flathub, and GNOME Builder. Here’s how to get each of them:
Flatpak is a packaging format for graphical applications that works on any GNU/Linux distribution. It is the most widely embraced packaging format for GNOME applications. To get flatpak on your distro of choice, run:
Flatpak é um formato de empacotamento de aplicações gráficas, que funciona em qualquer distribuição de GNU/Linux (Fedora, Ubuntu, Arch, etc). Esse é o formato escolhido pelo Projeto GNOME para publicar seus pacotes, então o usaremos para instalar os aplicativos e suas dependências.
sudo apt install flatpak
sudo pacman -S flatpak
# already installed
Flathub is an app store for the flatpak packaging format. It’s one of the biggest software catalogs in the Linux world! You can get it on your computer by running:
flatpak remote-add --user --if-not-exists flathub \ https://flathub.org/repo/flathub.flatpakrepo
Finally, GNOME Builder is an integrated development environment (IDE) for developing applications in the GNOME ecosystem. Install it with:
flatpak install org.gnome.Builder
And you’re all set!
GNOME is a software platform. That means GNOME provides an integrated stack for software development, distribution, and consumption.
An important part of this ecosystem are the GNOME apps, to which we’ll contribute in this event! These apps are built with GTK, using GNOME Human Interface Guidelines (HIG).
In programmer’s lingo: it is an object oriented widgets-based framework for developing graphical applications. Let’s break that down!
Object Oriented Programming is a programming paradigm that seeks to improve code organization, reduce code duplication, among many other things. Object Oriented Programming is very “concept heavy”, so teaching everything about it is out of scope for this event. Still, we hope to spark your curiosity enough for you to look it up on your own later :)
In GTK, every graphical element is a “widget”. These widgets are organized hierarchically, for example
Window → Header bar → Menu button. Here are some of the widgets and their names, in the wonderful Frog application:
Graphical applications are applications that show a window to the user. Some applications are not graphical, for example, that ones that run directly on the terminal.
GTK has a feature called Access Keys (also known as “mnemonics”). Here’s how it works:
Altkey until some characters are underlined
Access Keys are an important for two use cases:
To implement an Access Key for a widget within a application, you need to prepend an underline (
_) to whichever character you want to highlighted when the user hold the
Alt key. For example, to highlight the
C in button whose label is
"Continue", go with
Then, activate the Access Key feature for that widget. To do that you need to set the property “
This can sometimes be done with programming or markup languages. For programming languages, you’ll find some examples in the official documentation. Luckly for you, we have also made some additional examples, which you can checkout in the Projects Sheet. Here are some highlights:
Contribution by Gustavo Pechta to the app “Komikku” (link).
Contribution by Tárik Sá to the app “What IP” (link).
Contribution by Pedro Sader Azevedo to the extension “Space Bar” (link).
Now you might asking yourself: How to I decide which widgets to add mnemonics to? Which characters should I choose to underline?
The answer to all these questions (and plenty more) lie in the GNOME Human Interface Guidelines (HIG). This document describes, in a very detailed manner, directives for building graphical user interfaces that comply with the design standards of GNOME.
The HIG contains a section on Access Keys, that you should read thoroughly (it’s very short). When you’re back, here’s summary on how to implement Access Keys in GNOME apps:
Tip: view switchers are usually good candidates for Access Keys! They look like this:
The most popular version control system is
git. We’ll need to use its command line interface (CLI) to make our contribution but, unfortunately,
git is a very complex and convoluted tool. Teaching all about it would take a very long (probably a workshop of its own). If want a deeper introduction to the concepts of
git you can read “The tip of the git iceberg”, by yours truly 😉.
That being said, we’ll only give you what you need for this workshop:
git clone https://...
git checkout -b add-access-keys
git push origin add-access-keys
After you’ve pushed your changes to your GitHub/GitLab account, you have to request that the maintainers of the project accept your contribution. This is known as a “merge request” (MR) or a “pull request” (PR).
When either of these git platforms detect a
git push coming from you, they will offer you to create an MR/PR. Accept the offer and write a detailed description of what your contribution does. Again, you can check the examples in the Project Sheet.
Finally, you’re all set! Follow the steps below to make your first code contribution to GNOME and don’t hesitate to ask any questions.
This blog post is a slightly re-written translation of this blog post by LKCAMP, which was written by myself and Tárik Sá.