$wgResourceModules documentation is incomplete
Closed, ResolvedPublic
Actions

Description

I was looking how to include config variables with modules and noticed the documentation for $wgResourceModules is very incomplete.

For example https://www.mediawiki.org/wiki/Manual:$wgResourceModules does not mention noflip, targets or templates or packageFiles. The documentation in DefaultSettings.php is even less complete.

These options are mentioned in docs/extension.schema.v2.json, but even there it doesn't really explain how to use packageFiles.

Currently best documentation seems to be the doc for constructor in includes/resourceloader/ResourceLoaderFileModule.php, but even that fails to mention noflip.

Details

	Subject	Repo	Branch	Lines +/-
	resourceloader: Improve wgResourceModules documentation	mediawiki/core	master	+234 -222
	resourceloader: Add more $wgResourceModules documentation	mediawiki/core	master	+278 -66

Customize query in gerrit

Related Objects

Mentioned In: T239666: RESTBase requests to Parsoid/PHP that contain a "." in the title (without a /<revid> component) fail with a http 403
T231326: Use ResourceLoader package files to reduce number of CX modules

Event Timeline

Nikerabbit created this task.Sep 11 2019, 7:00 AM

Restricted Application added a project: Performance-Team. · View Herald TranscriptSep 11 2019, 7:00 AM

Restricted Application added a subscriber: Aklapper. · View Herald Transcript

Nikerabbit mentioned this in T231326: Use ResourceLoader package files to reduce number of CX modules.Sep 11 2019, 7:00 AM

We've documented packageFiles at https://www.mediawiki.org/wiki/ResourceLoader/Package_modules.

I'll make sure to link this from various places.

For the other properties, those are primarily documented in-place with Doxygen (the wiki page is essentially an outdated copy of that).

I'll make sure both are up to date, possibly by linking one to the other so as to not need to keep these and all other config/class docs in two places.

Krinkle moved this task from Inbox to Confirmed Problem on the MediaWiki-ResourceLoader board.Sep 13 2019, 5:59 PM

Krinkle removed Krinkle as the assignee of this task.Sep 14 2019, 6:16 PM

Krinkle moved this task from Inbox, needs triage to To-do: Goals, prioritized next 4 Quarters on the Performance-Team board.Sep 23 2019, 8:34 PM

ssastry mentioned this in T239666: RESTBase requests to Parsoid/PHP that contain a "." in the title (without a /<revid> component) fail with a http 403.Dec 3 2019, 3:24 AM

• WDoranWMF assigned this task to • holger.knust.Feb 6 2020, 5:55 PM

• WDoranWMF added a project: Platform Team Workboards (Clinic Duty Team).

• WDoranWMF moved this task from Inbox to Ready (WIP:5) on the Platform Team Workboards (Clinic Duty Team) board.

Krinkle moved this task from To-do: Goals, prioritized next 4 Quarters to Doing (old) on the Performance-Team board.Feb 6 2020, 6:24 PM

I added the missing options to https://www.mediawiki.org/wiki/Manual:$wgResourceModules
page and sorted them by key name. Should I also sort the key names in the JSON file
(docs/extension.schema.v2.json)?

Do we need a more comprehensive example in DefaultSettings.php? Or just on the page above?

@holger.knust I think we may want to move the (now updated) docs from the wiki page to DefaultSettings.php indeed. We can then remove replace the old comment at ResourceLoaderFileModule.php with a @see reference to $wgResourceModules, and once merged update the wiki to refer to doc.wikimedia.org. That's the general pattern I've followed for most docs in components Perf Team maintains for its classes and site config variables. (Using wiki pages only for high-level architecture and user manuals for instaling or upgrading something).

This has the benefit of being maintained in context with the code (usually updated in the same commit), and naturally reviewed/published in a versioned manner (e.g. docs for mediawiki/objectcache@MW 1.33.1). It's a trade off for sure though, so I don't mind having this link the other way around for now (from DefaulSettings/ResourceLoaderFileModule to the wiki).

• WDoranWMF moved this task from Ready (WIP:5) to Doing(WIP:5) on the Platform Team Workboards (Clinic Duty Team) board.Mar 24 2020, 1:54 PM

• WDoranWMF moved this task from Doing(WIP:5) to Ready (WIP:5) on the Platform Team Workboards (Clinic Duty Team) board.Mar 24 2020, 2:57 PM

• holger.knust moved this task from Ready (WIP:5) to Doing(WIP:5) on the Platform Team Workboards (Clinic Duty Team) board.Mar 24 2020, 3:19 PM

Change 583476 had a related patch set uploaded (by Holger Knust; owner: Holger Knust):
[mediawiki/core@master] mediawiki: $wgResourceModules documentation is incomplete

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

gerritbot added a project: Patch-For-Review.Mar 25 2020, 11:06 PM

• holger.knust moved this task from Doing(WIP:5) to Waiting for Review on the Platform Team Workboards (Clinic Duty Team) board.Mar 26 2020, 5:37 PM

Change 583476 merged by jenkins-bot:
[mediawiki/core@master] resourceloader: Add more $wgResourceModules documentation

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

ReleaseTaggerBot added a project: MW-1.35-notes (1.35.0-wmf.26; 2020-03-31).Mar 29 2020, 5:00 PM

Maintenance_bot removed a project: Patch-For-Review.Mar 29 2020, 5:10 PM

Now up at https://doc.wikimedia.org/mediawiki-core/master/php/search.php?query=$wgResourceModules.

It seems still impossible to figure out since what version has packageFiles been supported. There is no mention in HISTORY or RELEASE-NOTES and quick code search does not bring up any @since tags. The answer seems to be 1.33 based on https://gerrit.wikimedia.org/r/c/mediawiki/core/+/471370

Change 643785 had a related patch set uploaded (by Krinkle; owner: Krinkle):
[mediawiki/core@master] resourceloader: Improve wgResourceModules documentation

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

gerritbot added a project: Patch-For-Review.Nov 27 2020, 2:47 AM

Krinkle reopened this task as Open.Nov 27 2020, 2:50 AM

Krinkle claimed this task.

Krinkle moved this task from Doing (old) to Blocked (old) on the Performance-Team board.

Krinkle added a subscriber: • holger.knust.

Change 643785 merged by jenkins-bot:
[mediawiki/core@master] resourceloader: Improve wgResourceModules documentation

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

Maintenance_bot removed a project: Patch-For-Review.Jan 16 2021, 10:10 PM

ReleaseTaggerBot added a project: MW-1.36-notes (1.36.0-wmf.27; 2021-01-19).Jan 16 2021, 11:00 PM