Page MenuHomePhabricator

Allow deprecating extension configuration settings via extension.json
Open, Needs TriagePublic

Description

Since MW 1.29, we can use an object to represent different information about an extension configuration setting, for example a localized description as well as public/private information. In this aspect, extensions are much superior to core (afaik), where configuration settings are initialized dynamically from DefaultSettings.php instead of static metadata.

This allows us to add functionality to deprecate configuration settings. At first, I thought a bool would do the job, but after putting some further thought into it, I think we need an object like this:

"SomeExampleSetting" : [
  "value": [],
  "deprecated": {
    "mw-version": "1.32",
    "ext-version": "2.2",
    "comment": "The migration period will end with version 3.0."
  }
}

If the deprecated key is present, the configuration setting is deprecated, all properties are optional. Developers can either specify with which MediaWiki version they deprecated the setting or specify a respective extension version. Both might be fine as well, but could be confusing in some cases.

ExtensionRegistry will check if the user has overwritten the global in his LocalSettings and throw a deprecation warning in this case. This is trivial for non-array settings: Just check for deprecation in ExtensionRegistry->exportExtractedData( $info ) and throw a nice deprecation warning. The required information could be contained in $info['config']['SomeExampleSetting']['deprecated']. (I thought about $info['deprecations']['globals']['SomeExampleSetting'] before, but this seems much better.)

For arrays, it's a bit more complicated. I think $info['config'] only contains settings that are defined by extensions and aren't modified by other extensions, so it should propably work.

Event Timeline

I'm interested to work on this.

I like the idea.

What would the version numbers be used for? Just for human consumption?

I would suggest having a difference between soft and hard deprecation. Soft would trigger warnings in some development tools, while hard would trigger warnings at run-time and in production.

I like the idea.

What would the version numbers be used for? Just for human consumption?

Primarily yes, to construct an error message and to use for static analysis for other tools. In theory, you could add some functionality to silence the deprecation notice if extension/mediawiki version is smaller than deprecation version… However, this creates unclear semantics and adds unnecessary complexity to this feature I would like to avoid.

I would suggest having a difference between soft and hard deprecation. Soft would trigger warnings in some development tools, while hard would trigger warnings at run-time and in production.

Personally, soft deprecation has never been something I was particularly fond of. Nevertheless, I wouldn't mind implementing it. In this case, I think both version properties should be associated with soft deprecation.

What would you suggest here? Sounds a bit more complex than just using wfDeprecated / MWDebug::deprecated (or something similar, as this doesn't seem flexible enough to support an extension version or a custom message (yet).), as this only supports one error level which can only be modified by changing $wgDevelopmentWarnings.