Talk:Stable interface policy/Frontend

Archived topics:

• User talk:Jdlrobson/Stable interface policy/frontend/archive

Currently open topics:

• Improving our definition of popular gadgets Talk:Stable interface policy/Frontend#h-Improving_our_definition_of_popular_gadgets-20230804221800
• Consider replacing @stable tag with a different approach to public documentation Talk:Stable interface policy/Frontend#h-Consider_replacing_@stable_tag_with_a_different_approach_to_public_documentation-20230802181300
• Proposal for using `mw-stable-` prefix for classes that can be considered stable Talk:Stable interface policy/Frontend#h-Proposal_for_using_`mw-stable-`_prefix_for_classes_that_can_be_considered_stable-20230804221400
• Mailing list for announcements Talk:Stable interface policy/Frontend#h-Mailing_list_for_announcements-20230712162300
• Making amendments to this document Talk:Stable interface policy/Frontend#h-Process_for_making_amendments-20230915220500
• Feedback request for accessing DOM elements Talk:Stable interface policy/Frontend#h-Some_confusion_around_guidance_to_accessing_DOM_elements-20230915213500
• Approach to deprecating modules Talk:Stable interface policy/Frontend#h-Should_we_do_more_before_deprecating_modules?-20230915211900

Making the API Tighter

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

It's fairly clear that the somewhat loose contract in place between the page and the javascript is going to be unsustainable going forward. It's likely to create impasses where MediaWiki developers are going to be concerned about breaking Gadgets and Gadget writers are going to have to worry about MediaWiki changes breaking their functionality. To that end, tightening the contract seems like an excellent approach.

The question I'd like to ask is how tight should this be? Why not just take the top N uses of gadgets and simply build them as first class features? In cases where the community just wants collapsible tables or something, that might be worth supporting as a wikitext feature, but if it's more niche, perhaps the API should be more than the DOM itself? For instance said API could cover everything right from how the gadget obtains information about the page, and how it returns decorated DOM elements and some specification around where it is to be inserted. In other words, we should make it impossible for gadgets to insert arbitrary content into the page, and instead restrict / structure this through APIs.

It's going to be a lot more work on our end, and it'll require a lot of analysis of existing JS gadgets and picking and choosing which ones to build into the platform, which ones to offer an API for, and which ones to simply stop supporting. But it's at least a path forward where we can be sure that gadget and MediaWiki development can continue without impeding each other. SCherukuwada (WMF) (talk) 19:39, 22 September 2021 (UTC)

Why not just take the top N uses of gadgets and simply build them as first class features? WMF does that and then development halts due to resourcing, or because the feature was built for one wiki but requires localizing both in language and in workflows to extend to other wikis. It hasn't been a good story for a few of the things that they've tried this for (Flow and PageCuration off the cuff), and even where an approximately same-thing was sufficiently developed like the navigation tooltips that were added a few years ago, the Navigation_popups gadget hasn't been updated to use that as a base for myriad reasoning (actually-ancient-like-almost-20-year-old script, needs-local-consensus to change the styling [yeah, I know], lots of content that's superfluous for the general reader so needs an option of its own anyway somewhere in Special:Preferences, no obvious extension API or a declined one).

but if it's more niche, perhaps the API should be more than the DOM itself I've thought about this in response to one or two tickets I've seen go by, but the issue is that we will always want more, and leaving some parts or all of the DOM outside the stability guarantee isn't going to help anything because we'll just add stuff ourselves to X or Y element. Making insertion impossible is just going to freeze all development; WMF can't resource quick enough for our needs/wants. Wiki means go fast :). (NB, more APIs in general so that certain uses are better-supported is probably better regardless.) Izno (talk) 23:29, 21 December 2021 (UTC)

I think a good example of this going wrong was Extension:WikidataPageBanner and Extension:Popups.

The former started on wiki with limitations but is not as well maintained by WMF as it could be.

The navigation popup gadget that inspired the extension is more editor focused so not applicable to most readers.

I think there's a balance here. We can reduce the need of gadgets (and the disadvantages of performance/privacy that come with using them) for the mainstream but we won't eradicate their usage altogether. Jdlrobson (talk) 22:16, 23 December 2021 (UTC)

disadvantages of performance/privacy For real gadgets (meaning using the Gadget extension interface), there is no issue for performance (maybe there could be some stuff moved to PHP), and little enough privacy issue what with interface administrator role now.

For user scripts, yes, of course those are both potential issues. Izno (talk) 22:52, 23 December 2021 (UTC)

Furthermore, how do we get the top X gadgets by views/deployment? So that we can see exactly how hard this job is? SCherukuwada (WMF) (talk) 19:41, 22 September 2021 (UTC)

Special:GadgetUsage exists; I assume you could get the data serverside/cross-wiki accordingly. Of course, not all successful gadgets are formal gadgets, for that you need to resort to counting uses as with e.g. en:Wikipedia:User_scripts/Most_imported_scripts. Izno (talk) 23:15, 21 December 2021 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Comments from Izno

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

I have several comments so I'm going to split them into separate replies. Izno (talk) 02:25, 22 December 2021 (UTC)

Problem statement

1. JavaScript does not currently follow the stable interface policy (which takes pains to indicate "PHP" in the lead sentence) and AFAIK doesn't have a deprecation policy anywhere. So 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. doesn't quite cast the right tone, which maybe has ripple effects in the rest of this document. I see that JavaScript is indeed discussed in the document....
2. Developers moving CSS to improve page performance, inadvertently break wikitext that assumes it exists. Example Yes, I agree this is a problem. Generally, my personal position has been that any CSS clearly marked as mw- is not within the realm of editors to use, play with, or assume anything about except where such is clearly indicated (as e.g. with mw-collapsible). Anyone doing anything else with class names from internal to the software has been playing with fire and users getting singed for their own decision making has probably been on them, IMO :). (See also the discussion in phab:T78176 and elsewhere; particularly where I point out at least one use of unsemantic naming possibly having a benefit for mobile efforts regarding floatright and friends.)
3. Gadget developers make assumptions about CSS availability based on desktop, leading to display problems on the mobile site. Yes, this also seems an issue; possibly a task to link here is phab:T280766. Izno (talk) 02:25, 22 December 2021 (UTC)

Policy: JavaScript:

1. Code SHOULD be loaded to a page by the mw.loader.load method. This probably should have a MUST given the 'native' alternatives are already currently deprecated. We're outlining here the contract for the future, not how much backward compatibility to provide for several-year-deprecated software.
2. MUST pay attention is weak or useless for a policy. What constitutes "paying attention"?
3. MUST use ID attributes That would seem not to fix the related item from the problem statement?
4. At the top of the gadget, the maintainers MUST be listed Reasonably aspirational I think.
5. If a gadget is in the user namespace, the user MUST be considered as the maintainer. MUST is not realistic.
6. Regarding the use of specific frameworks, consider whether it is appropriate to call those out or attempt to formulate something more generally. This document should be reasonably future-proof...
7. Separately, consider the frameworks (jQuery, jQuery.ui) not listed here. Izno (talk) 02:26, 22 December 2021 (UTC)

This loader policy cannot be a MUST. IIRC mw.loader is using minification that only supports ES5. importScript is better in that it doesn't brake code. Nux (talk) 16:39, 25 December 2021 (UTC)

1) I am pretty sure mw.loader.load can take ES6+ if it is loaded via its URL form rather than as a gadget module. 2) I don't think we should predicate the general policy on whether ES version N is loaded correctly by RL, which clearly needs adjustment on the point. Izno (talk) 22:09, 25 December 2021 (UTC)

Yeh any ES6 issues are out of scope. If mw.loader.load doesn't work for certain use cases that should be fixed. The important thing here is we need an agreed standard way of loading code. If there are too many methods, we're adding complexity.

I'm also wondering how much of this can be done inside the code: for example maintainer could potentially be part of the user interface.

Hoping to dig deeper into your feedback here next week. Jdlrobson (talk) 18:40, 14 January 2022 (UTC)

Complexity on mediawiki side, yes. importScript is a way easier API. That is why it is used. You don't have to remember all the attributes that need to be used etc. it just works. Nux (talk) 19:31, 14 January 2022 (UTC)

This proposed policy isn't about importScript at the end of the day, so I see that as essentially offtopic. Izno (talk) 19:34, 14 January 2022 (UTC)

You said a worse API SHOULD be used. I think first thing would be to make a new API better and then maybe deprecate old one. Nux (talk) 20:16, 14 January 2022 (UTC)

The "new" API is over a decade old. Moreover, it is not hard to know how to use it, and at the end of the day most people don't need to know the specifics of how it works. People who do can make a nice abstraction around it that looks like the current one if they need to, trivially. See for example en:User:Izno/common.css.

That's besides the point of what the word SHOULD means in the context of the relevant IETF RFC as linked in the lead of the proposed policy. Izno (talk) 21:33, 14 January 2022 (UTC)

