Stable interface policy - MediaWiki

Stable interface policy - MediaWiki
Jump to content
From mediawiki.org
Languages:
português
This page documents an official
Wikimedia development policy
. There is no current mechanism to make changes, as the
TechCom RFC process
is defunct.
Development policies
Development policy
Architecture principles
Services policy
Support policy for PHP
Gerrit privilege policy
Stable interface policy
frontend
MediaWiki database policy
See also
Development guidelines
Deprecation policies
PHP interfaces
Action API (api.php)
REST APIs
Wikidata APIs
See also
Version lifecycle
Compatibility
The
stable interface policy for MediaWiki PHP code
defines what parts of
the software
are considered stable and safe for use by other components. Code that is considered part of this "stable interface" is subject to the
deprecation process
Quick guide
edit
Using code
edit
It is generally
stable to call
public methods on a class instance.
It is generally
not stable to construct
a class (instantiate).
It is generally
not stable to extend
a class (subclass) and
not stable to implement
an interface.
Writing code
edit
When changing existing code:
Keep
public methods
and
hook signatures
compatible for callers. Follow the
deprecation process
for breaking changes.
Keep
constructor signatures
compatible, if it is marked
@stable to call
Keep
method signatures
compatible for subclasses, if the method is marked
@stable to override
When creating new code:
When defining hooks, keep the signature minimal. Expose narrow interfaces, ideally only pure value objects, as parameters.
Avoid using interfaces as extension points. It is recommended to use an abstract base class instead. See
Stable to extend
Terminology
edit
Authors
: You are working on something that others will use. For example, a class in MediaWiki core that extensions can use.
Users
: You are working on something that uses a stable interface. For example, a class in an extension that interacts with MediaWiki core.
Wikimedia maintained code
is defined as any code running on Wikimedia sites or officially
published
by Wikimedia for use by others.
The
MediaWiki ecosystem
includes community mantained extensions that meet the criteria described in the
"Ecosystem"
section below.
Definition of the stable interface
edit
Stable to call
edit
It's generally
stable to call public methods
and access public class fields – unless these are marked otherwise.
It's generally
not stable to directly instantiate classes
using the
new
operator – unless these are marked as
@newable
Stable to call
can apply to methods and functions. It means they stay backwards-compatible between releases. This stability applies to both the behavior (its contract), and the signature. Breaking changes that would impact callers must follow the
deprecation process
Note that methods are
not stable to override
by default.
Included:
Global functions of which the name starts with the "wf" prefix.
Public methods on any class instance.
Protected methods of a class that is
stable to extend
All methods in traits that are
stable to use
Constructor methods that are marked
@stable to call
. This means their class will be considered "newable" and thus may be instantiated using the
new
operator in any code.
Constructor methods of classes marked
@newable
as well as classes that are
stable to extend
Not included:
Any constructor method, unless marked
@stable to call
Any method or function marked
@deprecated
@internal
or
@unstable
Legacy class methods that do not have an explicit visibility modifier. These are technically public, but considered unstable.
For authors:
It is recommended to only mark constructors as stable to call if they are for value objects or for extendable classes.
When making a constructor method
@stable to call
, consider marking the class it belongs to as
@newable
. This technically provides the stability guarantee, and is used to in discoverability of the stable constructor, and as self-documenting way to encourage a usage pattern through the
new
operator. It is at the author's discretion to decide whether or not to mark a class with a stable constructor as
@newable
. For example, if the class is generally only constructed through an intermediary utility method or subclass, then it may benefit users to not draw attention to the constructor.
For complex classes that may involve
dependency injection
, you should avoid making the constructor stable to call, as this means adding or changing dependencies would constitute a breaking change that requires following the deprecation process.
Stable to type
edit
It's generally
stable to mention interfaces and classes
in type hints for parameters and return values.
Stable to type
can apply to interfaces and classes. It means the type will continue to exist between releases and provide at least the same public methods that are
stable to call
. You can type against these interfaces and classes from various contexts; such as argument type declarations ("type hints"), return types,
catch
statements, and
instanceof
assertions.
Remember that by default interfaces are
not stable to implement
, and thus methods may be widened or added without notice. As PHP requires implementations to define all methods and use the same or narrower signatures, these would normally be breaking changes, but are backwards-compatible for the purpose of typehints and calling methods. For the same reason, an interface may become a class, and a class may become an interface without notice, unless it provides additional guarantees such as
@stable to extend
@stable to implement
, or
@newable
Included:
All classes and interfaces.
Not included:
Any class or interface marked
@deprecated
@internal
or
@unstable
For authors:
Avoid using interfaces as extension points. It is recommended to use an abstract base class instead. See
Stable to extend
When you do create interfaces, it is recommended that you explicitly mark them as
@stable to type
. This is intended to aid the discovery of limited guarantees around interfaces.
Stable to extend
edit
It's generally
not stable to extend classes
– unless these are marked
@stable to extend
. This means constructor signatures may break, protected methods are unstable, and new abstract methods may be added without notice.
Stable to extend
can apply to classes. It means the class and its methods will stay backward-compatible between releases and may be subclassed anywhere. Changes that affect subclasses will follow the
deprecation process
. Protected (and public) methods of extendable classes are automatically
stable to call
, unless they are marked
@deprecated
@internal
or
@unstable
. Remember that by default methods remain not
stable to override
, unless they are abstract.
Included:
Only classes that are marked
@stable to extend
For authors:
Constructor methods of extendable classes must be marked
@stable to call
When allowing extensions to create additional classes of a certain type, it is recommended you provide an abstract base class (marked stable to extend) instead of an interface. This is because is not possible to use deprecation in an interface. If you mark an interface as
stable to implement
, you commit to never changing its method signatures, and never adding new methods – unless the interface as a whole is deprecated first.
Stable to use
edit
It's generally
not stable to use traits
– unless these are marked
@stable to use
. This means method signatures may break and new abstract methods may be added without notice.
Stable to use
can apply to traits. It means all methods defined in the trait will stay backward-compatible between releases, including private methods. Changes that affect classes using the trait will follow the
deprecation process
. All methods of usable traits are automatically
stable to call
, unless they are marked
@deprecated
@internal
or
@unstable
. Remember that by default methods remain not
stable to override
, unless they are abstract.
Included:
Only traits that are marked
@stable to use
Stable to access
edit
It's generally
not stable to write to public and protected fields
, but it is stable to read them.
Stable to access
applies to fields of most classes. It means that the field will not be removed, and its behavior will not change, without going through the deprecation process. It however does not mean that they will keep being read, so there is no guarantee that writing to them will have the desired effect in the future, unless such a guarantee is explicitly given in the documentation of the field.
Included:
Public fields
Protected fields of classes that are
stable to extend
Not included:
write access
any field marked as
@deprecated
@internal
or
@unstable
For authors:
Public fields should generally be avoided in favor of getters and setters.
Base classes should generally not expect subclasses to modify protected fields directly. If this is desired, it must be explicitly documented.
When hard deprecating a field that is stable to access, PHP's magic __get() and __set() methods SHOULD be used to trigger a deprecation warning.
Stable to implement
edit
It's generally
not stable to implement interfaces
– unless these are marked
@stable to implement
. This means existing signatures may change and new required methods may be added without notice.
Stable to implement
can apply to interfaces. It means they will stay backward-compatible between releases and may be implemented anywhere. Changes that affect implementations will follow the
deprecation process
Included:
Only interfaces that are marked
@stable to implement
For authors:
Do not add methods to interfaces marked as
@stable to implement
Do not break method signatures in interfaces that are
@stable to implement
Any
hook interface
that is documented (and not deprecated) should be marked
@stable to implement
Avoid using interfaces as extension points other than hook interfaces. It is recommended to use an abstract base class instead. See
Stable to extend
Stable to override
edit
It's generally
not stable to override methods in subclasses
unless the method is marked
@stable to override
Stable to override
can apply to class methods and
hooks
. It means the method signature will remain compatible for overriding, and the method or callback will continue to be called in relevant circumstances. Changes to that contract must follow the
deprecation process
Included:
Any
hook
that is documented. For the sake of this policy, hook callbacks are treated as implementations of abstract methods. Hook interfaces follow the normal rules for interfaces. Note that since MediaWiki release 1.35, it is preferred for extensions to
implement hook interfaces
, rather than registering hook callbacks.
Methods that are declared as
abstract
in classes that are
stable to extend
Any method marked
@stable to override
Not included:
Any method marked
@deprecated
@internal
or
@unstable
For authors:
When hard deprecating code that is stable to override,
a deprecation warning SHOULD be triggered in case the method is overridden by a subclass, typically using
MWDebug::detectDeprecatedOverride
the method MUST still be called if it is overridden.
Global variables
edit
It's
not stable to use global variables
Global variables are not stable, not even those with the "wg" prefix.
For users:
To access site configuration, use
MediaWikiServices
::
getMainConfig
()
instead.
To access service objects, use
MediaWikiServices
::
get
methods instead.
For authors:
When access to global state cannot be avoided, static methods SHOULD be used.
Stability annotations
edit
Add guarantees
edit
@stable to call
: See
Stable to call
@stable to type
: See
Stable to type
@stable to extend
: See
Stable to extend
@stable to implement
: See
Stable to implement
@stable to override
: See
Stable to override
@newable
: See
Stable to call
The
@stable
annotations can be followed by a
Since
segment to indicate that a particular use of the class or method is only supported since a specific version. For example:
/**
* @since 1.17
* @stable to extend Since 1.35
*/
class
Foo
/* … */
The
@stable
annotations can be followed by a
Deprecated since
segment to indicate that a particular use of the class or method is currently deprecated outside of the original module. This can be used to indicate that extensions should no longer subclass, but may still call public methods. This guarantee may then be removed in the next release. Note that there is currently no mechanism for the hard-deprecation or removal of stability guarantees.
/**
* @stable to extend Deprecated since 1.35
*/
class
Foo
/* … */
Remove guarantees
edit
@internal
: Do not use outside the original module. It may change without notice.
@unstable
: It may change without notice. Similar to
@internal
, except that unstable things are aimed at external use and intended to become stable in the future.
@deprecated
: This means something should not be used anywhere, as this may be removed in a future release, per the
deprecation process
. This must include a
since
segment, and must include instructions for what to use instead (or state that there is no alternative). For example:
/**
* @deprecated since 1.35 Use expandFoo() instead.
*/
public
function
getSomething
Foo
$foo
);
Deprecation process
edit
Deprecation becomes necessary when the public interface of code needs to be changed in order to add new functionality or improve architecture. All code that falls within the
scope
of this policy and defines a
stable interface
is subject to the deprecation process defined here.
The deprecation process generally consists of the following steps, described in more detail below:
soft deprecation
, immediately followed by updating any code using the deprecated functionality.
hard deprecation
, as soon as the deprecated code appears to be unused, ideally within the same release as soft deprecation.
removal
of the deprecated code, after at least one release branch has been cut and at least three months have passed.
The purpose of the deprecation process is to remove usages of deprecated functionality, so that it can be dropped without breaking callers. Usage of deprecated code is considered more or less problematic depending on where it occurs: the most critical usages are within the same repository, followed by Wikimedia maintained code, further followed by code in the MediaWiki ecosystem. Usages outside the ecosystem are considered the least relevant.
This means that Wikimedia maintained code MUST receive special attention in the deprecation process, and extensions in the MediaWiki ecosystem SHOULD be given consideration and support during the deprecation process.
WikiApiary.com
and
ExtensionDistributor
can be used as indicators for an extension's relevance.
Individuals, teams and organizations that deprecate code MUST commit to follow through with the deprecation process until the obsolete code has been removed, and they SHOULD be proactive about supporting maintainers of affected code in the MediaWiki ecosystem.
Soft deprecation
edit
Soft deprecation occurs when a developer adds a
@deprecated
annotation to the documentation comment of a method, function, class, or interface.
The following rules apply to soft deprecation:
The documentation comment MUST mention what the alternative method or migration path is. If there is no alternative, it should state that.
The documentation comment MUST state what MediaWiki core version the deprecation occurred in.
As long as is only soft deprecated, it SHOULD function the same as prior to deprecation. If not possible, a best effort SHOULD be made to provide similar functionality that covers typical use cases.
Any relevant documentation in the Git repository and on mediawiki.org MUST be updated once the change is approved.
The deprecation MUST be mentioned in the relevant RELEASE-NOTES file, and MAY also be mentioned in the "Upgrade notices for MediaWiki administrators" section of the wiki release page depending upon severity. Deprecation of hooks MUST be documented on the
Manual:Hooks
page.
Developers or teams deprecating code SHOULD remove usages in Wikimedia maintained code as soon as possible.
Developers or teams deprecating code SHOULD actively support removal of usages in code in the MediaWiki ecosystem, especially in popular extensions. This includes making maintainers aware of the deprecation as well as creating or reviewing patches removing usages.
Soft deprecated code SHOULD be unused in Wikimedia maintained code and hard deprecated as soon as possible, ideally before the next release branch is cut.
If the deprecated code is unused in Wikimedia maintained code at the time of deprecation, it SHOULD be hard deprecated immediately.
Hard deprecation
edit
Hard deprecation occurs when the code starts emitting deprecation warnings, typically by calling
wfDeprecated( __METHOD__, '1.xx' );
. Deprecation warnings cause unit tests to fail.
If it is not reasonably possible for the deprecated code to emit deprecation warnings, hard deprecation can be applied by announcing the removal on wikitech-l in a timely manner. The announcement must explain why deprecation warnings cannot be emitted, and provide an opportunity for affected parties to raise concerns and propose alternatives. In addition, the affected code MUST be annotated with a
@warning
tag that announces the release in which removal is intended. This procedure is suitable e.g. for the deprecation of global variables, interfaces, and traits. It SHOULD also be used when removing parts of the stable interface by marking them as
@internal
The following rules apply to hard deprecation:
Code that is hard deprecated MUST also be soft deprecated.
The version number in the
wfDeprecated()
call MUST match the one in the
@deprecated
annotation, even if the hard deprecation occurs in a different release.
Any soft deprecated code SHOULD be hard deprecated as soon as it is no longer used in any Wikimedia maintained code.
Hard deprecated code MAY act as no-ops instead of actually functioning, though this is not recommended.
Hard deprecation MUST NOT be applied to code still used in Wikimedia maintained code. Such usage MUST be removed first.
Deprecation with far-reaching impact SHOULD be announced by email to wikitech-l or mediawiki-l.
Removal
edit
The following rules apply to the removal of code:
Obsolete behavior MAY be removed after it has been hard deprecated for three months in the development version (the master branch) as well as in one major release, using either deprecation warnings or public announcement as described in the
hard deprecation
section.
Obsolete behavior MAY be removed right away if it appears to have never been used within the Wikimedia maintained code and the MediaWiki ecosystem (except in the repo that defines it), and seems unlikely to be used elsewhere.
When determining the timeline for removal, developers SHOULD weigh the cost of maintaining the deprecated code against the difficulty of updating extensions that rely on it.
All removals of code that falls under the stable interface policy MUST be mentioned in the relevant RELEASE-NOTES file.
Removals that may have a severe impact SHOULD be mentioned in the "Upgrade notices for MediaWiki administrators" section of the wiki release page.
As one of the
principles
of MediaWiki, developers MUST ensure any removals will not cause issues on Wikimedia sites. Any removals that cause issues on the live site will be reverted by Wikimedia system administrators.
Further guidance
edit
Usages in code that is itself deprecated, or can only be activated by deprecated configuration settings, SHOULD be ignored for the purpose of this process.
Code that was never part of a public release MAY be changed or removed without deprecation, since it has never become part of the stable interface.
Developers SHOULD consider the impact of their proposed changes by searching for existing usage in extensions using tools such
Codesearch
Deprecations and removals SHOULD NOT be performed shortly before a release branch or between release candidates, to give extension authors time to fix any issues that may arise, and avoid broken snapshots of extensions.
Deprecations and removals MUST first take place on the master branch. Deprecations and removals SHOULD NOT be backported to release branches or release candidates.
Developers SHOULD deprecate related parts of code together so affected code can be updated all at once.
When a task is related to a deprecation, it is RECOMMENDED to tag it specifically in the bug tracker; for instance with the
"Deprecation process" tag
in Phabricator.
And finally: As with all policies, developers should apply their best judgement when applying it.
Meta
edit
Motivation
edit
The motivation for this policy is two-fold:
Offer guarantees to extension developers, providing guidance on what aspects of MediaWiki core they can safely rely upon.
Provide guarantees to developers working on MediaWiki core, telling them what aspects of the code they can safely change without having to worry about breaking extensions.
This policy is designed to make extensions more robust against changes in MediaWiki core, and provide more freedom for MediaWiki core code to evolve.
Scope
edit
This policy is mainly written to define a contract between MediaWiki core and MediaWiki extensions, but it also applies to the relationship between MediaWiki and libraries it uses, as well as dependencies between extensions. It applies to the following:
PHP code of MediaWiki core (mediawiki/core.git) as published in official releases.
Libraries maintained by Wikimedia, inside the core repository or in separate repositories, as published in official releases.
Extensions maintained by Wikimedia only if they offer extension points such as hooks, or explicitly opt into this policy. Per default, extensions are themselves not considered extensible, and do not offer a stable interface.
Code in a repository in the MediaWiki ecosystem if and only if it explicitly opts into this policy.
This policy does
not
apply to the following:
Any unreleased code, in particular code as it is on the master or a development branch of the repository.
Web APIs such as
api.php
or
rest.php
client-side JavaScript
The structure of HTML output from index.php and other endpoints
The structure of
dumps
or exports
The
database schema
Those may have their own policies and practices for maintaining stable interfaces.
Ecosystem
edit
Providing a stable interface enables a community of third parties to create and maintain components, forming a "
software ecosystem
". For the purpose of this policy, the
MediaWiki ecosystem
is thought to consist of extensions actively maintained by entities other than the Wikimedia Foundation, if they meet all of the following criteria:
the extension is
free software
the extension has a page on mediawiki.org, using the
Extension template
to make it discoverable.
the extension is maintained either in a repository hosted by the Wikimedia Foundation, or is
listed as a non-wikimedia extension
by the
MediaWiki Stakeholders' Group
Extension developers are encouraged to make their code available in the way described above, so it can be used by others. Per this policy, such extensions will in return receive consideration and support when breaking changes need to be made. For this purpose, such extensions are automatically index by the
codesearch
tool.
History
edit
This policy was established in January 2017 with RFC
T146965
(effective since
MediaWiki 1.29
), and superseded the guideline archived at
Deprecation policy/Until 2017
This policy was amended in March 2020 with RFC
T193613
, and in June 2020 with RFC
T255803
(effective since
MediaWiki 1.35
). The policy for MediaWiki 1.34 and earlier can be found at
Stable interfaces up to MediaWiki 1.34
This policy was amended in January 2021 with RFC
T268326
(effective since
MediaWiki 1.36
).
Frontend policy
edit
There is also a separate
Stable interface policy/Frontend
policy that defines what parts of the software are considered stable and safe for use by browser-based code from other components.
Development guidelines
Policies
Development policy
Architecture principles
Services policy
Support policy for PHP
Gerrit/Privilege policy
Stable interface policy
Frontend
MediaWiki database policy
General guidelines
Security for developers
Performance guidelines
Commit message guidelines
Security checklist for developers
Localisation
Codex, design system and guidelines
Documentation/Style guide
Accessibility guide for developers
Inclusive language
Guidelines for a healthy code review culture
Collaborative programming
Best practices for extensions
Pre-commit checklist
Code conventions
All languages
PHP
PHPUnit
JavaScript
CSS
Selenium
Lua
Python
Java
SVG
Vue
Database schemas
Analytics (Python, R, SQL)
API client code
Standards for API client libraries
Drafts
Code documentation
Using AI in MediaWiki patches
Retrieved from "
Categories
Wikimedia development policies
Development guidelines
Hidden category:
Languages pages
Stable interface policy
Add topic