Change 574542 had a related patch set uploaded (by Niedzielski; owner: Stephen Niedzielski):
[mediawiki/extensions/Popups@master] [Special:Preferences] [PHP] Position Popups' prefs below skin prefs

https://gerrit.wikimedia.org/r/574542

Change 574542 abandoned by Niedzielski:
[Special:Preferences] [PHP] Position Popups' prefs below skin prefs

Reason:
Abandoning until needed.

https://gerrit.wikimedia.org/r/574542

Change 575102 had a related patch set uploaded (by Jdlrobson; owner: Jdlrobson):
[mediawiki/skins/Vector@master] Make sure Vector skin preferences always follows skin

https://gerrit.wikimedia.org/r/575102

Thinking about this some more the easiest way to do this is to nest the preference under the skin itself. It's position is guaranteed to be above Popups. I've demonstrated this in https://gerrit.wikimedia.org/r/575102

Change 575102 merged by jenkins-bot:
[mediawiki/skins/Vector@master] Make sure Vector skin preferences always follows skin

https://gerrit.wikimedia.org/r/575102

This spike seeks to answer firstly: for all wikis in production, how do Vector skin preferences present themselves? If Vector's onGetPreferences() hook is always executed after Popups' hook, no changes will be necessary. We think that's the case as Vector is the last entry on extension-list.

HOWEVER, if the order cannot be guaranteed, how should we fix that?

• HACK it into Popups and keep on hacking and never stop hacking and always be hacking?

That is for sure inconvenient, but I don't think it's as crazy as you make it seem. The code is weird but the result is well-defined, and it's unlikely to break terribly.

MediaWiki uses ordered associative arrays in other places too, so it's not entirely outlandish (in our small ecosystem, at least), e.g. when defining the order of menu items in skins (https://github.com/wikimedia/mediawiki-extensions-VisualEditor/blob/cc557cfef508fdf3f1388b4c7809ab3b79de2dcb/includes/VisualEditorHooks.php#L494 – we used a different approach to affect the order, yours actually seems a bit neater).

• Revise the API?

As long as it is backwards-compatible, that seems like a nice idea. I've seen similar approaches elsewhere (e.g. if you've ever looked at Phabricator's code… it orders user settings in a similar way, by defining numbers which are compared to each other: https://github.com/wikimedia/phabricator-extensions/commit/9f897dbcb9cbebea42ad716633da3bcf83e315de#diff-e6f99b1e58a88d7d37a84495d7573452R19 (no, I don't know what that preference does, apparently it does nothing – I was looking at that code because I was trying to find out :D)).

Code for this is part of HTMLForm, so any changes here would potentially affect not only preferences, but also hundreds of places in core and extensions – please tread carefully if you end up working on this.

In T246162#5922016, @Jdlrobson wrote:

Thinking about this some more the easiest way to do this is to nest the preference under the skin itself. It's position is guaranteed to be above Popups. I've demonstrated this in https://gerrit.wikimedia.org/r/575102

That's cool, and seems to work well. Nested sections are supported by HTMLForm, but it hasn't been used for preferences before, so this code isn't really battle-tested like the rest of the system. It's certainly the most sensible way to get the order right though.

I was worried slightly if this is going to render right in preferences (but it seems fine), and whether Special:GlobalPreferences will handle it right (but it also seems fine – although it has another funny bug your preference triggers, T246491).

We decided to go for the straightforward fix here @matmarex rather than the risky HTMLForm changes. Thanks for the code review and the feedback.

will sign this off along with T242381: Add a Vector skin version preference

This LGTM.

I note that there's a TODO attached to HTMLForm around documenting the behaviour of the section property (see https://gerrit.wikimedia.org/g/mediawiki/core/+/680757355a84d0ce44d5312d5c0f1740adfc0a77/includes/htmlform/HTMLForm.php#129). AFAICT this is a novel usage of the property (see https://codesearch.wmflabs.org/search/?q=%27section%27%20\%3D\%3E%20%27[^%27]*\%2F[^%27]*\%2F) so I see no reason why documentation is out of scope for this task. @Jdlrobson, @matmarex?

@phuedx > https://www.mediawiki.org/wiki/HTMLForm#Parameters

@Jdlrobson: Thanks! Could you also add that line to the DocBlock for HTMLForm and remove the @todo?

The link is already in HTMLForm - https://github.com/wikimedia/mediawiki/blob/master/includes/htmlform/HTMLForm.php#L39.

To be honest I'm not sure when and why we began repeating already documented information - one source of truth that can be translated - mediawiki.org should suffice IMO. Once we've worked out where the canonical source should be (i'm guessing wiki) we can port that documentation.

It's not clear to me where the documentation canonically should live. JDForrester suggests the code is the canonical source. This looks like more work than I anticipated and is not documentation I touched during this change so I'd like to suggest pulling this out into a separate task and having that conversation. This doesn't seem like a priority for me at least right now given the team's priorities.

The discussion of the pros and cons of duplicating documentation between the codebase and mediawiki.org is an important one. I agree that it's out of scope for this task.

This looks like more work than I anticipated and is not documentation I touched during this change so I'd like to suggest pulling this out into a separate task and having that conversation.

Initially, I was confident that copying the updated documentation for that one property, formatting it correctly, removing the @todo at the bottom of the DocBlock, and having a peer review would require less effort overall than creating a new task and shepherding it through our process. Having just looked into how the form on Special:Preferences is built, for example, I agree that this is worthy of a separate task.

Opened https://phabricator.wikimedia.org/T247111