Yes, everybody can add their own wrapper for the API... That doesn't make the API better. jQuery is even older so I don't know how age matters (or I don't understand your point). Better API is better API. Note that I'm not talking about what is going on under the hood. I'm all fine with re-implementing importScript with whatever as long as it works. Or maybe do mw.import() that can do js and css based on extension.

In any case my comment is not about what I can do for myself or even for whole plwiki, but rather about providing better, general developer experience. Nux (talk) 21:48, 14 January 2022 (UTC)

Sorry, come to think of it, jQuery is probably not older then importScript. Just older then mw.loader. Still, I don't think age really matters. Nux (talk) 21:53, 14 January 2022 (UTC)

At the end of the day, what you're requesting is offtopic to this discussion about what should happen going forward. You want a different API? Request it (and probably get declined as it has been since a decade ago).

That said, I'm done with the back and forth. Izno (talk) 21:53, 14 January 2022 (UTC)

Done in https://www.mediawiki.org/w/index.php?title=User:Jdlrobson/Extension:Gadget/Policy&diff=next&oldid=5074754&diffmode=source Jdlrobson (talk) 22:56, 17 February 2022 (UTC)

Policy: CSS:

1. Gadget developers SHOULD provide their own CSS for styling their gadgets and SHOULD NOT rely on MediaWiki HTML classes provided by the software. I think this would be better written as Gadget developers SHOULD provide their own CSS for styling their gadgets. They SHOULD NOT rely on MediaWiki classes to provide CSS for their gadgets.
2. Should the above hold true/make sense particularly for styles-only gadgets which provide some styles that use the same names for targets but not all styles? If some CSS is added to a class, the gadget shouldn't be responsible for adding either a) the same CSS or b) overriding CSS for that property. Consider, for example, the dark mode gadget.
3. Consider splitting the rest of the sentence into subbullets, and cleaning up the 'this' to 'sharing' or similar.
4. MediaWiki developers MUST prefix their CSS classes with "mw-" to avoid namespace clashes with gadget developers. What about classes provided by extensions?
5. They SHOULD instead prefix CSS classes with "mwgadget-" where possible. mwgadget is pretty long.
6. MediaWiki developers MAY change default CSS for content generated by wikitext provided they go through the deprecation policy. Hmm, there is an intersection here now with TemplateStyles as well as the various MediaWiki:*.css pages that needs discussion I suspect, and neither of those fall into the proposed scope of this policy.
7. I think generally, this section could benefit from separating expectations related to use/reuse of names and use/reuse of CSS more clearly. Izno (talk) 02:26, 22 December 2021 (UTC)

Done in https://www.mediawiki.org/w/index.php?title=User:Jdlrobson/Extension:Gadget/Policy&type=revision&diff=5074754&oldid=5074752&diffmode=source Jdlrobson (talk) 22:52, 17 February 2022 (UTC)

Communication/deprecation:

1. I'm pretty sure these first two bullets would be better covered elsewhere in the document; moreover, they seem to duplicate some intent elsewhere.
2. Code that is (not) considered part of the gadget stable policy It's not that they aren't part of the policy, it's that they are (not) protected from change in the ways discussed by the section on deprecation.
3. The first two sub-bullets of the first bullet should use factual language, e.g. "are", not the imperative "must". They are statements of fact to be agreed upon with the policy, not an attempt to require something about downstream users. (This would make them match the third subbullet, "classes prefixed with mw-".
4. All classes that are generated by wikitext without the use of a template I do not think this really targets what you're trying to target, thought I haven't spent more time thinking about a possible replacement text.
5. Changes to HTML structure. Gadgets should not make assumptions about how existing interface code is structured. We have templates that assume such (see w:Module:Gallery and upcoming figure changes). I am not sure this section should change for that issue, but do consider it.
6. but ideally 1 release. That's a long time (for better or worse) but probably the right amount? I am not sure. I suspect desktop improvements would have taken much longer; alternatively, it may have gotten better planning and identifying where issues were going to occur. Izno (talk) 02:26, 22 December 2021 (UTC)

Done in https://www.mediawiki.org/w/index.php?title=User:Jdlrobson/Extension:Gadget/Policy&diff=next&oldid=5074749&diffmode=source

Regarding 1 release, I think it's a bit long, but best to start with long and adjust as we go.

Regarding Module:Gallery, the idea here is that APIs would be provided as and when needed:

https://www.mediawiki.org/w/index.php?title=User:Jdlrobson/Extension:Gadget/Policy&type=revision&diff=5074747&oldid=5074738&diffmode=source Jdlrobson (talk) 22:38, 17 February 2022 (UTC)

Maintenance:

1. MediaWiki developers MAY fix gadget and/or user script errors that undermine user privacy. I think this needs a either X or Y formulation: Fix, or disable. It is quite common for privacy-vio scripts to simply be page-deleted or text-removed and I would expect one of these two things to occur as a result. (I may be misrepresenting which actor does the deletion sometimes.)
2. Gadget/script developers MAY opt out of error tracking by the guidelines given on wikitech:Client error Method should be on/near this page, not on another wiki.
3. Gadget/scripts in the user namespace of a retired or blocked user MUST BE blanked as they are no longer maintained. Needs to be put in the active tense (Actor MUST Action) to be clear about what you think the expectations should be. I also think MUST is going to cause friction with the community. Izno (talk) 02:26, 22 December 2021 (UTC)

The community will stop running unmaintained gadgets shortly after the WMF stops running unmaintained code in production. AntiCompositeNumber (talk) 05:00, 22 December 2021 (UTC)

Done https://www.mediawiki.org/w/index.php?title=User:Jdlrobson/Extension:Gadget/Policy&type=revision&diff=5074749&oldid=5074748&diffmode=source Jdlrobson (talk) 22:33, 17 February 2022 (UTC)

General comments

1. Ensure requirements language a la the RFC is consistently marked up as such. "should" particularly occurs without caps and without bold, so it leaves it unclear whether this is guidance or not.
2. Use active requirements language e.g. "Actor/Acting system SHALL act" and not "Data product shall be". This is mostly ok; I called out a few above where this was an issue, but the rest could/should probably be cleaned/reviewed. Izno (talk) 02:27, 22 December 2021 (UTC)

Done: https://www.mediawiki.org/w/index.php?title=User:Jdlrobson/Extension:Gadget/Policy&type=revision&diff=5074748&oldid=5074747&diffmode=source Jdlrobson (talk) 22:30, 17 February 2022 (UTC)

Will dig into these in January. Thanks for all this feedback! Jdlrobson (talk) 22:13, 23 December 2021 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Classes: Stable or not?

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

The JS section says 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.. However, the CSS section says MediaWiki developers MUST prefix their CSS classes with "mw-" to avoid namespace clashes with gadget developers. and the Communication / Deprecation section says Code considered part of the gadget stable policy: ... Classes that are prefixed with "mw-". This does not seem consistent: either classes are stable (and can be relied on) or they are not. Almost no interface customization gadget would be able to comply with the first quoted requirement. AntiCompositeNumber (talk) 05:12, 22 December 2021 (UTC)

Thanks for pointing out these contradictions. Out of interest what do you think our policy should be here?

We can deprecate classes but we have no easy way of notifying developers of those deprecations outside messages on tech news so I'm leaning towards classes not being part of the stable policy.

I think prefixing code in core/extensions is probably a good idea regardless as it allows us to avoid the issues we ran into with the hlist class. Jdlrobson (talk) 22:12, 23 December 2021 (UTC)

a good idea regardless I almost think that's a given, MediaWiki (meaning core, extensions, and gadgets) are just full of baggage. :) Izno (talk) 22:50, 23 December 2021 (UTC)

I think HTML and CSS should generally be stable within one skin. You could provide API for adding buttons and links instead, but would you be really willing to? For all skins. For all menus. Well documented. I'm a wiki dev since about 2006. I made a lot of tweaks to plwiki interface over the years. I've been there when Vector was starting to be a thing. The gadgets still worked with monobook and had to be adjusted for vector. But some of them just worked because some classes were preserved.

The policy should be that classes and structure SHOULD be stable. Once you add a class you shouldn't remove it without a really good reason. And new UI elements should be added with classes that will allow styling, hiding etc. A good example was the new replay button (from discussion tools), that came with classes that allowed easy styling of this element.

If you want to provide APIs then that is great, but provide documentation with many examples. Something more like you have on PHP docs where each function has at least one usage example. Nux (talk) 15:51, 25 December 2021 (UTC)

I'm still thinking through this. I think a case study might help. Help me work out what's practical by providing feedback here: Talk:Stable interface policy/Frontend#h-Case_study:_Deprecating_ID_and_classes-2022-01-14T18:38:00.000Z Jdlrobson (talk) 18:41, 14 January 2022 (UTC)

Our team was just deliberating this very topic while working on modernizing the interface in one of the `WikibaseLexeme` special pages. We were trying to select a class prefix for our CSS and HTML, and we might have to refrain from using an `mw-` prefix if the implication of this is that we would have to communicate every single change to our class - html structure.

How can we circumvent this overhead if we are obliged to prefix each class with `mw-`? Or, alternately, how will we provide a stable interface if anybody can just opt out of these prefixes?

Perhaps we should consider some policy regarding which nodes accept this stable interface `mw-` class, if only for the sake of change tolerance. ItamarWMDE (talk) 16:04, 16 February 2022 (UTC)

FWIW i don't think classes should be considered an API and part of this policy as there is currently no way to notify a gadget about the deprecation of a class (unless we run code scanning stylesheets e.g. linter for the selector). Jdlrobson (talk) 16:54, 16 February 2022 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Definition of "gadget"

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

I let this go while reading it, but now another comment has spurred some thought. Right now, "gadget" as used in the proposed policy seems to refer both to systems that use the Gadget extension for loading as well as systems which do not e.g. loaded via mw.loader.load (or various deprecated JavaScript APIs) in user space scripts. Consider whether these should be treated the same.

Probably regardless, there should be some definitional language indicating that "gadget" does have one, the other, or meanings regarding both items. Izno (talk) 22:57, 23 December 2021 (UTC)

Yes I was thinking both should be treated the same, mainly because users often tend to load scripts from other user namespaces.

I've updated to use "Wiki-based code" as terminology going forward. Jdlrobson (talk) 18:46, 14 January 2022 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Case study: Deprecating ID and classes

My team needs to deprecate the use of the ID #catlinks and class .mw-normal-catlinks at some point in the near future.

Hidden and normal category elements would not necessarily share a parent element #catlinks.

The proposed changes inside Vector would be:

• Removal of the div#catlinks element
• Class mw-normal-catlinks renamed to mw-portlet-category-normal
• Class mw-hidden-catlinks renamed to mw-portlet-category-hidden

The benefits would be:

• mw.addPortletLink now works with categories
• All Wikimedia skins would eventually be guaranteed to use the same markup.

I'm curious to hear from gadget/script developers who are requesting IDs, classes and HTML to be part of the stable policy described here, to how we would actually do this in practice without severely slowing down skin development.

The main questions are:

• How do we communicate this to the people that need to know about it?
• How quickly could we make this change? It would cripple skin development if this sort of change couldn't be made within releases for example. Jdlrobson (talk) 18:38, 14 January 2022 (UTC)

id availability

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

One of the reasons why gadget creators get creative in their Dom traversal code is the lack of ids. For instance, the mapframe code has exactly 0 ids. The same for the new discussion tools, which in addition also lack any mw-* classes. I really can't see the proposed policy being implemented as long as an workable alternative is not provided. Strainu (talk) 14:32, 11 February 2022 (UTC)

Mapframe the template, or mapframe the element? I honestly think that both mapframe and leaflet have an exceptional amount of classes applied to them, so I don't really understand what you are running into here... —TheDJ (Not WMF) (talk • contribs) 21:20, 11 February 2022 (UTC)

Aren't they the same in the end? And yes, it isn't the best example, since most elements have mw-* classes. But even in this situation, as far as I can see there is no stable (according to the policy) way of getting the caption. The same can be said about adding a button to the discussion tools editor.

Yes, the policy also says "[wiki-based developers] are encouraged to request explicit APIs for absent use cases.", but I think it's obvious by the lack of maintenance that won't happen any time soon for maps and many other features.

What I'm trying to point out is that extensively used features were written without consideration to a stable interface and the policy puts the burden of maintainance almost exclusively in the hands of wiki-based developers, which is unfair and unrealistic, since the proportion of volunteer developers on wiki is much larger. I would like to have much more stringent stability requirements for mw developers, which are, in most cases, paid staff. Strainu (talk) 08:49, 12 February 2022 (UTC)

I don't know if there is a generic way of stating these requirements, but maybe something along these lines:

"All new MediaWiki code deployed to Wikimedia wikis should offer on wiki code a stable way to access its most important elements, such as (but not limited to) toolbars, edit boxes, buttons and metadata." Strainu (talk) 09:16, 12 February 2022 (UTC)

Thanks for your input here. My opinion, is this is covered under "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."

I acknowledge that this presents a problem for existing code without maintainers, but as we build out new systems it's really important that both MediaWiki and on wiki developers communicate. The crux of this policy is to do better, and to have something to point to. e.g. if an engineer is refusing to consider an API, then they should be pointed to this policy and asked to uphold their side of it.

In the Desktop improvements project we're actively listening to gadget developers. Gadgets are being built and then thrown away because they are addressed inside the software. We're trying to support gadgets better as we inadvertently break them.

"All new MediaWiki code deployed to Wikimedia wikis should offer on wiki code a stable way to access its most important elements"

I don't think offering a way to access all its most important elements is realistic, particularly when you consider trade offs regarding performance - we can't provide APIs for everything, but we need to be able to evaluate each of these on a case by case basis, having conversations as needed around explicit APIs or around supporting different use cases. Jdlrobson (talk) 22:18, 17 February 2022 (UTC)

Not including extensions and discussing only APIs is reinforcing my feel that you move all the burden to wiki-based code developers. :( I urge you yet again to share that responsability fairly! Strainu (talk) 22:26, 17 February 2022 (UTC)

Yes. This is https://www.mediawiki.org/w/index.php?title=User:Jdlrobson/Extension:Gadget/Policy&type=revision&diff=5074747&oldid=5074738&diffmode=source Jdlrobson (talk) 22:27, 17 February 2022 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Requirements for wiki-based code developers

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

This draft policy includes several “MUST” requirements for wiki-based code developers (mostly volunteers, I assume) – they MUST pay attention to deprecation warnings, MUST NOT use mw- classes, and so on. What does this actually mean in practice? What will happen when a wiki-based code developer doesn’t follow these requirements, or even decides to deliberately violate them? Lucas Werkmeister (WMDE) (talk) 15:12, 14 February 2022 (UTC)

Thanks for bringing this up it's a good question. Gadgets can opt out of the policy by disabling error handling globally for any user that runs them. That's not great, but it's the best we have right now. I'm hoping that progress with T262493#7584789 might allow us to disable it on a per script basis.

Note, for the most part ignoring the policy is not a problem. Remember the issues we are most concerned with are privacy (a single user has a script which breaks on every page view and is leaking information about their session), security (a user script presents a security risk to multiple users) and alerting (e.g. a script is causing 1000 errors a day which prevents us monitoring health of the site).

I think when a wiki-based code developer doesn't follow these requirements, and one of the serious issues above are a result of that inaction, it falls on others (including staff) to uphold the policy and take suitable action, pointing to this policy. Jdlrobson (talk) 18:52, 14 February 2022 (UTC)

That sounds like the requirements are more for wiki-based code than for wiki-based code developers – I think it would be good to clarify that. Lucas Werkmeister (WMDE) (talk) 16:51, 15 February 2022 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Developer edits to wiki-based code

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

I feel very uncomfortable with some of the suggestions in the last section, “maintaining code”, for two main reasons.

The first reason is that the set of global interface editors is very small – only 21 users – and for good reason: these users can deploy arbitrary JS to any Wikimedia wiki, a privilege that should not be handed out lightly. Yet some of the requirements, particularly the one that MediaWiki developers MUST fix wiki-based code and/or user script errors with error volumes that trigger alerts via Wikimedia alerting systems, seem to suggest that almost any MediaWiki developer who works with JavaScript also needs to become a global interface editor, which I think is not a good idea. (You could argue that Wikimedia deployers already have the technical ability to deploy arbitrary JS to any Wikimedia wiki, but this is still a narrower set than MediaWiki developers, and also I think it’s fair to say that production deployments are better protected than wiki edits via user accounts.)

The other reason is that this feels like an overreach of developers into the community’s area of responsibility. The wiki community, not MediaWiki developers, are responsible for the contents of a wiki, and I think this should extend to the wiki-based code as well. There can be circumstances where developer edits to wiki-based code are justified, but I think the current proposal text goes too far in the direction of treating all wiki-based code as fair game for MediaWiki developers to edit as they consider necessary.

Expanding on that second reason for a bit with my volunteer hat on, this wariness I feel is based not just on the proposal text, but also on the current practice I’ve witnessed so far. I’ve seen several edits, by several MediaWiki developers, that would be allowed under this policy, whether they fixed wiki-based code manually (bullet point two/three), disabled it (four), or fixed it automatically (five); and in most if not all of the cases I’ve seen, those edits were at best incomplete (typically making an error vanish from logstash but not actually fixing the problem), and at worst flat-out incorrect and causing new errors, and I or other volunteers had to go and clean up after them. So I’m not really thrilled about a proposed policy that further encourages this behavior. Lucas Werkmeister (WMDE) (talk) 15:12, 14 February 2022 (UTC)

Thanks for bringing up this topic.

If wiki-based code is triggering alerts then we need to stop those alerts, so to do that we need some accepted social contract for getting it fixed ASAP. I think historically these have been common as error logging is new, but hopefully we are at a point now, where any new error occurring at volume will relate to a breaking change in MediaWiki code or a bad and recent on-wiki edit.

In theory, these issues should relate to a recent change, so acceptable action might be:

• disable
• revert
• Disable error logging for all users that load that code.
• fix.

With the first three we could automate those (using a bot) or use some kind of wiki page which lists scripts that error logging shouldn't run on.

The secondary challenge here is working out who to notify about the error and how to do that. My worry is if we are disabling error logging for all users as a solution to quiet alerts we are aware of, and nobody is paying attention, errors we should be paying attention to slip through the net. Jdlrobson (talk) 18:47, 14 February 2022 (UTC)

"The wiki community, not MediaWiki developers, are responsible for the contents of a wiki, and I think this should extend to the wiki-based code as well."

I'd note that this philosophy, while admirable in many ways, all but guarantees an extremely problematic security model for gadgets (and userjs) given current WMF and Volunteer resources. SBassett (WMF) (talk) 21:57, 14 February 2022 (UTC)

Having MediaWiki developers edit wiki-based code they’re unfamiliar with doesn’t sound great for security either. (I’m assuming that the code is still maintained, i.e. there are people in the community familiar with it, the policy is just proposing to bypass those people instead of contacting them.) As far as I remember, none of the edits I saw so far introduced new security issues, but I wouldn’t rule it out either. Lucas Werkmeister (WMDE) (talk) 09:57, 15 February 2022 (UTC)

I will change the wording so this is clearer. Ideally the people maintaining the code would take action. However in time sensitive situations I don't think that's always practical. For example if there was code collecting people's passwords we'd want to fix that right away if we can without waiting on say half a day for a volunteer. Jdlrobson (talk) 16:51, 16 February 2022 (UTC)

If there's code collecting people's passwords, something has gone very wrong in MediaWiki. And it's a situation that can be and is already handled under existing policies and practices. AntiCompositeNumber (talk) 17:05, 16 February 2022 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Use of mw-mf- as example

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

Someone pointed out that this is not a great example as MobileFrontend doesn't do this 100% of the time. Find a non-contradicting example. Jdlrobson (talk) 17:57, 28 April 2022 (UTC)

Using mw-abuse-filter- as the example now: https://www.mediawiki.org/w/index.php?title=User:Jdlrobson/Extension:Gadget/Policy&type=revision&diff=5217109&oldid=5217108&diffmode=source Jdlrobson (talk) 22:06, 17 May 2022 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

3rd party code

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

No decision has been made on this yet, we may want to wait on https://phabricator.wikimedia.org/T296847 or amend/remove before publishing this policy. Jdlrobson (talk) 18:00, 28 April 2022 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Feedback from MusikAnimal

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

This is great! I have only one primary concern at this time: At the top of wiki-based code, the maintainers MUST be listed – I would make this a SHOULD. At least at enwiki, gadgets (as opposed to user scripts) are often considered community-maintained and without explicit owner(s). At least for relatively simple gadgets, this is a good thing, since volunteers are never guaranteed to stay active or be responsive. When necessary, MediaWiki developers should consult the revision history to see who to contact, or go through Village Pumps, make protected edit requests, etc.

Everything else on the first read looks quite good. This policy won't solve the problems we have with meta:MoreMenu or even Twinkle, since we don't have a mw.util.addPortlet() method. Even when when that does become available, MoreMenu still needs submenus which I don't expect to ever be implemented in Vector. But that's okay :) I appreciate the "MediaWiki developers SHOULD provide APIs…" clause and the bits about using Tech News.

I suspect many gadget/script maintainers do not regularly read Tech News, and/or will miss deprecation notices in the JS console, etc. Many users publish their scripts and never revisit them, or simply don't have the time to devote to maintenance. So again, this policy won't solve all of our problems, and that's totally fine. The important part is setting expectations, especially for the paid engineers over at WMF. I think your draft does a good job of doing that. Thank you! — MusikAnimal ^talk 19:55, 28 April 2022 (UTC)

Another concern: Extension/skin developers MUST NOT use the `mw-` prefix – I'm going to assume you gathered that from Manual:Coding conventions/CSS, which used to encourage extensions to use ext-. This was recently removed by Krinkle, and we've heard from him on gerrit that we're encouraged to use mw- for any MediaWiki code (extension or otherwise). I have no strong feelings, but I wanted to point out the contradiction. — MusikAnimal ^talk 20:07, 28 April 2022 (UTC)

One of the examples says that MobileFrontend uses mw-mf-, so that suggests that a sub-prefix of mw- is acceptable. AbuseFilter does this too (mw-abusefilter-), and I'm sure many others do as well. I've also seen mwe-extensionname- in a few places (e.g. Popups), and some other extensions just use their extension name as a prefix (e.g. growthexperiments- or ve-). Roan Kattouw (WMF) (talk) 16:26, 13 May 2022 (UTC)

First topic resolved by https://www.mediawiki.org/w/index.php?title=User:Jdlrobson/Extension:Gadget/Policy&type=revision&diff=5217106&oldid=5186440&diffmode=source

I'm continuing the prefixed conversation @ https://www.mediawiki.org/w/index.php?title=Manual%20talk%3ACoding%20conventions/CSS/Archive%202/Flow%20export#h-Removal_of_extension-based_namespace-ing_encouragement-2022-03-03T16%3A47%3A00.000Z Jdlrobson (talk) 21:58, 17 May 2022 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

"generated by wikitext without the use of tranclusion"

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

I find this hard to interpret: HTML classes that are generated by wikitext without the use of tranclusion of a module or template

This is a class generated by wikitext without the use of tranclusion of a module or template:

{| class="prettytable"
|}

This is not:

{| {{prettytable}}
|}

but the distinction is not really meaningful and I imagine it's not what you had in mind. Tgr (WMF) (talk) 07:24, 29 April 2022 (UTC)

Would saying without the use of raw HTML make sense? Jdlrobson (talk) 15:09, 29 April 2022 (UTC)

Is the goal here to say that classes generated by the wikitext parser (like [http://example] turning to <a class="external>...</a>) should be considered a stable interface? If so, I'd refer to them like that, or as content-area classes generated by MediaWiki core/extension/skin code (as opposed to on-wiki code).

I'm asking because the other reading of the phrase is that it's trying to differentiate between classes used in templates vs. classes used directly in the article wikitext (which is rare but sometimes done for e.g. tables). Tgr (WMF) (talk) 08:06, 30 April 2022 (UTC)

Yep wikitext parser. I ran into a little confusion with this when talking to one particular gadget developer about phab:T287997 hence the additional clarifying text.

How about this?

https://www.mediawiki.org/w/index.php?title=User:Jdlrobson/Extension:Gadget/Policy&type=revision&diff=5217107&oldid=5217106&diffmode=source Jdlrobson (talk) 22:02, 17 May 2022 (UTC)

That's clearer, thanks!

The other slightly confusing part is that it says "Any other HTML classes provided by the interface are NOT subject to the deprecation policy (e.g. ambox, infobox, rcfilters-head). but ambox and infobox are templates/modules, not provided by the interface. So maybe something like this would be even more clear?

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. Tgr (WMF) (talk) 22:18, 17 May 2022 (UTC)

Done in https://www.mediawiki.org/w/index.php?title=User:Jdlrobson/Extension:Gadget/Policy&type=revision&diff=5218104&oldid=5217109&diffmode=source. Thanks! Jdlrobson (talk) 15:34, 18 May 2022 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

"MediaWiki developers MUST regularly actively review popular gadgets to evaluate missing APIs"

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

That would certainly be useful, but is it realistic? How would it look in practice? Tgr (WMF) (talk) 08:07, 29 April 2022 (UTC)

Does this suggestion seem practical? https://www.mediawiki.org/w/index.php?title=User:Jdlrobson/Extension:Gadget/Policy&type=revision&diff=5217108&oldid=5217107&diffmode=source Jdlrobson (talk) 22:04, 17 May 2022 (UTC)

Thanks, that seems like a good balance to me. Tgr (WMF) (talk) 22:10, 17 May 2022 (UTC)

Could we leave out the technical village pump part? I don’t think developers should be concerned about how the breakage surfaced (village pump, user talk page, gadget author noticed themselves etc.). Smaller wikis usually don’t even have a technical village pump, or may not really use a village pump at all (if there are only a handful of active users, it may be easier to just use each others’ talk pages). Tacsipacsi (talk) 07:34, 30 May 2022 (UTC)

Done in https://www.mediawiki.org/w/index.php?title=User:Jdlrobson/Extension:Gadget/Policy&type=revision&diff=5317511&oldid=5317474&diffmode=source Jdlrobson (talk) 22:54, 1 July 2022 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

I think this policy is a mistake as a separate document

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

We already have a policy for interfaces being stable. If you think we should extend the Stable interface policy then we should be talking about extending that, not writing competing standards that claims it covers different code (JS and CSS) but then covers PHP output as well. Can we instead move all of the suggestions onto that talk page to involve people properly? Jdforrester (WMF) (talk) 15:57, 18 May 2022 (UTC)

Thanks for raising this. My concern with merging the two policies, is that the audiences are different. The stable interface policy is targeted at Wikimedia developers, and this is targeted at Wikimedia deployers AND gadget developers. Lots of the stable interface policy is irrelevant to gadget developers, as they are not writing PHP at all. For example, the use of the @stable method doesn't make sense there.

One thing that might make sense is splitting out the stuff focused at Wikimedia developers into that one, and retaining this so the audience is just gadget developers. Is that what you had in mind? Jdlrobson (talk) 15:27, 26 May 2022 (UTC)

Yeah, I appreciate the worry about the main policy being mostly irrelevant for gadget authors, but the overlap is so strong that I think this will always at best be an awkward re-wording of that, but more likely be a slightly divergent set of rules and recommendations, which will lead to confusion. We could bring in a principle of annotating the sections of the main policy with icons or whatever to highlight whether each section is more relevant to MediaWiki core developers, MediaWiki extension/skin developers, gadget developers, etc.? Jdforrester (WMF) (talk) 15:05, 10 June 2022 (UTC)

Another way to do this could be to merge much of this policy into the stable interface policy, then create a summary of that policy as it applies to gadgets (either on the same page or on a separate page), linking back to the stable interface policy as the primary document. The former would be "as a developer, you are required to do X", and the latter would be "as a gadget author, you can rely on X but you should not rely on Y".

I do think that there is value in having gadget-specific text either in the stable interface policy or separate from it, because some of the things on this page don't neatly fit into the stable interface policy (especially the parts describing anti-patterns and alternatives, like "you should not rely on X because it isn't stable, use Y instead"). Roan Kattouw (WMF) (talk) 18:31, 15 June 2022 (UTC)

I should note there's also a lot of overlap here with Manual:Coding_conventions and Manual:Coding_conventions/CSS in particular. Jdlrobson (talk) 15:30, 26 May 2022 (UTC)

If it's okay I'd like to suggest the following:

1) Agree on the first version of the policy

2) Publish the policy outside my username, and link to it from the editing interface for gadgets and user scripts.

3) Once the gadget policy is live, starting discussions on Talk: Stable interface policy about importing relevant sections from the "official" document rather than a draft.

I'm committed to fixing the relationship between these 2 documents, but my thinking is doing 3 now would fragment the conversation right now.

Is that okay with you? Jdlrobson (talk) 23:07, 1 July 2022 (UTC)

Not really. I think starting with a known-bad state of divergent policies with an aspiration to lashing them back together later is mostly likely to be much worse and slower, sadly. Jdforrester (WMF) (talk) 15:47, 12 July 2022 (UTC)

James: One thing that would be helpful is if you could list out here the exact clauses in this policy that you think that are problematic and would better belong in Stable interface policy ?

I don't want to make assumptions here about what you see as competing standards and it's possible I'm not understanding the issue in the same way you are. Jdlrobson (talk) 20:12, 12 July 2022 (UTC)

James: One thing that would be helpful is if you could list out here the exact clauses in this policy that you think that are problematic and would better belong in Stable interface policy ?

Half the "JavaScript" and "CSS" sections (but maybe all of it, frankly), and the entirety of the "Communication", "Deprecation policy", and "Maintaining code and error handling" sections. Essentially, everything. Jdforrester (WMF) (talk) 13:20, 13 July 2022 (UTC)

Hi User:DKinzler (WMF) I reached out a while back to you about us having a frontend stable policy. I was curious if you could weigh in on this discussion.

Specifically: Do you think it makes sense to make Stable_interface_policy link to Stable_interface_policy/frontend or would it be better to merge the two documents despite the different audiences? Jdlrobson (talk) 18:35, 19 July 2023 (UTC)

In the "Scope" section, the Stable Interface Policy mentions several other parts of the system that have (or should have) their own policy. I think it is best to keep them separate.

If there is just two of them, we could have a "disambiguation" at the top. If there is more, we could have a navigation box, or an overview page (e.g. Stability Policies) that is linked from the Development policies an Deprecation policies boxes. DKinzler (WMF) (talk) 08:01, 20 July 2023 (UTC)

To expand on this a bit: The main reason in my mind to keep the policies separate is that they deal with structurally different things.

The SIP for PHP deals a lot with the specifics of how subclassing works in PHP, with dependency injection and such.

The frontend policy deals a lot with conventions of identifiers and locations of things in data structures (DOM). It just seems like the concerns are structurally different. DKinzler (WMF) (talk) 17:49, 26 July 2023 (UTC)

I'd really rather not merge the policies as the intended audience and scope is completely different and they are both already a tough read. No point in forcing people to go through twice as much text when they don't need to; like code, policies only need to be written once but need to be read many times by many people so it makes sense to optimize for the latter. There's a navbox for deprecation policies so it's easy to navigate between the various stable X policies. Tgr (WMF) (talk) 03:02, 2 August 2023 (UTC)

Hi James, I think the outcome seems to be to retain a separate policy so I'm resolving this for now.

That doesn't mean this can't be reconsidered at a later date, but for now the focus is to make sure we have a policy in place. Jdlrobson (talk) 15:51, 2 August 2023 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

This seems useful

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

Thanks Jon! From the perspective of someone who uses and maintains a modest amount of wiki-based code (and wants to spend as little time as possible maintaining it), I think the 'shoulds' and 'musts' and 'mays' that apply to wiki-based code are very helpful guidance.

(I have no opinion on the parts that apply to MediaWiki core and extension code.)

I don't feel strongly about whether or not this should be policy, but I do hope something like this can become a maintained resource for guiding wiki-based code authors. Sage (Wiki Ed) (talk) 21:16, 23 May 2022 (UTC)

Thanks for the feedback Sage. Just knowing the guidance is helpful is useful in itself! Jdlrobson (talk) 15:27, 26 May 2022 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Special names for CSS prefixes

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

Hey! It seems to me that we still need to share as much as possible MediaWiki-Core и MediaWiki-EXT. To do this, all classes that are created by extensions must contain the prefix ext-, which will allow them to be better redefined and recognized.

All classes created in Common.css (or used in Common.js) must have no prefixes. All classes created in Templates (TemplateStyles) must have ts- prefix. All classes created by gadgets must have gadget- or gg- prefix. Iniquity (talk) 01:02, 24 May 2022 (UTC)

Not sure I 100% understand what you are suggesting here, but I like the idea of prefixing classes in templates with `ts-` and `gadget-`, as I think that would help people reading the code knowing where it originates. I am not exactly sure what you have in mind though: Common.css is styling things that already exist right (either created by MediaWiki core, extensions or gadgets) - what kind of elements wouldn't have prefixes, how would they get created?

I wanted to note this conversation is also occurring around prefixing in Wikimedia code:

https://www.mediawiki.org/wiki/Manual%20talk%3ACoding%20conventions/CSS/Archive%202/Flow%20export#h-Removal_of_extension-based_namespace-ing_encouragement-2022-03-03T16%3A47%3A00.000Z Jdlrobson (talk) 15:35, 26 May 2022 (UTC)

> I am not exactly sure what you have in mind though: Common.css is styling things that already exist right (either created by MediaWiki core, extensions or gadgets) - what kind of elements wouldn't have prefixes, how would they get created?

For example hlist or some

classes for tables

or

navboxes? :) Iniquity (talk) 16:58, 26 May 2022 (UTC)

