Requirements and tips for getting your GNOME Shell Extension approved
GNOME Shell extensions are patches applied during runtime that can affect the stability and security of the desktop.
These requirements must be followed in order for your extension to be approved for distribution on extensions.gnome.org. Failure to meet these requirements will result in your extension being rejected.
If this is your first time writing an extension, consider starting with the Tutorial which includes many examples of how to write an extension that will be approved.
Don’t do anything major in init()
init() is called by the extension subsystem when your extension is loaded by GNOME Shell, not when it is enabled. Your extension MUST NOT create any objects, connect any signals or modify any aspect of GNOME Shell here.
- Setup gettext translations
- Register GResources
- Store functions and methods you plan on overriding
- Connect any signals
- Bind any properties
- Override any functions
- Create any objects
Add any mainloop sources such as with GLib.timeout_add()
Undo all modifications in disable()
disable() is called in number of situations such as:
- when a user logs out
- when the screen lock engages
- when an extension is uninstalled or updated
- when and extension is disabled manually by a user
Failing to revert changes, such as removing UI elements created in enable(), can cause them to remain on the login and lock screen resulting in a security risk for the user. This is the most common reason extensions are rejected.
- Disconnect all signals
- Unbind all properties
Destroy all objects created in enable()
Destroy all GSources, such as those created with GLib.timeout_add()
- Simply hide UI elements instead of destroying them
- Leave any GSources or pending callbacks which may call back to destroyed objects
External Scripts and Binaries
Use of external scripts and binaries is strongly discouraged. In cases where this is unavoidable for the extension to serve it's purpose, the following rules must be adhered to:
- No binary applications or libraries may be included an extension
- Scripts must be short, simple and GPLv2+
- Processes must be spawned carefully and exit cleanly
During the submission process, you are asked to confirm that your extension can be distributed under the terms of the GPLv2+. If your extension includes headers or a LICENSE file containing another license, such as BSD/MIT, you approving GNOME to distribute your extension under an additional license.
If you would like to make your code available under more than one license, please explicitly license your code for both.
GNOME Shell extensions are reviewed carefully for malicious code, malware andsecurity risks, but are not reviewed for bugs or issues. The following sections are tips for common problem areas and getting your reviewed quicker.
Use consistent code style
Using consistent indentation and code style will make reviewing your extension easier and get your extension approved sooner.
By convention, most GNOME Shell extensions use the same code style used by GNOME Shell itself (see GNOME Shell's source for thorough exampless). If you choose a slightly different style, please be consistent.
Be cautious with GSettings
Programmer errors with GSettings are fatal in all languages and will cause a GLib application to exit. Since the code in your extension code is executed in the gnome-shell process, a fatal error will cause GNOME Shell to crash.
If the error happens when your extension is loaded or enabled, this can leave a user unable to log in, disable the extension or even ask for help.
- Test your usage of GSettings and avoid unsanitized user input
- Confirm settings schemas and keys are a part of the core GNOME desktop
Use Gio.SettingsSchemaSource.lookup(), Gio.SettingsSchemaSource.has_key()
- and other relevant functions to when you need dynamic behaviour
There are several ways for you to get help with your extension.