User:Jdlrobson/Extension:Gadget/Policy

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 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 wiki-based code developers.

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

Together, we should determine a policy that works for both Wikimedia staff and wiki-based code 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 wiki-based code. Examples: A wiki-based code 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
 * Wiki-based code 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 wiki-based code 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 wiki-based code 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 wiki-based code and is subject to the rules of the Stable interface policy. Wiki-based code developers are encouraged to use these libraries, but MUST pay attention to any deprecation warnings in JavaScript console.
 * Wiki-based code 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.
 * Wiki-based code 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.
 * Wiki-based code 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. Wiki-based code developers MUST cater for the situation where these elements do not exist.
 * Wiki-based code SHOULD not use global scope where possible, to make it easier for other JavaScript developers to debug where errors originate.
 * At the top of wiki-based code, the maintainers MUST be listed, so that when there is a problem it is clear who needs to be talked to. If wiki-based code 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

 * Wiki-based code developers SHOULD provide their own CSS for styling their code and SHOULD NOT rely on MediaWiki HTML classes provided by the software. In certain cases it might make sense for wiki-based code 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 wiki-based code developers MUST file a Phabricator ticket to make sure this is documented.
 * Wiki-based code 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 wiki-based codedevelopers.
 * Wiki-based code 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 wiki-based code 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 wiki-based code 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 wiki-based code stable policy:
 * Changes to HTML structure. Wiki-based code 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 wiki-based code stable policy.
 * When code is considered part of the wiki-based code 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 wiki-based code developers to raise any concerns relating to the change, but ideally 1 release.
 * Wiki-based code developers SHOULD follow Project:Tech_News to learn about upcoming deprecations.

Maintaining code and error handling

 * Client side errors occurring in wiki-based code are tracked alongside errors on Grafana and can be explored further inside our logstash instance.
 * MediaWiki developers MUST fix 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.
 * MediaWiki developers MAY fix 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 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.
 * Wiki-based code MAY opt out of error tracking by the guidelines given on wikitech:Client error
 * Wiki-based code 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 wiki-based code by creating a Phabricator ticket in #Instrument-ClientError