Please no. This policy should go only so far as to reserve names for system development. It should not extend to mandating class names anywhere else. Izno (talk) 17:25, 26 May 2022 (UTC)

It seems to me that this policy is the best way to harmonize some technical aspects between different wikis. This will facilitate both the development and distribution of gadgets, scripts and styles. Iniquity (talk) 17:30, 26 May 2022 (UTC)

I am not interested in harmonizing technical aspects between wikis. I am interested in establishing a technical contract between system developers and wiki users. Mandating what names can or will be used by the system developer is sufficient to achieve that task. Let's not make this document something it is not nor what it intends to be.

If a wiki thinks there are naming issues, I think that wiki is in the sole position to fix them. Izno (talk) 17:40, 26 May 2022 (UTC)

As for findability, Special:Search. That's it. That's the story. That's how easy it is. If you particularly need to identify where TemplateStyles came from, the HTML emitted (both style and link elements) includes a reference to the page revision. Izno (talk) 17:43, 26 May 2022 (UTC)

Just to check I'm understanding the concern here.

Are you saying you have a concern with the following line:

> 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.

I think not using the mw- prefix is very important to be enforced, so I think this should be MUST.

The twinkle-, mwgadget- prefixing is a suggestion (hence SHOULD) as it helps the wider community understand how things fit together and find things more easily. Is there a way I could rephrase this to satisfy your concern more?

