User:Jdlrobson/Extension:Gadget/Policy

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

On top of this, when gadgets break it's not clear who can and will fix them.

Together, we should determine a policy that works for both Wikimedia staff and gadget developers to lead to a better experience for both parties and try to restore trust and good faith between the two parties.

To contribute to the policy please use the discussion page to raise concerns, suggestions, removals or additions.

See https://datatracker.ietf.org/doc/html/rfc2119 to understand the language used in this policy to Indicate Requirement Levels.

Problem statement
MediaWiki engineers follow the Stable interface policy. However, currently CSS and HTML is not subject to this policy as they cannot be deprecated in the same way as JavaScript and PHP.

A few problems have arisen in the development of skins because of this:


 * Developers make HTML changes that break gadgets. Examples: A gadget uses an element ID to insert itself into the page and that ID is changed, or the HTML is refactored by engineers for better maintainability leading to unexpected consequences on code assuming the old HTML structure.
 * Developers moving CSS to improve page performance, inadvertently break wikitext that assumes it exists. Example
 * Gadget developers make assumptions about CSS availability based on desktop, leading to display problems on the mobile site.
 * Editors MAY edit MediaWiki:Common.js or site-wide gadgets and introduce unchecked errors leading to bugs that impact high volumes of users. Examples: https://phabricator.wikimedia.org/T291512, Japanese gadget

Recommended solution
To solve this a policy is recommended to make the contract between MediaWiki developers and gadget developers explicit.

JavaScript

 * Code SHOULD be loaded to a page by the `mw.loader.load` method. Methods such as `importScript` are not officially supported by the MediaWiki software and may break in future. See ResourceLoader/Migration_guide_(users) for more information.
 * Code inside the `mw` object can be used by gadgets and is subject to the rules of the Stable interface policy. Gadget developers are encouraged to use these libraries, but MUST pay attention to any deprecation warnings in JavaScript console.
 * Gadget developers SHOULD NOT assume that certain HTML structures and classes that are used now will be used in future and are encouraged to request explicit APIs for absent use cases.
 * For example, menu items SHOULD be added via the `mw.util.addPortletLink` method. Any menu items added via other mechanisms e.g. $('').appendTo('#p-personal ul li") is not supported and is prone to future breakage.
 * Gadget developers when accessing and enhancing a specific element in the DOM MUST use ID attributes or `mw-` prefixed classes where available and cater for the situation where the element does not exist.
 * Gadget developers MAY enhance elements without IDs or `mw-` classes but when doing so must know this is done at their own risk as these elements are not subject to the deprecation policy. Gadget developers MUST cater for the situation where these elements do not exist.
 * Gadget and user scripts developers SHOULD not use global scope where possible, to make it easier for other JavaScript developers to debug where errors originate.
 * At the top of the gadget, the maintainers MUST be listed, so that when there is a problem it is clear who needs to be talked to. If a gadget is in the user namespace, the user MUST be considered as the maintainer.
 * 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.

CSS

 * Gadget developers SHOULD provide their own CSS for styling their gadgets and SHOULD NOT rely on MediaWiki HTML classes provided by the software. In certain cases it might make sense for gadget and MediaWiki developers to share code, but this MUST be documented in the code using a @public keyword per the Stable interface policy. If the code is not documented gadget developers MUST file a Phabricator ticket to make sure this is documented.
 * Gadget developers MAY override existing CSS rules for content generated by wikitext e.g. thumbnails
 * MediaWiki developers MAY change default CSS for content generated by wikitext provided they go through the deprecation policy.
 * MediaWiki developers MUST prefix their CSS classes with "mw-" to avoid namespace clashes with gadget developers.
 * Gadget developers MUST NOT introduce or use CSS classes prefixed with "mw-" to avoid namespace clashes with MediaWiki developers. They SHOULD instead prefix CSS classes with "mwgadget-" where possible.

Communication / Deprecation policy

 * Code considered part of the gadget stable policy:
 * All classes that are generated by wikitext without the use of a template e.g. `.wikitable` MUST be subjected to the stable deprecation policy. Any other HTML classes provided by the interface are NOT subject to the deprecation policy.
 * HTML IDs MUST be subjected to the deprecation policy on the understanding that gadget developers should be catering for the situation where they do no exist.
 * Classes that are prefixed with "mw-".
 * Code that is not considered part of the gadget stable policy:
 * Changes to HTML structure. Gadgets should not make assumptions about how existing interface code is structured. For example, the dropdown menus in Vector. MediaWiki developers should provide APIs where required to abstract this away where needed.
 * Classes that are not generated by wikitext (see above) and not prefixed with `mw-` are not subject to the gadget stable policy.
 * When code is considered part of the gadget stable policy:
 * If the ID or class is in use in any skin or extension that shows up on Codesearch, it's coming removal SHOULD be noted in RELEASE_NOTES before removal.
 * In the case of renaming classes, the new class MUST be added along with the removed class for 1 MediaWiki release.
 * In the case of renaming IDs an inline comment should be added to the HTML output introducing the HTML marking the ID as unstable and mentioning the new ID. e.g.
 * MediaWiki engineers MUST notify Project:Tech_News prior to making a change to CSS and HTML code covered by the stable policy.
 * The message MUST mention "BREAKING CHANGE" and provide steps to resolve the problem. A period of at least two weeks must be given for gadget developers to raise any concerns relating to the change, but ideally 1 release.
 * Gadget developers SHOULD follow Project:Tech_News to learn about upcoming deprecations.

Maintaining code and error handling

 * Client side errors occurring in gadgets are tracked alongside errors on Grafana and can be explored further inside our logstash instance.
 * MediaWiki developers MUST fix gadget 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.
 * MediaWiki developers MAY fix gadget 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 disable gadgets that are broken provided the edit summary documents how the issue can be fixed.
 * MediaWiki developers MAY run bots to fix multiple gadgets where resolution is straightforward.
 * Gadget/script developers MAY opt out of error tracking by the guidelines given on wikitech:Client error
 * Gadget/scripts in the user namespace of a retired or blocked user MUST BE blanked as they are no longer maintained. They MAY be forked to other places (e.g. MediaWiki namespace, another user namespace) where the maintainer is clear.
 * Volunteers MAY request anonymized data from WMF staff and other engineers with NDA about errors coming from their gadgets by creating a Phabricator ticket in #Instrument-ClientError