Talk:Stable interface policy/Frontend

Archived topics:

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

Currently open topics:

• Improving our definition of popular gadgets Topic:Xn79rsszgj5hg0kc
• Consider replacing @stable tag with a different approach to public documentation Topic:Xn2fqgancgxt2hut
• Proposal for using `mw-stable-` prefix for classes that can be considered stable Topic:Xn79jnalf1umup0b
• Mailing list for announcements Topic:Xlrhitipsnlphmph
• Making amendments to this document Topic:Xpst7ed32vkcitws
• Feedback request for accessing DOM elements Topic:Xpsrioo1nhgqo4k6
• Approach to deprecating modules Topic:Xpsqnpkczjxy7q3h

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?

I think I'd support this...

+1, seems a reasonable consequence of what we mean by "stable code".

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.

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?

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

In https://www.mediawiki.org/w/index.php?title=Topic:Xn1201q2fbyyb7wj&action=history 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)

en.wp has w:Wikipedia:User scripts/Most imported scripts.

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.

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.

It would be nice to do _something_ about the imported user scripts of inactive/usurped users.

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.

Please read for a summary of changes.

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!

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.

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?

it's not technically correct: js changes can break user scripts too. But naming is hard

How about wiki-hosted-code-announce ?

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.

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.

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.

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!

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?!

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.

Lol sorry! It's actually linking to User:Nardog?action=edit&redlink=1, hence why we were unsure if the ping worked.

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.

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?

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

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?

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.

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.

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.

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.

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.

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.

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

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.

This review is complete!

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

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.

This is an excellent example, could you add it to the doc? I think that would make things a lot clearer...

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?

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?

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.

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?

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.

Reworded in https://www.mediawiki.org/w/index.php?title=User%3AJdlrobson%2FStable_interface_policy%2Ffrontend&diff=6103808&oldid=6103807 - thanks for the suggestion!

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

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.