Stable interface policy/Frontend

The stable interface policy for MediaWiki frontend code (CSS, JavaScript and HTML) defines what parts of the software are considered stable and safe for use by other components. Code that is considered part of this "stable interface" is subject to the deprecation process. For guidelines on PHP please see Stable interface policy. It is currently kept as a separate document given the audience is different, particularly given its unique requirement to gadget developers. The eventual goal is to move this to Stable interface policy/frontend.

While this documentation is in draft please feel free to dive into the talk page to debate any aspect of this code.

This document is complemented and supported by a set of recommendations for developers of on-wiki code.

Terminology

 * See https://datatracker.ietf.org/doc/html/rfc2119 to understand the language used in this policy to Indicate Requirement Levels.
 * "Wiki-based code" is defined as code that executes on Wikimedia projects, who's source code lives inside a page that is editable on wiki.
 * A "MediaWiki developer" is defined as someone who contributes code to the MediaWiki code repository or one of its extensions or skins.

HTML markup (ID and class attributes)
HTML should generally not be considered a stable interface. It should be acceptable to make changes to HTML structure, or rename classes and IDs, however it is important to communicate those changes to gadget developers.


 * Code that MUST be communicated to developers via the communication process
 * All HTML classes prefixed with generated by MediaWiki core. Note, Code outside MediaWiki core, should not use the mw- prefix as it can confuse gadget developers by suggesting a stable API.
 * All HTML classes that are generated by the wikitext parser e.g.,   MUST be subjected to the stable deprecation policy.
 * NOTE: HTML classes provided by other parts of the software (e.g. sidebars/menus, special page content) or being defined in the wikitext source (e.g. ambox, infobox) are NOT subject to the deprecation policy.
 * HTML IDs generated by code that lives inside MediaWiki core (e.g.,  ) MUST be subjected to the deprecation policy on the understanding that wiki-based code SHOULD be catering for the situation where they do no exist.
 * Code that SHOULD NOT be protected by the wiki-based code stable policy and do not need to follow the deprecation policy:
 * Changes to HTML structure.
 * MediaWiki developers SHOULD provide APIs if this is likely to break gadgets.
 * Classes introduced by skins or extensions
 * HTML IDs and classes introduced inside extensions or skins SHOULD NOT be subject to the wiki-based code stable policy unless stated. In cases where it might make sense for wiki-based code and MediaWiki developers to share code, this MUST be documented in the source-controlled code using a  and  keyword. HTML classes that do wish to be considered stable MUST add an inline comment indicating for what MediaWiki versions they were introduced using a   annotation and must follow the deprecation policy.
 * MediaWiki developers MAY change default CSS for content generated by wikitext provided they follow the communication guidelines in communication / deprecation policy section. This does not require going through the deprecation policy.

MediaWiki developers and wiki-based code MUST NOT share CSS classes


 * MediaWiki developers MUST prefix CSS to avoid namespace clashes with wiki-based code developers.
 * MediaWiki developers SHOULD ensure legacy classes are preserved while moving to their  prefixed equivalent for example  and
 * Extension/skin developers MUST prefix their CSS classes to avoid namespace clashes with wiki-based code developers.
 * Extension/skin developers MUST use a unique prefix e.g. for Skin:Vector use, for Extension:AbuseFilter use
 * Wiki-based code MUST NOT introduce or use CSS classes prefixed with  to avoid namespace clashes with MediaWiki developers. It SHOULD consider prefixing CSS classes with context about the code's origin e.g.   /   where possible but not in a way that creates name clashes with other extensions or skins.

JavaScript and ResourceLoader

 * Code that MUST be protected by the wiki-based code stable policy and follow the deprecation policy:
 * Code inside the public  object
 * Hooks fired using the  object
 * Wikimedia developers SHOULD regularly check the JavaScript console for deprecation notices and warnings.
 * Code creating complex UIs SHOULD use Vue.js and MUST follow any guidance that appear in the JavaScript console to maintain compatibility.
 * Code written in OOUI MUST follow any guidelines in the JavaScript console.
 * MediaWiki developers MUST regularly review popular gadgets to evaluate missing APIs using the global-search tool. MediaWiki developers MAY do this as part of their planning process, and MUST evaluate the use case in situations where a gadget developer raises a Phabricator ticket after an incident has occurred (for example: in a situation where a popular gadget breaks)
 * All new MediaWiki code deployed to Wikimedia wikis SHOULD consider support providing on-wiki code a stable way to access its most important elements.
 * All ResourceLoader modules inside MediaWiki core MUST be considered stable unless marked as deprecated.
 * Code SHOULD NOT use ResourceLoader modules using the deprecated tag. e.g. jQuery.UI.

Deprecating ResourceLoader modules

 * When deprecating a ResourceLoader module, set the deprecated key on the associated ResourceLoader. When deprecating in this manner, the developer MUST document the deprecation in RELEASE_NOTES and mention the release number in which it was deprecated.
 * The software MUST log hard deprecation warnings in this manner for at least one MediaWiki release. When removed, this should also be documented in RELEASE_NOTES.
 * Communicate the change to gadget developers (see Communicating changes to gadget developers)

