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.

These rules also apply to code in the top-level of any JavaScript files or imports in your extension. Code not in a function or class definition will be executed when your extension is loaded and therefore can not be reverted later.

Do...

  • Setup gettext translations
  • Register GResources
  • Store functions and methods you plan on overriding

Don't...

  • 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.

Do...

  • Disconnect all signals
  • Unbind all properties
  • Destroy all objects created in enable()

  • Destroy all GSources, such as those created with GLib.timeout_add()

Don't...

  • 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

Licensing

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.

Tips

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.

It may be convenient to run the ESLint rules on your code that the gnome-shell-extensions package runs as a CI job. You can find those in the lint/ directory on GitLab.

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

Getting Help

There are several ways for you to get help with your extension.

Projects/GnomeShell/Extensions/Review (last edited 2020-07-04 21:31:59 by AndyHolmes)