I don't see anything here that would require any changes to existing CSS classes such as `hlist` for onwiki developers - only mediawiki developers (the expectation here is that the hlist in core needs fixing and should be renamed mw-hlist or removed)? What am I missing? Jdlrobson (talk) 17:57, 26 May 2022 (UTC)

I think it is already good/best practice to 'namespace' classes to relevant components, whether TemplateStyles, gadgets, or MW software. This I have no objection to. The current text of the guideline I could nitpick but what is there is reasonable today. Izno (talk) 20:40, 26 May 2022 (UTC)

(I am particularly objecting to Iniquity's musts.) Izno (talk) 18:10, 26 May 2022 (UTC)

> I am not interested in harmonizing technical aspects between wikis.

Yes, I am aware of this problem, but I am interested in it.

> If a wiki thinks there are naming issues, I think that wiki is in the sole position to fix them.

On a global scale, when 80% of projects do not have technical specialists in an independent version, this is not possible. Tested by experience. I also recommend trying to administer something other than English Wikipedia, you will understand what the pain is.

> As for findability, Special:Search. That's it. That's the story. That's how easy it is. If you particularly need to identify where TemplateStyles came from, the HTML emitted (both style and link elements) includes a reference to the page revision.

Thanks for the link! :) I didn't know about it!

But seriously, are you suggesting that I do the search instead of adding an exercise to the guideline? I do not prevent you from doing this, but to be honest, I do not want to do this.

And in order to not do this in our local wiki, we came up with a great policy:

Википедия:Стили шаблонов#Принципы

. I recommend to use, very convenient. Classes do not overlap, all users know how to correctly name classes, it is easier for engineers to maintain templates.

> (I am particularly objecting to Iniquity's musts.)

Please, dont read any message like text in MoSCoW. Of course it should be SHOULD. Iniquity (talk) 20:24, 26 May 2022 (UTC)

When the language this proposed policy uses is in fact predicated on the relevant IETF RFC, yes, I am going to read must as must. Don't use imprecise language.

when 80% of projects do not have technical specialists in an independent version, this is not possible These wikis probably aren't in a position to need to care about this proposed policy then, and certainly won't regardless. Either they have sufficient knowledge to fix these conflict themselves, or they're ripping straight from arbitrary other wiki, and presumably one of the ones with the knowledge to be ripped from, meaning no issues should arise. ;)

I do not know what you intend by I do not prevent you from doing this, but to be honest, I do not want to do this.

The ru.wp TemplateStyles page basically looks like a translation of en.wp's based on Google Translate. Please indicate the line you think is specifically relevant to what you proposed above -- that is, the required addition of certain prefixes.

But seriously, are you suggesting that I do the search instead of adding an exercise to the guideline? Yes. Because as I said, this proposed guideline is about a contract between the system developers and wiki users. You are trying to make it something it is not. Don't do that. The prefix mw- is sufficient to prevent issues between deployed software and wiki-based code. Anything else is scope-creeping this proposed policy. Izno (talk) 20:38, 26 May 2022 (UTC)

> When the language this proposed policy uses is in fact predicated on the relevant IETF RFC, yes, I am going to read must as must. Don't use imprecise language.

Of course you can going to read must as MUST, it's your right.

> These wikis probably aren't in a position to need to care about this proposed policy then, and certainly won't regardless.

These wikis can be maintained by users from other wikis, and when everyone has the same guideline, it's much easier to do so.

> The ru.wp TemplateStyles page basically looks like a translation of en.wp's based on Google Translate. Please indicate the line you think is specifically relevant to what you proposed above -- that is, the required addition of certain prefixes.

Wow, yes, sorry. The text of the English Wikipedia seems copies ours, did not know about it. Anyway I am talking about this paragraph:

> При именовании классов в стилях шаблонов используйте префикс вида ts-[префикс]-, чтобы избежать коллизий при использовании стилей двух шаблонов с одинаковыми селекторами. Рекомендуется, чтобы часть [префикс] соответствовала названию шаблона (кириллицей или латиницей), подстраницей которого являются создаваемые вами стили. При наличии в названии нестандартных символов заменяйте их на нижнее подчёркивание.

> Yes. Because as I said, this proposed guideline is about a contract between the system developers and wiki users.

I see no problem at all in giving general style advice in this guide. Especially considering that they are already in the text. Iniquity (talk) 21:00, 26 May 2022 (UTC)

I see no problem at all in giving general style advice in this guide. It is out of scope. Izno (talk) 21:23, 26 May 2022 (UTC)

If we decide not to expand the scope, then read me only as a suggestion for reflection. Iniquity (talk) 21:29, 26 May 2022 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Classes renaming

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

I understand correctly that after the adoption of this policy, it will be necessary to rename: wikitable -> mw-wikitable, plainlinks -> mw-plainlinks etc? :) Iniquity (talk) 01:04, 24 May 2022 (UTC)

In practice, I think it's more likely we'll add both wikitable and mw-wikitable to these elements and slowly (very slowly) phase out the former. Jdlrobson (talk) 15:36, 26 May 2022 (UTC)

Didn't want to lose this so this is now captured here:

https://www.mediawiki.org/w/index.php?title=User:Jdlrobson/Extension:Gadget/Policy&type=revision&diff=5317512&oldid=5317511&diffmode=source Jdlrobson (talk) 22:57, 1 July 2022 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Strict separation of on-wiki and MediaWiki classes

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

• MediaWiki developers and wiki-based code MUST NOT share CSS classes
  • […]
  • Wiki-based code MUST NOT […] use CSS classes prefixed with mw- […].

I don’t like this as a MUST. There are some well-known classes like mw-message-box-* for which the styles are always loaded. If wiki-based developers are forced to use different class names, it’ll cause (in addition to the unnecessary extra CSS downloaded by users) that if their styling (and not the class name) changes, the UI becomes inconsistent unless the wiki-based code is updated. Either this needs to be at most a SHOULD, or a list of exceptions should be added.

Also, it’s not clear for me what introduce in the same sentence means. Is any occurrence of mw- prefixed class names in wiki-based CSS definitions prohibited? Or is intentional overriding of core/extension/skin styling accepted, and only custom mw- prefixed classes (i.e. those that are never added or styled by core/extensions/skins) are disallowed? For example, hu:MediaWiki:Common.css contains the following rule:

.mw-tag-marker {
	margin: 0 2px;
	border: 1px solid #a2a9b1;
	-moz-border-radius: 4px;
	-webkit-border-radius: 4px;
	border-radius: 4px;
	padding: 1px 3px;
	background-color: #ddd;
}

This styles the tags (e.g. “Visual edit” or “Manual revert”) in page histories. Since they are by default unstyled, the goal of this class is clearly to allow wiki-based code to customize their appearance, but it’s not clear if this policy will allow us to do so. Tacsipacsi (talk) 13:44, 30 May 2022 (UTC)

> There are some well-known classes like mw-message-box-* for which the styles are always loaded.

The Minerva skin does not load these rules on all pages. In this particular situation, it seems the following applies:

"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."

Perhaps there should be a magic word or JS API for adding message boxes.

> That if their styling (and not the class name) changes, the UI becomes inconsistent unless the wiki-based code is updated.

If the HTML and CSS changes in the codebase, the UI would also become inconsistent.

> Also, it’s not clear for me what introduce in the same sentence means. Is any occurrence of mw- prefixed class names in wiki-based CSS definitions prohibited? Or is intentional

This is a good point, thanks for bringing it up. I've made a note to clarify around "intentional overriding" being allowed. https://www.mediawiki.org/wiki/Talk%3AStable%20interface%20policy/Frontend#h-TODO%3A_Update_policy_to_confirm_on_wiki_styles_can_change_defaults-2022-05-31T18%3A46%3A00.000Z Jdlrobson (talk) 18:46, 31 May 2022 (UTC)

The possible misunderstandig arrives from a distinction

• which purpose have selectors and selected elements
• the appearance of such elements in context of a certain wiki or user adaption.

No selector shall be used for other purpose than explained in the selector registry.

• mw-error (or error as legacy) must not be used for other elements than important error messages.
• However, everybody could define a yellow background, or yellow text on red background for those elements. PerfektesChaos (talk) 17:59, 2 June 2022 (UTC)

Clarified in https://www.mediawiki.org/w/index.php?title=User:Jdlrobson/Extension:Gadget/Policy&type=revision&diff=5317474&oldid=5243439&diffmode=source Jdlrobson (talk) 22:52, 1 July 2022 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Policy means violations

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

This may be out of scope for the drafting, but I haven't seen a discussion anywhere about what happens when (inevitably if not immediately) parts of this policy are not followed/violated/ignored. The current draft further notes this as a "contract" but regardless of language used, what are the proposed avenues for follow-up? Presumably different by venue and role (Wikimedia staff, volunteer contributor, random user in on-wiki userspace). ~ Amory (u • t • c) 20:39, 30 May 2022 (UTC)

The main goal of the policy in this early stage is to aid resolving disputes that are already happening. ie. violations already exist, but we want to provide better guidance about how to fix them/stop them happening again.