Deprecating code on public mw object or hooks

 * If possible, the method  should be used to deprecate an API. The deprecation message should state the release in which the deprecation happened. When deprecating in this manner, the software MUST log hard deprecation warnings for at least one MediaWiki release.
 * Communicate the change to gadget developers (see Communicating changes to gadget developers)

Changing HTML markup

 * When code is not part of the wiki-based code stable policy, MediaWiki engineers MUST still assess impact of their change based on the popularity of the gadget e.g. Special:GadgetUsage and en:User scripts/Most imported scripts to decide a suitable timeframe for the change. The timeframe should be at least 1 month, but may warrant longer in some cases. This can be skipped if engineers are confident that gadgets will not be impacted.
 * For changes that impact more than 10 gadgets and/or 1000+ user scripts, MediaWiki engineers MUST notify m:Tech/News prior to making a change covered by the stable policy.
 * A period of at least one month MUST be given for wiki-based code developers to respond and raise any concerns relating to the change (see Communicating changes to gadget developers) regardless of MediaWiki release.
 * In the case of renaming IDs where the class might be mistakenly considered stable per Definition of the stable interface, developers SHOULD consider a longer grace period.
 * Wikimedia engineers MUST consider any feedback from gadget developers to minimize disruption (for example introducing APIs where missing)
 * In the case of renaming classes, where the class might be mistakenly considered stable per Definition of the stable interface, the new class MUST be added along with the removed class for 1 MediaWiki release. An inline comment should indicate which release the old class was deprecated.
 * All Wikimedia deployed code MUST be updated to cater for the old and new IDs/classes prior to the removal of the old ID given cached HTML may be served alongside new CSS.

Handling errors in gadget code
Client side errors occurring in wiki-based code are tracked alongside errors in Wikimedia code on Grafana and can be explored further inside our logstash instance. When making breaking changes, despite good intentions it is inevitable even with good communication that some scripts will not be updated and the change will lead to production errors.


 * MediaWiki developers MUST fix or disable error logging for any wiki-based code and/or user script errors with error volumes that trigger alerts via Wikimedia alerting systems. Having healthy metrics helps us have more confidence when we deploy code. Ideally the fix SHOULD be made by the maintainer of the code after discussion on the script's talk page, however in time sensitive situations MediaWiki developers MAY take action themselves if they feel comfortable doing so.
 * MediaWiki developers MAY fix or disable wiki-based code and/or user script errors that undermine user privacy. For example, if an active user is triggering an error on every page load, which reveals their page history, you are encouraged to fix it.
 * MediaWiki developers MAY fix or disable wiki-based code that are broken provided the edit summary documents how the issue can be fixed.
 * MediaWiki developers MAY run bots to fix multiple wiki-based code where resolution is straightforward.

Communicating changes to gadget developers
MediaWiki engineers MUST notify m:Tech/News prior to making a change covered by the stable policy. The phabricator ticket title MUST mention "BREAKING CHANGE" and provide steps to resolve the problem inside the description


 * MediaWiki engineers SHOULD use feature flagging (e.g. Extension:BetaFeatures or user preferences) in roll outs where possible to allow editors to test interfaces prior to development.
 * MediaWiki engineers when learning about the breakage of gadgets on-wiki that is not covered by the wiki-based code policy MUST assess the inclusion of a new API to reduce future breakage.

Motivation
This policy is designed to make extensions more robust against changes in MediaWiki core, and provide more freedom for MediaWiki core code to evolve.

The motivation for this policy is two-fold:


 * Offer guarantees to gadget developers and extension developers, providing guidance on what aspects of MediaWiki core they can safely rely upon.
 * Provide guarantees to developers working on MediaWiki core, telling them what aspects of the code they can safely change without having to worry about breaking extensions.

Scope
The scope of this policy is for code that runs on one of the Wikimedia projects. It does not apply to third party instances

Ecosystem
Despite gadgets and user scripts (which will be referred from now on as wiki-based code) being a key component of MediaWiki projects, up until now frontend APIs (e.g. how wiki-based code should interact with source control provided code) have been ill-defined leading to misunderstandings between engineers and wiki-based code developers when wiki-based code breaks. This also leads to code rot, where developers do not feel empowered to make changes as it's unclear how their changes will impact wiki-based code developers.

On top of this, when wiki-based code breaks it's not clear who can and will fix them.

This document aims to build agreements between Wikimedia staff, volunteer contributors (on Gerrit and Github) and wiki-based code developers to lead to a better experience for both parties and build trust and good faith between the two parties.

History

 * [August 2021] This document began life in User:Jdlrobson/Extension:Gadget/Policy. It was advertised on wikitech-l and received input from gadget developers as well as MediaWiki developers.
 * [January 2023] Document was separated into User:Jdlrobson/Stable_interface_policy/frontend and Recommendations for gadget developers