Page MenuHomePhabricator

Introduce global registry for gadget module identifiers
Open, MediumPublic


On mw: (or meta:) wiki a wikitext page shall be established, where every gadget (mostly javascript, but sometimes CSS only) may be registered.

  • Gadget identifiers are components of the RL module ID ext.gadget.exampleTask
  • Global gadget identifiers are also reserved for the following purposes:
    • mw.libs.myNiceGadget = { };
    • mw.hook( "myNiceGadget.ready" )
    • mw.user.options.get( "userjs-myNiceGadget" )
    • "myNiceGadget" )
    • sessionStorage.getItem( "myNiceGadget" )
    • href="#mynicegadget-top"
    • class="mynicegadget-heading"


  • Name conflicts shall be avoided, which may easily arrive from naming a script according to its functionality.
  • If someone on wiki-A develops a script to solve thisTask, the script will get this name. If someone else was programming an entirely different approach to solve the same problem on wiki-B, that might be named thisTask as well. If one day a global gadget repository will be created, it becomes entirely confusing for someone in wiki-A: Which one is in effect now? The local script? Or the global one, which might be a third implementation to provide thisTask in a more secure and performant manner, with more features and different configuration.
    • Different implementations of CollapsibleNav might be in the world.


Suggested Rules

  • Every user is free to create an entry in the registry, claiming the sole use of this identifier forever.
    • A documentation page is mandatory.
      • The documentation page is linked from the registration entry.
      • A link to the source code with some comment lines about the purpose is not sufficient.
      • The documentation page has to tell who might use that gadget for which purpose and which effects, possible risks, side effects and other circumstances are interesting to the user. If possible, examples, screenshots etc. should be included.
  • The code has to exist, left baby shoes and is in multi-user operation on any WMF wiki, serving any purpose within the WMF project targets.
  • The code is to be provided on a page under full control of the WMF.
    • Any user page in any WMF wiki is matching this requirement.
  • Identifiers might be registered even if the gadget is applicable for one wiki project only, since that one should avoid collision with a global identifier, too.
  • Reserved names might be removed again if within a couple of weeks it turns out that the requirements above were not met.
    • Once an identifier was established, it must not be deleted.
    • However, it can be stroke and a caveat may be applied, if the code shows persistent security gaps, does not work any longer and is not maintained either.

Suggested Naming

  • There is no full naming convention, but considerations of interoperability and long-term aspects.
    • Identifier shall consist of ASCII characters only.
    • They must not contain dots etc. like .,:;'"/ nor spaces.
    • They should use letters a-z, A-Z and digits 0-9 only.
    • First character is supposed to be a lowercase letter.
    • Lowercase camel casing is recommended.
    • Keywords of programming languages (reserved words in JavaScript) like switch or continue are not permitted as sole identifiers.
    • No database name of any current WMF wiki or such generated according to composition rules in future must be used as global gadget identifier.
    • Also the single words action agora cologneblue common commons console css echo error file flow global history ime javascript jquery js json language load loader log lua media mediaviewer mediawiki meta mobile modern module monobook mw notifications page preferences project qunit resource skin standard storage super template title uls url user util utility utl ve vector view viewer watchlist wikia window $ and similar.
    • No existing (PHP) extension name shall be used for other purposes.
      • The PHP extension may use this identifier for client side stuff.
    • An obvious user nick (even more other than the developer) should not be used.
      • The gadgets shall be maintained by followers in eternity and should not carry a personal burden.
    • In general it might be a good idea to compose the identifier from multiple words, preferrably English, e.g. verb and noun, and combine them by lowercase camel casing.
    • The identifier shall give a first clue on functionality. Abbreviations should be avoided.
  • The uniqueness of identifiers does not depend on casing. That means: If all identifiers are downcased, there is still no name conflict.
  • Once an identifier has been reserved, maintainers are free to subclass them by appending a dot . and anything they want.

Event Timeline

PerfektesChaos raised the priority of this task from to Needs Triage.
PerfektesChaos updated the task description. (Show Details)
PerfektesChaos added a project: JavaScript.
PerfektesChaos added a subscriber: PerfektesChaos.

It is a kind of prerequisite.

However, registration (claiming) of a unique WMF-global identifier does not require that anything becomes part of any repository, or that something would be appreciated by any global repo with reliable content.

It is simply the reservation of a particular name and provides a traceback link to a certain documentation page.

Probably related to T1238, but shared Gadgets has been taken out of scope for T31272.

IMPORTANT: If you are a community developer interested in working on this task: The Wikimedia Hackathon 2016 (Jerusalem, March 31 - April 3) focuses on #Community-Wishlist-Survey projects. There is some budget for sponsoring volunteer developers. THE DEADLINE TO REQUEST TRAVEL SPONSORSHIP IS TODAY, JANUARY 21. Exceptions can be made for developers focusing on Community Wishlist projects until the end of Sunday 24, but not beyond. If you or someone you know is interested, please REGISTER NOW.

Within the recent five years two more aspects arrived:

  1. CSS selectors
  2. TemplateStyles

Both are affecting elements of the same HTML pages, e.g. in etc. Since they interfere, the global registry of package identifiers needs to be extended and includes canonical names for:

  • JavaScript gadgets (may contain stylesheet resources)
  • CSS gadgets (CSS only)
  • Global Lua modules
  • Global templates
  • MediaWiki PHP Extensions

While gadget IDs are supposed to begin with lowercase letter, template and module names may use a capital letter. As the payload is case-independent, and CSS selectors will use lowercase letters only, casing does not influence unique identifiers derived from the canonical ID which is case sensitive.