For example, if a developer does something that breaks a gadget, it should be clear who is at fault and what action to take next e.g. developer didn't go through deprecation policy correctly OR the gadget developer was using something that wasn't subject to the policy and should request it.

I think if someone on either side chooses not to follow the policy, I can't foresee too many problems (unless they are maintaining a hugely popular gadget), but they'd just be setting themselves up for frustration, and a lack of sympathy when they complain e.g. If you'd followed the policy this issue wouldn't have happened. Are there items on this policy, that if violated/not followed would cause major problems to us that would need resolution?]

The worse case I can think of is if a popular gadget was causing production errors at such a scale it was causing a problem for identifying bugs in other software. In this situation, I could imagine a wheel war where a change is made to fix the error/undo the fix. I think this situation would be very rare, but I'm also optimistic if it did happen, through discussion we'd be able to eventually compromise somewhere via discourse. Is there anything you think would be helpful to add to the policy? Jdlrobson (talk) 18:37, 31 May 2022 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

TODO: Update policy to confirm on wiki styles can change defaults

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

See https://www.mediawiki.org/w/index.php?title=Talk%3AStable%20interface%20policy/Frontend#h-Strict_separation_of_on-wiki_and_MediaWiki_classes-2022-05-30T13%3A44%3A00.000Z

The policy is currently unclear around whether MediaWiki:Common.css can override default definitions. Jdlrobson (talk) 18:46, 31 May 2022 (UTC)

See https://www.mediawiki.org/w/index.php?title=User:Jdlrobson/Extension:Gadget/Policy&type=revision&diff=5317474&oldid=5243439&diffmode=source Jdlrobson (talk) 22:52, 1 July 2022 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Policy page location

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

Extension:Gadget/Policy seems like a confusing place for a policy that explicitly says it is not specific to Extension:Gadget code but also applies to MediaWiki:Common.js etc Tgr (WMF) (talk) 15:28, 9 July 2022 (UTC)

Right. I never moved the page since it's change in scope. I need to work out the right terminology here but I am currently thinking Wiki-hosted code policy. What do you think? Jdlrobson (talk) 19:07, 9 July 2022 (UTC)

That includes templates and Lua modules as well - I guess that's a good thing as those can generate CSS classes etc. Sounds like a good name - better than "wiki-based" (used in the current draft) IMO.

"Gadget policy" could work too, just don't tie it to the extension specifically. Tgr (WMF) (talk) 21:59, 9 July 2022 (UTC)

Rename done in https://www.mediawiki.org/w/index.php?title=User%3AJdlrobson%2FStable_interface_policy%2Ffrontend&diff=6031915&oldid=6022653 Jdlrobson (talk) 17:40, 18 July 2023 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Please review amendment (June 2023)

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

I've made some minor amendments based on feedback from WMF engineers.

The diff of changes here; https://www.mediawiki.org/w/index.php?title=User%3AJdlrobson%2FStable_interface_policy%2Ffrontend&diff=6010504&oldid=5935744

Summary of changes:

• Clarify how this links to PHP stable policy and gadget policy
• Fix typos
• Add additional terminology
• Allows HTML markup to be stable if deemed necessary and why HTML markup might be important to support.
• Details around caching updated to provide further clarity to those not familiar.
• Attempt to define what constitutes "Gadget popularity"
• More examples given of "stable APIs"
• Use of Vue.js is now a MUST consideration for complex UIs.

Jdlrobson (talk) 18:17, 30 June 2023 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Relax policy around deprecations

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

It has been suggested to relax the requirements around deprecations so that it need not apply to everything. Proposed text is: "Code that was never part of a public release, or never consumed according to codesearch MAY be changed or removed without deprecation, since it has never become part of the stable interface or used." Proposal is to add this text to sections What to do when breaking changes to JavaScript interfaces and What_to_do_when_removing_ResourceLoader_modules If no objections or amendments within 7 days I'll make this part of the policy. Jdlrobson (talk) 15:53, 12 July 2023 (UTC)

From Ladsgroup (original link): Maybe turn codesearch to codesearch and global search. So if it's not used by users either (or used a little, then we can switch them ourselves) Jdlrobson (talk) 15:53, 12 July 2023 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Mailing list for announcements

In the hackathon we talked about a mailing list for frontend-related announcements (like cloud-announce, analytics-announce, etc.). We should do something about it. Ladsgroup (talk) 16:23, 12 July 2023 (UTC)

Agreed. I think the main audience would be gadget developers - so perhaps gadget-announce? The release notes and developer console should suffice for other breaking changes. What do you think? Jdlrobson (talk) 19:55, 12 July 2023 (UTC)

it's not technically correct: js changes can break user scripts too. But naming is hard Ladsgroup (talk) 16:39, 13 July 2023 (UTC)

How about wiki-hosted-code-announce ? Jdlrobson (talk) 17:41, 18 July 2023 (UTC)

User:Izno, User:MusikAnimal, User:Stjn, User:Novem_Linguae, User:Nardog, User:Nikki as people who I hope would subscribe to such a mailing list - do you have any opinion on the name of the list and whether it would be useful?

I'd love to use such a mailing list for advertising the upcoming phab:T303488 for example. Jdlrobson (talk) 23:16, 19 July 2023 (UTC)

Thanks for the ping. Fix ping to Nardog. I don't think hosted-code-announce is precise enough. Throwing out some ideas: gadget-announce, user-script-announce, front-end-announce, javascript-announce, gadgets-l, userscripts-l, frontend-l, javascript-l. Of those I think I like frontend-l the best so far. Hope this helps. –Novem Linguae (talk) 23:41, 19 July 2023 (UTC)

The link to Nardog's userpage still isn't working. Not sure if ping worked or not. This talk page thing we're using is Extension:Flow right? And it's getting sunset? Guess I'll hold off on a bug ticket. –Novem Linguae (talk) 03:08, 20 July 2023 (UTC)

Nardog – that should work. I guess it doesn't…

I have no strong feelings but "frontend-l" as Novem suggests sounds fine. Announcements might involve CSS as well as JS, right?

Thanks for starting this initiative! — MusikAnimal ^talk 19:21, 20 July 2023 (UTC)

Do we want this to be low traffic? If so, perhaps frontend-announce and use it strictly for reporting breaking changes ?

Or are we really looking for a new community to discuss best practices? This policy itself could be discusses there for example? In which case frontend-l makes sense but it might steal traffic from wikitech-l.

Or.. both?! Jdlrobson (talk) 22:40, 20 July 2023 (UTC)

I got pings from all three of you. I just don't have a user page on this wiki or on Meta so it's a red link. Nardog (talk) 05:06, 21 July 2023 (UTC)

Lol sorry! It's actually linking to User:Nardog?action=edit&redlink=1, hence why we were unsure if the ping worked. — MusikAnimal ^talk 20:44, 26 July 2023 (UTC)

I think it should stay low-traffic and for announce only: For many wikipedians that we are asking them to join this mailing list, they want to only receive important updates not all sorts of random inquiries. People who like to do so, they can join wikitech-l or other forums. Ladsgroup (talk) 10:10, 21 July 2023 (UTC)

I don't personally sign up for mailing lists for the tech side as I do a fairly good job of keeping watch of relevant projects on Phabricator (and similarly for non-tech stuff things bubble up in various channels).

I'm wondering what the utility is of a -announce list if we already have Tech News (for the gadget-minded) and wikitech/mediawiki lists for the skin/dev minded?

And on that thought, why not just add a Tech News announcement email to wikitech-l? Izno (talk) 20:31, 26 July 2023 (UTC)

