GNOME Shell is the desktop you are looking at, and it is reviewed by a design team

What the shell does

The README describes the project in one paragraph, and it is a tighter description than most desktops get. GNOME Shell provides core user interface functions for the GNOME desktop, like switching to windows and launching applications. It takes advantage of the capabilities of modern graphics hardware and introduces user interface concepts to provide a visually attractive and easy to use experience. The subject is the shell rather than the whole desktop, which is an important distinction for a reader who lands in the repository expecting a full operating system. The window switcher, the application launcher and the visual language of the session all live here, and the rest of the desktop, the panel applets, the session manager and the compositor pieces, sits in adjacent projects. The project is distributed under the GNU General Public License, version 2 or later, and the COPYING file in the repository root is the authoritative statement.

The GitHub repository is a mirror

The project description on this repository states that it is a read-only mirror of the project hosted on gitlab.gnome.org, and that is the single most important fact for anyone arriving from GitHub. It changes where everything happens. Merge requests are opened at the GNOME GitLab instance, the issue tracker is the GitLab one, and the issue handbook, the change submission handbook and the coding style documents all live in the same GitLab group. Support and discussion happen on a Matrix room, with a Desktop category and a shell tag on GNOME Discourse. The mirror exists so that the code is searchable and forkable from GitHub, which is useful for reading and for mirrors of mirrors, but the day to day work is on GitLab. The repository is not archived and the last push was on 2026-10-19, so the mirror is being kept current.

Three release series are supported

The supported versions section is short and firm. Upstream gnome-shell only supports the most recent stable release series, the previous stable release series, and the current development release series. Any older stable release series are no longer supported, although they may still receive backported security updates in long term support distributions, and such support is up to the distributions. That last sentence is the one that matters for a reader, because a distribution that still ships an older series will be running a shell that upstream no longer fixes, and the only patches it gets are the security ones its packager chooses to backport. The release schedule is published separately, so you can check when a new series is due, and a reader trying to reproduce a bug has to know which series they are on, since a bug fixed in the current development series may not be fixed in the previous stable one.

Rule out extensions before filing a bug

The bug reporting section contains a piece of advice that is specific to this project and worth repeating. If you are using extensions, please confirm that an issue still happens without extensions, and to properly disable extensions you use the extensions app and then restart your session, because disabling extensions without a restart is not sufficient to rule out extensions as the cause of a bug. If an issue can only be reproduced with a certain extension, the request is to file the issue report against that extension first. The tracker is meant to be used for actionable issues only, and everything else, support questions, feedback on changes and general discussions, belongs in the Matrix room or on Discourse. The reasoning behind the restart requirement is straightforward, since an extension that has been loaded into the running session keeps its hooks until the session ends, so a disabled extension can still be affecting the behaviour you are reporting.

Behaviour changes need the design team

The feature request section explains something about the project that a code reader would not guess. gnome-shell is a core component of the GNOME desktop experience, and as such any changes in behavior or appearance only happen in accordance with the GNOME design team. For major changes, the guidance is to start a discussion on Discourse and reach out on the design Matrix room, and only to involve the issue tracker once agreement has been reached. Mockups must be approved by the design team to be considered for implementation, and for enhancements that are limited in scope and well defined it is acceptable to open a feature request directly. The closing line is the one to remember, which is that when in doubt it is better to ask before opening an issue. In practice that means an ordinary bug fix can go straight to the tracker, while a new interaction, a different layout or a new animation is a proposal rather than a patch.

How to contribute

The contribution rules are conventional but strict about the things that make review painful. Keep the change as small as possible, and if you can split it into multiple merge requests, please do so. Use multiple commits, which makes it easier to review and helps to diagnose bugs in the future. Use clear commit messages following the project's conventions. Pay attention to the CI results, because merge requests cannot be merged until the CI passes. There is a small guide for newcomers with a few more basic tips, and the handbook is linked for the full change submission process. The documentation section lists what a new contributor needs, with coding style and conventions for JavaScript and for C code as separate documents, the GJS Developer Guide, and the guides for building and running the shell and for debugging it. Since the project is written in two languages, the style rules for both are first class reading rather than an afterthought.

The layout and the API surface

The top level of the repository shows the shape of the project. The JavaScript lives in js/ and the C code in src/, with data/ for the resource files, po/ for translations, man/ for the manual pages, tests/, tools/ and build-aux/ for the build helpers, and subprojects/ for the vendored dependencies. The build is Meson, with meson.build, meson.options and a config.h.meson template, and the continuous integration is GitLab CI with a .gitlab-ci.yml and a .gitlab-ci/ directory. The linting setup is visible too, with an eslint.config.js for the JavaScript, a gobject-linter.toml for the GObject introspection conventions and a .jscheckignore. The API reference section names the four libraries the shell is built on, Meta for the display server and window manager, St for the shell toolkit, Clutter for the OpenGL based scene graph and Shell for the non user interface shell objects and utilities, with a pointer to the mutter project for the remaining documentation. The mutter page is where the compositor and window manager documentation lives, and the split explains why a change to the shell often ends up as a change to mutter as well.

Editorial conclusion

GNOME Shell fits a developer who wants to work on the shell of a shipping desktop, and the build, style and debugging documentation makes the codebase approachable once you know that the workflow is a review-heavy one. It does not fit someone who wants to iterate quickly on a feature, since a change in behaviour needs design team agreement before it can be implemented, and mockups are explicitly part of that process. It does not fit a contributor who expects GitHub pull requests, because the GitHub repository is a read-only mirror and the merge requests are opened on gitlab.gnome.org. Before you start, read the supported versions policy, because only the most recent stable series, the previous stable series and the current development series are supported, and check the JavaScript and C coding style documents, since the CI will hold your merge request to them.

Frequently asked questions

Official sources

1. GNOME/gnome-shell on GitHub
2. Issues
3. License: GPL-2.0
4. Project website
5. README