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, volunteer contributors (on Gerrit and Github) 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.

Problem statement
MediaWiki engineers follow the Stable interface policy for PHP. However, currently CSS JavaScript and HTML is not subject to this policy. The policy drafted here, sets expectations between developers of MediaWiki and of on-wiki code.

A few problems have arisen in the development of MediaWiki frontend code in the absence of this policy:


 * 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. Example
 * Editors 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.

Definitions

 * 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 it's extensions or skins.

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.
 * Code that MUST be protected by the wiki-based code stable policy:
 * All HTML classes that are generated by the wikitext parser e.g. `.wikitable, .external` 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. #mw-category-media, #mw-content-text) 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. An HTML ID CAN be changed provided they follow the associated deprecation steps.
 * Code that SHOULD NOT be protected by 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.
 * HTML classes that are not generated by wikitext without the use of transclusion (see above), including classes prefixed with `mw-` SHOULD NOT be subject to the wiki-based code stable policy unless stated.
 * HTML classes that do wish to be considered stable MUST add an inline comment indicating for what MediaWiki versions they were introduced using a @since annotation and must follow the deprecation policy.
 * HTML IDs introduced inside extensions or skins SHOULD NOT be subject to the wiki-based code stable policy unless stated.

JavaScript

 * Code MUST be loaded to a page by the `mw.loader.load` method. Methods such as `importScript` are deprecated, not officially supported by the MediaWiki software and may break in future. See ResourceLoader/Migration guide (users) for more information.
 * Wiki based code SHOULD be loaded from a Wikimedia owned domain e.g. hosted on a project OR a cloud VPS instance.
 * Depending on T296847 this could change to MUST in future.
 * 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 any available libraries, but wiki-based code MUST act on any deprecation warnings in JavaScript console to avoid breaking, being disabled or edited by other developers at a future point in time.
 * 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.
 * Code SHOULD NOT use deprecated libraries such as jQuery.UI.
 * 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 MAY enhance elements 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 MUST cater for the situation where these elements do not exist.
 * MediaWiki developers MUST regularly review popular gadgets to evaluate missing APIs. MediaWiki developers MAY do this as part of their planning process, and MUST do this in situations where a gadget developer raises a Phabricator ticket based on a breakage surfaced in a Village pump technical discussion.
 * 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 SHOULD be listed, so that when there is a problem it is clear who needs to be talked to. Alternatively this can be documented on the talk page. In the absence of such information, for wiki-based code is in the user namespace, the user SHOULD be considered as the maintainer. If the user is retired, the script should be forked to another location e.g. MediaWiki namespace. When necessary, MediaWiki developers CAN consult the revision history to see who to contact, or go through Village Pumps, make protected edit requests, for non-urgent matters.
 * All new MediaWiki code deployed to Wikimedia wikis SHOULD consider support for on wiki code a stable way to access its most important elements.

CSS

 * Wiki-based code SHOULD provide their own CSS for styling their features and SHOULD NOT rely on MediaWiki HTML classes provided by the software to style their features, even if this results in duplicated CSS. In certain cases it might make sense for wiki-based code and MediaWiki developers to share code, but this MUST be documented in the source-controlled 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 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 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 their CSS classes with "mw-" to avoid namespace clashes with wiki-based code developers. Wiki-based code SHOULD NOT assume that the use of a `mw-` prefix indicates a stable API.
 * 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 `vector-`, for Extension:AbuseFilter uses ` `
 * Wiki-based code MUST NOT introduce or use CSS classes prefixed with "mw-" to avoid namespace clashes with MediaWiki developers. It SHOULD consider prefixing CSS classes with context about the code's origin e.g. "mwgadget-" / "twinkle-" where possible but not in a way that creates name clashes with other extensions or skins.

Communication

 * MediaWiki engineers SHOULD assess the impact on gadgets when changing interfaces regardless of whether it is covered by the wiki-based code policy.
 * MediaWIki engineers SHOULD use feature flagging in roll outs where possible to allow editors to test interfaces prior to development.
 * MediaWiki engineers SHOULD notify Project:Tech_News prior to making a change to CSS and HTML code which is not covered by the stable policy where they are aware of breakage.
 * 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.
 * Wiki-based code developers SHOULD follow Project:Tech_News to learn about upcoming deprecations.

Deprecation policy

 * When code is considered part of the wiki-based code stable policy:
 * If possible, the method mw.log.deprecate 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.
 * MediaWiki engineers MUST notify Project: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.
 * The coming removal of class or ID that has been documented as @stable 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 MUST be added to the source code. It MAY be added to the HTML output introducing the HTML marking the ID as unstable and mentioning the new ID. e.g.
 * All Wikimedia deployed code MUST be updated to cater for the old and new IDs prior to the removal of the old ID.
 * 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 https://en.wikipedia.org/wiki/Wikipedia:User_scripts/Most_imported_scripts to decide a suitable timeframe for the deprecation.
 * For changes that impact more than 10 gadgets and/or 1000+ user scripts, MediaWiki engineers MUST notify Project:Tech_News prior to making a change covered by the stable policy.
 * A period of at least two weeks MUST be given for wiki-based code developers to respond and raise any concerns relating to the change.

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 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.
 * Wiki-based code MAY opt out of error tracking by the update guidelines given on wikitech:Client error.
 * Wiki-based code in the user namespace of a retired or blocked user SHOULD be blanked by MediaWiki developers or a site admin when no longer maintained to mitigate the likelihood of security, stability or privacy issues occurring in future. 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