*-announce has the implication that posting to it is restricted and replies get redirected to another list (presumably wikitech-l). *-l has the implication that pretty much anyone can post or respond there. IMO wikitech-l is fine for discussing frontend issues (it gets 1-2 mails per day so assuming a new *-l would be functional at all, it wouldn't really reduce the amount of emails gadget maintainers have to read). So a new *-announce list makes sense to me (good for people who want to get near-zero volume of messages) but a new *-l does not.

As for the name (obviously it's a bit of a bikeshed) my vote would be for "gadget" (gadgets are intended to replace other kinds of user scripts, we just didn't get there yet). "frontend" sounds nice too but maybe suggests a more generic purpose than the list would actually have. Tgr (WMF) (talk) 02:56, 2 August 2023 (UTC)

To add to the bikeshed perhaps wikitech-announce would make sense if we're open to including all sorts of announcements relating to breaking changes? I believe backend stable policy requires emails to wikitech-l but that could perhaps use the new mailing list too? Jdlrobson (talk) 15:53, 2 August 2023 (UTC)

wikitech-l is "the list for discussing the technical aspects and organization of the Wikimedia projects, for developers discussing technical aspects and organization of Wikimedia projects". So wikitech-announce makes sense if you think the audience is limited to Wikimedia.

The PHP stable interface policy says "hard deprecation [without a warning period] can be applied by announcing the removal on wikitech-l in a timely manner" and "deprecation with far-reaching impact SHOULD be announced by email to wikitech-l or mediawiki-l". (The default communication channel is the PHP warnings themselves + the release notes, so most deprecations aren't announced anywhere.) Web API deprecations are announced on mediawiki-api-announce (and the action API also uses a warning mechanism; not sure if other web APIs have something similar). Wikidata has its own set of channels. Tgr (WMF) (talk) 19:38, 2 August 2023 (UTC)

What if we used the existing api-announce then? After all what we have here is a frontend API that we are making breaking changes to. Jdlrobson (talk) 15:58, 4 August 2023 (UTC)

The MediaWiki-API-announce list is for the Action API, not general APIs people care about. You won't reach your audience there, and you'll spam a bunch of people who don't and won't care. Creating wikitech-announce for this seems sensible. Jdforrester (WMF) (talk) 16:30, 4 August 2023 (UTC)

In practice it's also used by the the REST API deprecation policy and I'd imagine some gadget authors are already subscribed to it because gadgets tend to use APIs as well. OTOH I'd expect most people to interpret "API" as "web API" (which is how e.g. the API: namespace on mw.org is used); PHP interface breaking changes are also announced on wikitech-l.

So I think api-announce is a workable idea but I too like wikitech-announce more. Tgr (WMF) (talk) 16:45, 4 August 2023 (UTC)

One thing that came up during the feedback policy was the suggestion that relying on tech news makes in-efficient use of volunteer team since not everyone reading tech news can help.

If we did have a mailing list, perhaps a requirement of giving someone interface rights on a wiki could be that they are required to subscribe to this mailing list. Jdlrobson (talk) 18:12, 18 September 2023 (UTC)

Not everyone who needs this information is an interface admin – some may develop user scripts, or develop gadgets by making edit requests. Also, some interface admins may not be willing to share their email addresses, or not even have one (remember that in order to create a SUL account, providing an email address is only recommended, not mandatory). Most of the Tech News entries are irrelevant to most readers, but there aren’t that many that this would be a real problem IMO. Tacsipacsi (talk) 07:53, 20 September 2023 (UTC)

I was thinking about this discussion in the context of phab:T344067 ("Gadget icons may go missing - how to fix") -- TLDR: that task affects ~45 gadgets (most of which are copies of a single specific darkmode gadget) and ~45 user-CSS pages. When we added that to Tech News, it frustrated me that thousands[1] of people were likely to read something that only a tiny handful of people can help with.[2]

For a task like that, I think we essentially want a way to reach some specific Interface Admins (IAs). It isn't practical to manually construct a custom MassMessage target-list for each time something like this occurs, especially as we want to be more communicative (higher quantity) about things like this (and hence related concerns for just using Tech News to do it). We also want to avoid making the signal-to-noise ratio even worse at smaller wikis' Village Pumps (phab:T130602 et al).

I'm not sure if a new mailinglist is a practical solution, unless we require subscription. (and while IA's are required to have 2FA, I don't believe that 2FA requires a registered email, so Tacsipacsi is correct about that concern, as well as the privacy concern.) And even then it wouldn't reach userscript-devs who are almost impossible to comprehensively list.

For the narrower use-cases like my example: We've linked to GlobalSearch a few times in similar tasks, and I wonder (pipedream?) if it would be possible to use results from that, along with the {{ping}} feature, via some kind of simple scripting? -- E.g. Perhaps it's possible to hack together a quick tool that matches "wikinames from GlobalSearch results" with "complete list of all IAs on each wiki"(?), so that if we wanted to contact the IAs from (xxwiki, yywiki, zzwiki, ...) we could get a copy & pasteable {{ping|alice|bob|charlie}} that any dev could then easily use in a talkpage post on m:Tech noticeboard, and use a page like that as the central location.(?)

Overall, the choices are basically: Mailing list, Onwiki broad announcement, Onwiki targeted message, Onwiki centralized ping. All have many pros and cons. They could even be combined, e.g. "new announce mailing list, + manually copy it to a centralized noticeboard".

To get any further with this discussion, I think it might help to have additional examples of the kinds of content we'd expect to be communicating, so that we can think about the target-audience more clearly. I.e. Beyond phab:T344067 and phab:T303488.

I hope these thoughts help! Sorry for the length.

[1] (Tech News currently reaches: ~300 notice-boards and ~700 individuals onwiki, plus ~900 Diff-blog subscribers and ~600 wikitech-ambassadors@ subscribers)

[2] (even fewer people than the usual small-ish quantity likely to be interested in any average Tech News entry, as Tacsipacsi notes.) Quiddity (WMF) (talk) 23:16, 27 October 2023 (UTC)

I think the goal is not so much to make sure to directly ping everyone who might be affected but to have a place where people who want their tools to be high-reliability can learn about changes up front, and people who want to spend less effort on tool maintenance can look at the list of recent changes if their tool does get affected. Tgr (WMF) (talk) 01:30, 28 October 2023 (UTC)

Guidance for consumers vs guidance for providers

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

The guideline includes guidance and requirements for providers of the interface (mostly staff), mixed in with guidance and requirements for consumers of the interface (mostly gadget developers).

Reading this doc from the perspective of a gadget developer looking for information on what CSS calsses, JS functions, and DOM elements I can (or can't) rely on, I am having a hard time finding that information.

I think it would be useful to have a top level section aimed at "consumers", which lists what is, and isn't, safe to use. Following that, we should have a section aimed as "providers", telling them what they can (and can't) change without notice. DKinzler (WMF) (talk) 17:41, 26 July 2023 (UTC)

It was suggested to me that the the audience for this document should be Wikimedia developers only (those working on Gerrit).

For gadget developers we currently have Recommendations_for_gadget_developers_on_Wikimedia_wikis which I'm working on separately, which is currently intentionally meant to be more informal (e.g. gadget developers do not need to follow our guidelines - it's not a "policy" but a set of recommendations) and provide more context around the guidelines in this document.

Does that separation make sense to you or should we reconsider merging the two of them (or perhaps there's particular text in the recommendations page that should be ported over)? Jdlrobson (talk) 18:12, 26 July 2023 (UTC)

Addressing the two audiences separately makes sense to me. Whether we do it in two section of the same page, or on separate pages, is probably a matter of teste.

If we do it on separate pages, the pages should be interlinked - not just by a priminent link at the top, but probably also by cross-referencing individual sections.

The guideline docs for the two audiences is to a large part presenting the same information from two perspective. Doing so on the same page would make this more obvious, and would make it easier to ensure they do not get out of sync.

On the Stable interface policy page, the overall structure of the document is oriented towards guidance to the consumers of the interface. Each section has a paragraph that provides guidance for authors (providers). The bottom of the document then defines process to be followed by providers.

I would propose the use the same approach for this document, if for no other reason, for consistency with the established policy page. It's a tried-and-true approch. DKinzler (WMF) (talk) 19:13, 26 July 2023 (UTC)

Just a semi side point -- if you do have a separation of the intended audience, I think it needs to be made explicit in the policy. MSchottlender-WMF (talk) 19:39, 26 July 2023 (UTC)

Did the audience requirement change?

In a discussion below regarding potentially merging this policy with the Stable Interface Policy, you pointed out that the reason they should be separate is that

"The stable interface policy is targeted at Wikimedia developers, and this is targeted at Wikimedia deployers AND gadget developers. "

I don't mind having two policies if both are needed, but I think that the conversation above and the earlier ones show that if nothing else, this point shows a confusion that needs to be clarified. MSchottlender-WMF (talk) 19:44, 26 July 2023 (UTC)

The PHP SIP is targetted at two audiences as well: extension developers (consumers) and core developers (providers). I suppose it's in the nature of interfaces, since they by definition sit "in between". DKinzler (WMF) (talk) 22:21, 26 July 2023 (UTC)

Thank for this discussion!

There has also been some similar feedback here: https://phabricator.wikimedia.org/T341532#9052717 so will look to arrange this better by audience type.

The theme of feedback I got from people (including in private) seems to lean towards including high level details of Recommendations_for_gadget_developers_on_Wikimedia_wikis here. Jdlrobson (talk) 20:52, 28 July 2023 (UTC)

I've added a quick start session at https://www.mediawiki.org/w/index.php?title=User%3AJdlrobson%2FStable_interface_policy%2Ffrontend&diff=6058288&oldid=6058278 and have reorganized the document to be clearer about the audience.

Does this help at all or does this still seem confusing? Jdlrobson (talk) 00:19, 5 August 2023 (UTC)

Okay, I've made some changes and I'm quite happy with the result:

https://www.mediawiki.org/w/index.php?title=User%3AJdlrobson%2FStable_interface_policy%2Ffrontend&diff=6062585&oldid=6061828

Please let me know if there are still concerns here that need to be addressed. Jdlrobson (talk) 22:34, 8 August 2023 (UTC)

Thanks for discussing this. Please create a new topic if you feel the latest version of the document doesn't satisfy your concerns. Jdlrobson (talk) 23:32, 11 August 2023 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

clearly define when Vue is a requirement

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

User:Jdlrobson/Stable interface policy/frontend#Maintaining existing features states that Vue must be used for complex UIs. What is a complex UI?

I did some cursory digging, and even Vue.js doesn't clearly state that using it is a requirement. I looked at the announcement of Vue as our formal choice of frameworks: https://lists.wikimedia.org/hyperkitty/list/wikitech-l@lists.wikimedia.org/thread/SOZREBYR36PUNFZXMIUBVAIOQI4N7PDU/ and while it seems clear that Vue is the technology of choice when using a framework, I couldn't really find any other guidance for when a framework must be used.

It seems like that guidance should be plainly stated somewhere and referenced here. JSherman (WMF) (talk) 15:53, 31 July 2023 (UTC)

I would also like to know when this new requirement applies. When a new complex user interface begins development? Or is this basically an executive order to immediately rewrite all existing non-Vue complex user interfaces (e.g. Wikibase’s)? Lucas Werkmeister (WMDE) (talk) 16:04, 31 July 2023 (UTC)

This also doesn't seem to follow from the scope and spirit of the policy in any way, and there are situations where using Vue isn't feasible or beneficial (e.g. payload size, or extremely complex UIs like VisualEditor). Tgr (WMF) (talk) 05:33, 2 August 2023 (UTC)

Hey all! So the purpose of this line was to avoid the situation where a new feature (gadget or code) is built with something other than our preferred framework or in OOUI.

Perhaps this could be rewritten

e.g

"Code creating complex UIs MUST use Vue.js and MUST follow any guidance that appears in the JavaScript console to maintain compatibility."

->

"New code requiring a framework or component library MUST use Vue.js and MUST follow any guidance that appears in the JavaScript console to maintain compatibility."

Would that make more sense? Thanks in advance for your answers! Jdlrobson (talk) 15:46, 2 August 2023 (UTC)

I would go with SHOULD (for the first one at least). For gadget developers, if they want to use their favorite widget library or whatever, I don't think we have a reason to prevent that; we won't provide them any support, but if they are OK with that, no harm in it. (That's assuming using Vue is even an option for them; T313945 is still in its early stages.) For MediaWiki developers, there is more justification for enforcing uniformity but I think there might be valid reasons in specific cases to not use Vue, even if it's not a decision to be taken lightly. That's especially true if by Vue we really mean Codex (I assume using a different Vue-based UI library would not be seen as a good practice), which is not that mature yet. Tgr (WMF) (talk) 19:58, 2 August 2023 (UTC)

This is limited to MediaWiki developers not gadget developers. This was implied by I've made this clearer here

> For MediaWiki developers, there is more justification for enforcing uniformity but I think there might be valid reasons in specific cases to not use Vue, even if it's not a decision to be taken lightly.

> That's especially true if by Vue we really mean Codex (I assume using a different Vue-based UI library would not be seen as a good practice), which is not that mature yet.

This is intentionally Vue.js not Codex, to allow the ecosystem to evolve as we need it to. The key thing we want to avoid is an extension introducing say React without any discussion and fragmenting our ecosystem/bloating our JavaScript.

I still think MUST is appropriate here, but perhaps we could qualify this? Instead of complex UIs perhaps the following text captures the spirit? What do you think?

> MediaWiki developers requiring a JavaScript framework MUST use Vue.js and MUST follow any guidance that appears in the JavaScript console to maintain compatibility. Jdlrobson (talk) 20:46, 2 August 2023 (UTC)

Thanks for the clarifications! Sounds good to me. Tgr (WMF) (talk) 22:52, 2 August 2023 (UTC)

This is intentionally Vue.js not Codex, to allow the ecosystem to evolve as we need it to.

I think it would be better to put Codex here, and have us update the document when we have a need for the ecosystem to evolve. Jdforrester (WMF) (talk) 12:04, 3 August 2023 (UTC)

Okay then how about:

> MediaWiki developers requiring a JavaScript framework MUST use Vue.js. They SHOULD consider using Codex for components and MUST follow any guidance that appears in the JavaScript console to maintain compatibility.

As Gergo says Codex is still immature so many teams are building out components and later upstreaming them to Codex so we don't want to require Codex currently (but should increase this to MUST at some future point). Jdlrobson (talk) 15:56, 4 August 2023 (UTC)

As Gergo says Codex is still immature so many teams are building out components and later upstreaming them to Codex so we don't want to require Codex currently (but should increase this to MUST at some future point).

If you're using Codex and writing components for the infill, that clearly counts as using Codex. This is a document read by humans, not unthinking robots. I don't see the problem? What we want to avoid is people using Vuetify or Quasar or whatever, or intentionally building their own distinct from Codex because they don't like the Wikimedia design, etc.. Jdforrester (WMF) (talk) 16:27, 4 August 2023 (UTC)

Okay. Gergo do you have any concerns with the text?

> MediaWiki developers requiring a JavaScript framework MUST use Vue.js. If a component library is required and components exists they MUST use Codex. All developers MUST follow any guidance that appears in the JavaScript console to maintain compatibility. Jdlrobson (talk) 21:58, 4 August 2023 (UTC)

Fine with me but IMO would be easier to just leave out - I think the question of how quickly to adapt Vue/Codex (people need to learn a new framework etc, not always a good idea to block a project on that) doesn't have much to do with this policy. Tgr (WMF) (talk) 00:38, 5 August 2023 (UTC)

The more I think about it the more you are right. Using Vue.js is a guideline, it's not about providing a stable interface for code. I think it would make sense to remove this altogether since provided a module isn't deprecated it should be considered okay to use. Jdlrobson (talk) 18:17, 5 August 2023 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Comments from Tgr

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

> A "MediaWiki developer" is defined as someone who contributes code to the MediaWiki core code repository or one of its extensions or skins.

Should probably be limited to extensions in Wikimedia production (or extensions maintained by the Wikimedia community or some such). If I write an extension for my company wiki, there is no reason for me to care about this policy. Tgr (WMF) (talk) 03:20, 2 August 2023 (UTC)

Yep makes sense. https://www.mediawiki.org/w/index.php?title=User%3AJdlrobson%2FStable_interface_policy%2Ffrontend&diff=6058181&oldid=6054874 Jdlrobson (talk) 22:02, 4 August 2023 (UTC)

> historically, gadget developers have been led to believe this

"historically, gadget developers had no other choice than to rely on HTML markup" might be a better way to phrase it. Tgr (WMF) (talk) 03:20, 2 August 2023 (UTC)

Done: https://www.mediawiki.org/w/index.php?title=User:Jdlrobson/Stable_interface_policy/frontend&diff=next&oldid=6058181 Jdlrobson (talk) 22:03, 4 August 2023 (UTC)

> MediaWiki developers are encouraged to over-communicate any changes

add a convenience link to the communications section? Tgr (WMF) (talk) 03:20, 2 August 2023 (UTC)

Done in https://www.mediawiki.org/w/index.php?title=User:Jdlrobson/Stable_interface_policy/frontend&diff=next&oldid=6058182 Jdlrobson (talk) 22:03, 4 August 2023 (UTC)

> Wiki-hosted code MUST NOT reuse class names defined by MediaWiki developers for styling purposes as this can lead to misuse

"SHOULD NOT"? That implies "this is how we expect you to do it; if you don't and your code breaks, you are on your own". MUST NOT would imply "if you don't do it this way you get into trouble" (or at least someone forcibly changes your code) which 1) I don't think we really care that much, 2) a stable interface policy is unlikely to cover all uses cases so IMO it's legitimate for someone to say they are willing to take the risk for the extra functionality. (Also if this policy applies to MediaWiki developers, setting requirements for wiki-hosted code isn't really in scope...)

Also, maybe it should say "reuse style sheets" instead? The current wording isn't very clear; "Wiki-hosted code MUST NOT reuse class names" could be taken to mean that wiki-hosted code should not use core/extension class names to target style rules / JS behavior it creates, or that core/extension class names should not be used in wiki page content or gadget-generated markup as a way of reusing styling / JS behavior defined in core/extensions. From the context I assume this is about the latter.

(Also, presumably styling created with the express purpose of being widely reusable, such as OOJS or Codex, is an exception from this?) Tgr (WMF) (talk) 03:21, 2 August 2023 (UTC)

Yes this all makes sense. Done in https://www.mediawiki.org/w/index.php?title=User:Jdlrobson/Stable_interface_policy/frontend&diff=next&oldid=6058183 Jdlrobson (talk) 22:11, 4 August 2023 (UTC)

> this MUST be documented in the source-controlled code using the @public ans @since keywords and linking to the on-wiki discussion

At a high level, documenting this is a great idea but other than for JS code, it's not obvious how - class names don't have a single point of definition like JS methods do, if the class is used in many different places in the stylesheet or the HTML template (or HTML-generating PHP or JS code), there isn't really an obvious place and way to do it. Not sure what can be done to improve that (maybe some kind of registry? but detaching documentating from live code, even within the same codebase, usually results in the documentation not being well-maintained).

Also, there doesn't seem that much point in linking to a discussion. We don't link to any discussion in @stable doc blocks either. There should be a way to understand why the given thing is public, but git-blaming and looking at the commit summary or task description is usually sufficient IMO. Tgr (WMF) (talk) 03:31, 2 August 2023 (UTC)

I wonder if it would make sense to use dedicated class names. mw-stable- sounds awkward as a prefix, but it does avoid the documentation problem somewhat. Tgr (WMF) (talk) 03:45, 2 August 2023 (UTC)

I agree with the problem but am not sure about the solution. I've broken this out into https://www.mediawiki.org/w/index.php?title=Talk%3AStable%20interface%20policy/Frontend#h-Proposal_for_using_%60mw-stable-%60_prefix_for_classes_that_can_be_considered_stable-20230804221400 so it's not lost. Jdlrobson (talk) 22:15, 4 August 2023 (UTC)

> As a general rule, popularity can be judged by 50+ scripts in MediaWiki namespace or more than 1000 scripts across the user and MediaWiki namespace.

This is intended to say "50+ different scripts or 1000+ users", right? (And would also apply to a gadget with 1000+ users / multiple gadgets with 1000+ users in total?) And that in total across all wikis?

This seems complicated to calculate; if user scripts are copied verbatim, global search works, but for gadgets or scripts loaded via importScript it doesn't. Would be nice to have a tool for that... (I'm not suggesting the policy should be blocked on that, to be clear.) Tgr (WMF) (talk) 03:43, 2 August 2023 (UTC)

Also at the very end it says

> For changes that impact more than 10 gadgets (MediaWiki namespace) and/or 1000+ user scripts (user namespace)

so the numbers should probably be unified. Tgr (WMF) (talk) 05:40, 2 August 2023 (UTC)

I've broken this out into https://www.mediawiki.org/w/index.php?title=Talk%3AStable%20interface%20policy/Frontend#h-Improving_our_definition_of_popular_gadgets-20230804221800 Jdlrobson (talk) 22:18, 4 August 2023 (UTC)

> In the case of renaming IDs where the class might be mistakenly considered stable per definition of the stable interface (such as due to historic association with the mw- prefix), developers SHOULD consider a longer grace period.

"renaming IDs where the class" -> "renaming IDs which" ?

The link points to the top of its own section; I'm not sure what it's supposed to communicate. The section doesn't say which IDs might be mistakenly considered stable (fair enough, it's hard to define what mistakes people might make, but then the link is just confusing).

I'm skeptical of extra grace periods, people tend to leave fixing their code to the last minute (or after that) anyways. I don't think we'd get much value out of it. Tgr (WMF) (talk) 03:54, 2 August 2023 (UTC)

I agree about the grace period, but when breakages do happen, it is helpful to point out that time was available and the change was communicated. For example I had about 3 different people complain to me when we removed jquery.tipsy, but that had been deprecated for 10 years.

Made some adjustments here: https://www.mediawiki.org/w/index.php?title=User:Jdlrobson/Stable_interface_policy/frontend&diff=next&oldid=6058185 Jdlrobson (talk) 22:24, 4 August 2023 (UTC)

> In the case of renaming classes, it is recommended that the new class SHOULD be added along with the removed class for at least one MediaWiki release cycle.

Is the thinking here that third-party extensions might do some kind of HTML processing? From a gadget (or bot etc) maintainer's perspective, one release cycle could be anywhere between half a year and one week; it's not a very useful unit of time. Tgr (WMF) (talk) 03:57, 2 August 2023 (UTC)

Yes! https://www.mediawiki.org/w/index.php?title=User:Jdlrobson/Stable_interface_policy/frontend&diff=next&oldid=6058190

I think we can re-evaluate the timelines through experience. Jdlrobson (talk) 22:26, 4 August 2023 (UTC)

> All HTML classes prefixed with mw- generated by MediaWiki core.

I think this is missing a verb? I'm not sure of the intended meaning.

> Note: code outside MediaWiki core SHOULD NOT use the mw- prefix as it can confuse gadget developers by suggesting a stable API.

I don't think this is a convincing rationale (there might be other valid reasons to limit this prefix to core, of course). Either we think mw- is taken to mean a stable API and we want to honor that to some extent; then no new code should use the prefix, neither core nor extension. Or we think that once the policy is published, gadget developers should know better, so while we don't want to break old code using mw- classes, no script has any business using new mw- prefixed classes (new in the sense that the class was introduced after the policy went into effect); in that case, there is no reason extensions can't create such classes.

(BTW it might be worth mentioning in the definitions section that "extension" always means extension or skin.) Tgr (WMF) (talk) 04:04, 2 August 2023 (UTC)

Also the request to avoid an mw- prefix in extensions conflicts with the mention of mw-abusefilter- as a valid extension prefix below. Maybe what's meant is that extensions should be using a unique prefix? Or is "code outside MediaWiki core" rather meant to be "code outside MediaWiki" (e.g. gadget code)? Tgr (WMF) (talk) 04:51, 2 August 2023 (UTC)

I believe this was fixed by https://www.mediawiki.org/w/index.php?title=User%3AJdlrobson%2FStable_interface_policy%2Ffrontend&diff=6054327&oldid=6053926. Jdlrobson (talk) 22:27, 4 August 2023 (UTC)

> MediaWiki developers SHOULD provide and request APIs to access elements or extend existing elements.

Would be nice to offer some guidance on how such requests should be made. (Maybe there should be a Phab tag?)

Also it's not very clear what this means outside Javascript. If I want to change the styling of an element, should I ask for dedicated CSS classes? Tgr (WMF) (talk) 04:49, 2 August 2023 (UTC)

Handled in https://www.mediawiki.org/w/index.php?title=User%3AJdlrobson%2FStable_interface_policy%2Ffrontend&diff=6058194&oldid=6058191.

Regarding " If I want to change the styling of an element, should I ask for dedicated CSS classes?" I've interpreted this to mean you are relying on certain styles. Presumably a gadget can make its own markup with its own classes to change its own styling e.g.

<button class="my-gadget-custom-btn"></div>

Please create a new topic if there is more to discuss here. Jdlrobson (talk) 22:32, 4 August 2023 (UTC)

> Share code between modules privately, using require and module.exports to circumvent this.

I have very mixed feelings about this. Limiting the stable interface is of course a good thing, but private JS functions via closures are an anti-pattern IMO as it makes debugging much more inconvenient. I wonder if it would make sense to adopt an underscore notation like e.g. Python does. (ES2022 privates are a nice best-of-both-worlds approach but I imagine support for that is quite far away.)

> See mediawiki.String (and mediawiki.Title) as an example of how to share code privately using module.exports and require( '<modulename>' ).

I don't understand this example, there is nothing private going on here. Anyone can require the String module and access the same functionality. I would have expected something about packageFiles and requiring files from the same module. Tgr (WMF) (talk) 05:01, 2 August 2023 (UTC)

I'm not sure exactly what you mean here by "private JS functions via closures are an anti-pattern IMO". The essence of this text is to say don't put things on the mw object.

If this edit doesn't resolve your concerns here please could you open a new topic to discuss further?

https://www.mediawiki.org/w/index.php?title=User%3AJdlrobson%2FStable_interface_policy%2Ffrontend&diff=6058204&oldid=6058194 Jdlrobson (talk) 22:49, 4 August 2023 (UTC)

> Code that has indicated it is stable in its JavaScript documentation, preferably using the @stable tag.

It's not clear from the documentation: if a property or module is marked as stable, does that automatically mean all its publicly accessible children are also stable? (Ie. do you need to tag stableMethod in the examples as stable, and could you have require('foo').bar where foo itself is stable but bar is not?) Tgr (WMF) (talk) 05:07, 2 August 2023 (UTC)

Qualified per https://www.mediawiki.org/w/index.php?title=User%3AJdlrobson%2FStable_interface_policy%2Ffrontend&diff=6058206&oldid=6058204 Jdlrobson (talk) 22:50, 4 August 2023 (UTC)

> 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.

Instead:

When removing an already deprecated module, this also MUST be documented in RELEASE_NOTES.

(Since the other documentation criteria was a MUST, I think it makes sense to use that here as well. The rest of the sentence can be omitted, it just repeats a previous bullet point.) Tgr (WMF) (talk) 05:19, 2 August 2023 (UTC)

Done in https://www.mediawiki.org/w/index.php?title=User:Jdlrobson/Stable_interface_policy/frontend&diff=next&oldid=6058206

Thanks! Jdlrobson (talk) 22:52, 4 August 2023 (UTC)

> MediaWiki developers SHOULD use feature flagging (such as Extension:BetaFeatures or user preferences) in deployments to allow editors to test interfaces prior to development

SHOULD -> MAY? Preferences bloat is a bad thing (especially given how bad our preferences UI is), BetaFeatures is significant overhead, so this might work for major new self-contained UI components, but isn't practical most of the time. Tgr (WMF) (talk) 05:39, 2 August 2023 (UTC)

Makes sense. https://www.mediawiki.org/w/index.php?title=User:Jdlrobson/Stable_interface_policy/frontend&diff=next&oldid=6058207 Jdlrobson (talk) 22:53, 4 August 2023 (UTC)

> If any gadgets/scripts are impacted, then MediaWiki developers SHOULD notify m:Tech/News.

Should this also be a requirement whenever stable interfaces are changed, regardless of whether they are actively used in gadgets? Remarks earlier in the policy seem to imply so but it's not explicitly said anywhere. Tgr (WMF) (talk) 05:53, 2 August 2023 (UTC)

Done in https://www.mediawiki.org/w/index.php?title=User%3AJdlrobson%2FStable_interface_policy%2Ffrontend&diff=6058210&oldid=6058209 Jdlrobson (talk) 22:55, 4 August 2023 (UTC)

> When learning about the breakage of gadgets on wiki that are not covered by the wiki-hosted code policy

Not clear what this refers to. Gadgets on third-party wikis? Tgr (WMF) (talk) 05:53, 2 August 2023 (UTC)

Done in https://www.mediawiki.org/w/index.php?title=User:Jdlrobson/Stable_interface_policy/frontend&diff=next&oldid=6058210 Jdlrobson (talk) 22:56, 4 August 2023 (UTC)

The document doesn't mention soft-deprecation / @deprecated; should that be applied in a similar manner as in PHP code? (In JS code, at least; in CSS / HTML we can't really differentiate between soft and hard deprecation.) Tgr (WMF) (talk) 07:05, 2 August 2023 (UTC)

