Getting Started
First, you'll need to build and run the GNOME Shell on your system. Next, you should find the gnome-shell/source/gnome-shell/js/ui directory and review one of the files there. panel.js can be a good candidate. An effort to add JavaScript documentation for GNOME Shell can be found here and an earlier version of panel.js has been documented here.
Some of the GNOME Shell functions that are called in JavaScript are implemented in C due to the limitations of what can currently be accessed from JavaScript and can be found in the gnome-shell/source/gnome-shell/src directory.
The GNOME Shell Style Guide and the Gjs Style Guide it defers to explain a lot of patterns that can be found in the GNOME Shell JavaScript code. You need to be familiar with the GNOME Shell style guidelines before developing the code for it.
You can try making simple modifications in the JavaScript code and they should be in effect once you restart the shell. The information on how to restart the shell is here. You would need to run jhbuild shell (just once), make and make install in the gnome-shell/source/gnome-shell/src directory before restarting the shell if you make modifications in the C code. Alternatively, you can run jhbuild buildone -f -n gnome-shell in that case.
Once you are familiar with the gnome-shell source tree and the style guidelines, you can select one of the bugs with the "gnome-love" keyword in Bugzilla or come up with your own idea for a patch and discuss it on IRC.
Once you have a patch, you need to attach it to the existing bug or create a new bug report in GNOME Bugzilla for the 'gnome-shell' product describing your change and attach the patch to it. The patch will be reviewed, and once all the comments are addressed it will be committed to the common repository. See this guide on creating and using patches in the GNOME Shell development process for more details.
Git Version Control
The GNOME Shell uses Git as its version control system. The initial e-mail about GNOME Shell moving to Git has useful links and information for learning Git.
This Git by Example document has some Git usage examples that came up during the GNOME Shell development, such as how to review a file history, how to use git stash, how to work with a remote branch, and how to apply a conflicting patch.
Running GNOME Shell
To open a nested gnome-shell session in Wayland do:
dbus-run-session -- gnome-shell --nested --wayland
This allows useful set ups such as multimonitor and different scales, for example, to run two monitors with a DPI scale of 1 for the first and DPI scale 2 for the second:
dbus-run-session -- env MUTTER_DEBUG_NUM_DUMMY_MONITORS=2 MUTTER_DEBUG_DUMMY_MONITOR_SCALES=1,2 gnome-shell --nested --wayland
Resolution of each can be adjusted in the GNOME control center inside the generated window with the new session.
Clutter and Tweener
The GNOME Shell uses Clutter to lay out its graphical components.
Documentation on how to subclass ClutterActor helps understand size allocation, paint, and pick in Clutter.
The GNOME Shell has a custom Clutter-based toolkit called St (Shell Toolkit) that defines useful actors. Some of these actors, such as StBoxLayout and StBin implement various layout options. The code for these actors can be found in gnome-shell/source/gnome-shell/src/st St was initially based on Moblin User Experience toolkit Mx and we are trying to keep the code for the two toolkits in sync as it suits the development of both projects.
Some interactive tests that show off various capabilities of the St toolkit can be found in gnome-shell/tests/interactive You can run them like this: jhbuild run ../run-test.sh box-layout.js
Initially, a custom Clutter actor called Box that provided useful layout options for its components was used widely throughout the GNOME Shell code and you might come across its usage. The properties and functions it has can be found in gnome-shell/source/gnome-shell/src/big/box.c The St actors should be used for the new code instead.
The GNOME Shell does not use Clutter animation framework, but uses Tweener instead.
CSS
GNOME Shell uses CSS theming, which makes it easy to try out various UI changes or add new themes. The file that contains the GNOME Shell css is gnome-shell/source/gnome-shell/data/theme/gnome-shell.css
JavaScript
Mozilla JavaScript Resources page contains a wide selection of JavaScript documentation.
Gjs Wiki has a thorough overview of GObject usage in JavaScript and Modules included with Gjs
Gnome API Documentation is available for the Gnome JavaScript bindings
Gjs Style Guide explains a lot of patterns that can be found in the GNOME Shell JavaScript code.
Extensions
GNOME Shell exensions system allows creating extensions that contain arbitrary JavaScript and CSS code that is loaded on shell start-up. Get started writing an extension now!
Looking Glass
Looking Glass is GNOME Shell's integrated inspector tool and JavaScript console useful for debugging. It can be run by typing 'lg' in the Alt+F2 prompt.
Developer Shortcuts
GNOME Shell cheat sheet lists some shortcuts useful for developing GNOME Shell.
Debugging
This page has information on how to debug GNOME Shell.
Recovering from a Freeze
If your gnome-shell froze, switch to a text virtual terminal (e.g. with Ctrl+Alt+F2), log in there, type 'DISPLAY=:0 gnome-shell'. and switch back to the graphic virtual terminal (e.g. with Ctrl+Alt+F1). This will restart the system version of gnome-shell.