Done in https://www.mediawiki.org/w/index.php?title=User:Jdlrobson/Stable_interface_policy/frontend&diff=next&oldid=6058211. Jdlrobson (talk) 23:03, 4 August 2023 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Timeline

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

The draft says

> MediaWiki developers have a responsibility to respect gadget developers' existing work by over-communicating any changes to HTML markup while this policy is rolled out

which can be read in a couple different ways, but since publishing a policy doesn't magically update all gadget code (consider how long it usually takes to fully process large-scale deprecations in MediaWiki code, and there we have the benefit of good search, static code analyzers, test environments etc..), I guess we'd want a multi-year transition period where we should do that? Tgr (WMF) (talk) 03:24, 2 August 2023 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Consider replacing @stable tag with a different approach to public documentation

The use of @stable doesn't have any effect in frontend code. Perhaps in a future iteration of the frontend stable policy this could be replaced by "Publish visible documentation on docs.wikimedia.org" and use @ignore for code that shouldn't be consider stable. I think https://phabricator.wikimedia.org/T138401 would be a blocker for doing this and we'd need to revamp our approach to published documentation (e.g. only publish content that is stable rather than publish everything). Jdlrobson (talk) 18:13, 2 August 2023 (UTC)

Proposal for using `mw-stable-` prefix for classes that can be considered stable

Current text: > In cases where it might be mutually beneficial for wiki-hosted code developers and MediaWiki developers to share code, for example for performance reasons, this MUST be documented in the source-controlled code using the @public and @since keywords and linking to the on-wiki discussion. HTML classes that do wish to be considered stable MUST add an inline comment indicating in which MediaWiki version they were introduced using the @since annotation and must follow the deprecation process in the relevant section below.

In https://www.mediawiki.org/w/index.php?title=Talk%3AStable%20interface%20policy/Frontend#c-Tgr_%28WMF%29-20230802033100-Tgr_%28WMF%29-20230802032000 @tgr rightly suggests this is hard to document and suggests that instead we could make the class itself declare that it is stable.

I like the idea but wanted to run this by a few people before adding. I'm also not sure if we have any classes that would want to behave in this way so we may also want to evaluate dropping this in a future version of the policy. Jdlrobson (talk) 22:14, 4 August 2023 (UTC)

Improving our definition of popular gadgets

In https://www.mediawiki.org/w/index.php?title=Talk%3AStable%20interface%20policy/Frontend#h-Comments_from_Tgr-20230802032000 Tgr (WMF) raises that our current definition does not taken into account importScript.

Does anyone else have any ideas for improving how we evaluate?

Some off the topic of my head:

• The Gadgets tab on Special:Preferences page could count users in a similar way to Extension:BetaFeatures. This would be also useful for turning off seldom used gadgets.
• We could go by page views (e.g. hits to the .js pages with ctype query string) Jdlrobson (talk) 22:18, 4 August 2023 (UTC)

en.wp has w:Wikipedia:User scripts/Most imported scripts. Izno (talk) 22:21, 4 August 2023 (UTC)

The Gadgets tab does count users (that's Special:GadgetUsage, already mentioned in the policy); what's not counted is loading a user script from your personal common.js via mw.loader.load / importScript / etc. Definition-wise "number of users of the script" is clear, it's just often not very convenient to determine.

Page views would be nice but even more effort, I think - we don't have good patterns for creating tooling that works with private data. The number of users who installed a script could be counted by a toolforge tool (if it's a gadget, check Special:GadgetUsage; it it's a user script, do a global search for common import patterns; repeat the whole thing for all interwikis), someone would just have to write it first. Tgr (WMF) (talk) 00:34, 5 August 2023 (UTC)

My concern with counting references to importScript is many of these are pages for inactive users. I think if we took this approach we would need to be more proactive about blanking user script pages for inactive users. Jdlrobson (talk) 18:13, 5 August 2023 (UTC)

It would be nice to do _something_ about the imported user scripts of inactive/usurped users. SBassett (WMF) (talk) 14:39, 7 August 2023 (UTC)

As a general rule, popularity can be judged by 50+ scripts in MediaWiki namespace or more than 1000 scripts across the user and MediaWiki namespace impacted by any given change

Our popularity definition currently only applies to MediaWiki and user namespace.

This came up recently in phab:T182050 although this was for pages using MediaWiki CSS (which is not covered by the stable policy and is using an unstable interface).

A change that impacted 580 pages and 1209 subpages (many translated) in the main namespace was interpreted as "widespread breakage". Do people think this a fair assessment?

I am starting to wonder if it makes sense to require communication for all changes where we know that there's impact (at least for CSS), but that also seems like a lot of overhead on developers.

This has definitely flagged a gray area in the frontend stable policy and how it can be interpreted so I'd like to improve our definition one way or another. Jdlrobson (talk) 18:32, 2 January 2024 (UTC)

Suggested addition

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

While reorganizing the document as part of Talk:Stable interface policy/Frontend#h-Guidance_for_consumers_vs_guidance_for_providers-20230726174100 I noticed that there is no advice around communicating changes to other extensions / skins.

I'd like to add the following text to Stable_interface_policy/frontend#How_providers_should_communicate_changes_to_consumers. Please reply here if you have any concerns with that text by Friday 11th August.

Communication of changes to other MediaWiki developers

• If code running on Wikimedia sites is impacted by breaking changes, developers MUST open Phabricator ticket(s) tracking the issue for impacted skins and/or extensions. The Phabricator ticket(s) should tag the impacted project and detail the timeline for the removal and provide details on the required change.
• Developers MAY provide patches, and are encouraged to do so especially in the case where the fix is simple. Jdlrobson (talk) 22:39, 8 August 2023 (UTC)

Is this meant to be one-task-for-each-impacted-extension, or one overall task, or either as appropriate? Jdforrester (WMF) (talk) 14:05, 10 August 2023 (UTC)

Either or. I've revised this text with that in mind. Thanks for pointing this out! Jdlrobson (talk) 18:43, 10 August 2023 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Package files example

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

I still don't get this sentence:

Share code between modules using ResourceLoader/Package files (using module.exports and require( '<modulename>' )) to avoid methods on the public mw object. See mediawiki.String as an example of a module that is not defined on the mw object and limited to ResourceLoader modules including mediawiki.Title.

The examples aren't package files and don't really avoid public methods (mediawiki.String shares its functionality by defining itself as a publicly callable module; the document even says elsewhere that all ResourceLoader modules inside MediaWiki core must be considered stable).

Maybe I'm misunderstanding the point being made here, but I'd expect something like this:

Share code between modules using ResourceLoader/Package files (using module.exports and require( '<filename>' )) to avoid methods on the public mw object. See OptionalParamWidget.js as an example of a class that is not defined on the mw object and can only be used by mediawiki.special.apisandbox.

Tgr (WMF) (talk) 02:10, 9 August 2023 (UTC)

Yes this seems like a much better example! Thanks! Jdlrobson (talk) 21:43, 10 August 2023 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

"MediaWiki developer's"

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

@Jdlrobson: The phrase "MediaWiki developer's" in this edit was meant to be plural (developers) rather than genitive (developer’s), wasn’t it? I also don’t understand why it’s in quotation marks. Tacsipacsi (talk) 15:45, 11 August 2023 (UTC)

Thanks for pointing that out! Fixed in https://www.mediawiki.org/w/index.php?title=User%3AJdlrobson%2FStable_interface_policy%2Ffrontend&diff=6066442&oldid=6066441 Jdlrobson (talk) 23:33, 11 August 2023 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Slightly confusing example

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

To give a concrete example: Wiki-hosted code SHOULD NOT manually replicate the HTML markup of a dropdown menu in Vector, using Vector's stylesheets as the gadget incorrectly assumes the HTML markup of the dropdown menu is stable.

The sentence structure here seems slightly confusing and I don't think it really explains what the issue is, perhaps rewording to "Wiki-hosted code SHOULD NOT manually replicate the HTML markup of a dropdown menu in Vector, using Vector's stylesheets, as both the html structure of the menu and the content of the stylesheet are considered unstable and may change" would make the problem clearer?

Perhaps it would also be worth adding a pointer to what developers should do instead? e.g. "Instead wiki-hosted code should use the addPortletLink function to add additional menu items, because as part of the mw object it would be considered stable." 192.76.8.66 (talk) 18:24, 15 August 2023 (UTC)

This all sounds great. Your wording is a lot more elegant! Thanks for the suggestion. I will fold it in with the next round of edits. Jdlrobson (talk) 20:10, 15 August 2023 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Missing bold text for "Communication of changes to other MediaWiki developers" section

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

Hi,

I've noticed that the "Communication of changes to other MediaWiki developers" section doesn't have the "MUST" or "MAY" words bolded. This is in contrast with the rest of the page.

Thanks, Dreamy Jazz (talk) 16:27, 21 August 2023 (UTC)

Thanks for pointing this out! I'll fix that in the next round of edits! Jdlrobson (talk) 00:53, 22 August 2023 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Should we do more before deprecating modules?

Currently the stable policy in the "What providers should do when removing ResourceLoader modules" section says:

"Developers MAY fix consumers of a module prior to deprecation, but doing so is not required as a precursor to deprecation."

The reasoning here was that developers should be paying attention to the developer console and the deprecation message appearing there should be sufficient to notify maintainers of their responsibility.

When deprecating, do we have more of a responsibility to fix things prior to the deprecation?

One downside of this, is deprecations would take longer and not work as they have traditionally. For example jquery.ui was deprecated 8+ years ago and consumers in Wikimedia production remain. Strengthening this to a SHOULD or MUST might make deprecations substantially more work and slower.

What do people think? Jdlrobson (talk) 21:19, 15 September 2023 (UTC)

At the time of the deprecation, maybe the Tech News entry could be a MUST (even if there is no known usage, as there can be usage using string concatenation that cannot be found, or in browser scripts/browser extensions). Generally requiring MediaWiki developers to fix code at the time of deprecation is not only more work, but may also lead to worse results, as authors of the wiki-based code are probably best equipped to fix that. (In specific cases, e.g. if a module was simply renamed or merged/split, MediaWiki developers may be equipped just as well, but judging this should be up to the developers doing the deprecation. Migrating from jQuery UI to OOUI/Codex is a perfect example for a change that is better done by people who know the code: one needs to consider things OOUI/Codex doesn’t provide (non-modal windows, draggable windows etc.), things that only OOUI/Codex provides and could be taken advantage of (e.g. new input types), maybe OOUI/Codex even needs new strings that a MediaWiki developer not speaking the language cannot create, and so on.)

However, it may (or may not) make sense to require MediaWiki developers to clean up remaining known usage before completing the deprecation, as trying to use removed modules can cause serious breakage (and maybe even log spam, at least if these removed module dependencies are defined statically, in gadget definitions?). In this case, the on-wiki code being fixed by a MediaWiki developer is the alternative to it not being fixed at all and thus breaking, so from a user perspective, fixing is definitely better – the only downside is spending developers’ time that may be used more meaningfully. Tacsipacsi (talk) 10:56, 16 September 2023 (UTC)

Some confusion around guidance to accessing DOM elements

We currently make clear that consumers should not rely on HTML elements and instead rely on API abstractions that allow us to make changes with less disruption.

For example, the following code would be considered stable:

$( '<div>Hello world</div>').prependTo( mw.util.$content );

The following code wouldn't:

$( '<div>Hello world</div>').prependTo( '#content' );

In the feedback received during August and September, it came to my attention that this was possibly not as clear as it could have been.

I have since made some edits to style to clarify this, and if it can be improved further I would appreciate any feedback. Jdlrobson (talk) 21:35, 15 September 2023 (UTC)

This is an excellent example, could you add it to the doc? I think that would make things a lot clearer... DKinzler (WMF) (talk) 09:20, 17 September 2023 (UTC)

I've made some modifications here: https://www.mediawiki.org/w/index.php?title=Stable_interface_policy%2FFrontend&diff=6119504&oldid=6113967

Is that sufficient or is there more we can do here? Jdlrobson (talk) 21:25, 21 September 2023 (UTC)

Policy is now official, notice of changes during feedback period

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

Hi all, on August 11th 2023, I posted to wikitech-l and tech news the intention to make this policy official.

During the feedback period no vetoes were voiced, but there was various feedback around the structure and phrasing of the document.

For full transparency, the edits I have made during the feedback period can be reviewed in full here: https://www.mediawiki.org/w/index.php?title=Stable_interface_policy%2Ffrontend&diff=6107667&oldid=6065454 (see history for a more granular view of the changes)

These changes should not change the meaning of the document, but if you believe any of those edits have done that, please do reply to this thread so they can be discussed and rectified ASAP.

Thank you to all those that have engaged with this document and got us to this stage! Jdlrobson (talk) 22:02, 15 September 2023 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Process for making amendments

I would like to define a process for making future amendments to this document. Please help me!

The following seems like a reasonable starting point:

Fixing typos: Editors are free to correct typos and grammar without any process. Making translations: Editors are invited and encouraged to translate the document. When translating, they should refer to the revision of the document and the date and time of the translation. Amendments to content: I propose that topics are first posted on the talk page, and that at least a month of discussion is given. When there are no unresolved vetoes, the proposer of the topic can make the adjustment.

Any thoughts? Jdlrobson (talk) 22:05, 15 September 2023 (UTC)

Translations should preferably be done using Extension:Translate – it provides automatic updates and highlights outdated translations (instead of referring to a possibly outdated revision), and provides a better translator UX. Your proposals for the typo fix and content amendment processes seem reasonable to me. Tacsipacsi (talk) 11:00, 16 September 2023 (UTC)

Technical writing request underway

The following discussion is closed. Please do not modify it. Subsequent comments should be made on the appropriate discussion page. No further edits should be made to this discussion.

---

In case anyone here is interested, a technical writing review is still in progress for this document. Feel free to point out any problems in the phabricator ticket here: https://phabricator.wikimedia.org/T341532 Jdlrobson (talk) 22:23, 15 September 2023 (UTC)

The discussion above is closed. Please do not modify it. No further edits should be made to this discussion.

Requiring documentation on docs.wikimedia.org

In Stable_interface_policy/Frontend#JavaScript_code we state "Note: Clearer documentation guidelines will be provided as part of phab:T138401."

I'd like to propose that stable code MUST be documented on docs.wikimedia.org. While using the stable tag is a helpful indicator, having it discoverable on the documentation is probably the most ideal situation.

One implication of this would mean that extensions/skins that provide stable APIs would need to publish documentation on docs.wikimedia.org.

What thoughts do people have on this? Jdlrobson (talk) 23:31, 18 June 2024 (UTC)

I think I'd support this... —TheDJ (Not WMF) (talk • contribs) 16:10, 19 June 2024 (UTC)

+1, seems a reasonable consequence of what we mean by "stable code". Jdforrester (WMF) (talk) 12:56, 20 June 2024 (UTC)

I’d say stable code SHOULD be documented on doc.wikimedia.org. In some cases, it may be more desirable to provide documentation on mediawiki.org pages or via other means. As you write, discoverability is the most ideal situation; other factors (like maintainability) may overrule this. Tacsipacsi (talk) 15:49, 22 June 2024 (UTC)

Remove note regarding ambiguous contracts

In Stable_interface_policy/Frontend#JavaScript_code we have a note:

> "Note: We aim to clarify stable contracts where ambiguous before the 1.42 release as part of phab:T348076 by adding @stable, @ignore and @internal tags. Please bear with us while we perform this cleanup of our documentation!"

This window has passed so I'd like to propose remove this note. This would mean any ambiguously defined code is now stable.

Any concerns with us doing this? Jdlrobson (talk) 23:33, 18 June 2024 (UTC)

Maybe turn it into something like "Stable interface contracts should now be in place; if you think one is mis-labelled or should become stable where it currently is not, please raised a ticket."? Jdforrester (WMF) (talk) 12:57, 20 June 2024 (UTC)