CINXE.COM

<!DOCTYPE html> <html class="client-nojs vector-feature-language-in-header-disabled vector-feature-language-in-main-page-header-disabled vector-feature-sticky-header-disabled vector-feature-page-tools-pinned-disabled vector-feature-toc-pinned-clientpref-1 vector-feature-main-menu-pinned-disabled vector-feature-limited-width-clientpref-1 vector-feature-limited-width-content-enabled vector-feature-custom-font-size-clientpref-1 vector-feature-appearance-pinned-clientpref-1 vector-feature-night-mode-disabled skin-theme-clientpref-day vector-toc-available" lang="en" dir="ltr"> <head> <meta charset="UTF-8"> <title>Stable interface policy - MediaWiki</title> <script>(function(){var className="client-js vector-feature-language-in-header-disabled vector-feature-language-in-main-page-header-disabled vector-feature-sticky-header-disabled vector-feature-page-tools-pinned-disabled vector-feature-toc-pinned-clientpref-1 vector-feature-main-menu-pinned-disabled vector-feature-limited-width-clientpref-1 vector-feature-limited-width-content-enabled vector-feature-custom-font-size-clientpref-1 vector-feature-appearance-pinned-clientpref-1 vector-feature-night-mode-disabled skin-theme-clientpref-day vector-toc-available";var cookie=document.cookie.match(/(?:^|; )mediawikiwikimwclientpreferences=([^;]+)/);if(cookie){cookie[1].split('%2C').forEach(function(pref){className=className.replace(new RegExp('(^| )'+pref.replace(/-clientpref-\w+$|[^\w-]+/g,'')+'-clientpref-\\w+( |$)'),'$1'+pref+'$2');});}document.documentElement.className=className;}());RLCONF={"wgBreakFrames":false,"wgSeparatorTransformTable":["",""],"wgDigitTransformTable":["",""], "wgDefaultDateFormat":"dmy","wgMonthNames":["","January","February","March","April","May","June","July","August","September","October","November","December"],"wgRequestId":"e5010dcb-756e-4473-bef1-72b78a35e4bf","wgCanonicalNamespace":"","wgCanonicalSpecialPageName":false,"wgNamespaceNumber":0,"wgPageName":"Stable_interface_policy","wgTitle":"Stable interface policy","wgCurRevisionId":6774239,"wgRevisionId":6774239,"wgArticleId":983280,"wgIsArticle":true,"wgIsRedirect":false,"wgAction":"view","wgUserName":null,"wgUserGroups":["*"],"wgCategories":["Languages pages","Wikimedia development policies","Development guidelines"],"wgPageViewLanguage":"en","wgPageContentLanguage":"en","wgPageContentModel":"wikitext","wgRelevantPageName":"Stable_interface_policy","wgRelevantArticleId":983280,"wgIsProbablyEditable":true,"wgRelevantPageIsProbablyEditable":true,"wgRestrictionEdit":[],"wgRestrictionMove":[],"wgNoticeProject":"mediawiki","wgCiteReferencePreviewsActive":true,"wgMediaViewerOnClick":true ,"wgMediaViewerEnabledByDefault":true,"wgVisualEditor":{"pageLanguageCode":"en","pageLanguageDir":"ltr","pageVariantFallbacks":"en"},"wgMFDisplayWikibaseDescriptions":{"search":true,"watchlist":true,"tagline":false,"nearby":true},"wgWMESchemaEditAttemptStepOversample":false,"wgWMEPageLength":30000,"wgCentralAuthMobileDomain":false,"wgEditSubmitButtonLabelPublish":true,"wgDiscussionToolsFeaturesEnabled":{"replytool":true,"newtopictool":true,"sourcemodetoolbar":true,"topicsubscription":false,"autotopicsub":false,"visualenhancements":false,"visualenhancements_reply":false,"visualenhancements_pageframe":false},"wgDiscussionToolsFallbackEditMode":"visual","wgULSPosition":"personal","wgULSisCompactLinksEnabled":true,"wgVector2022LanguageInHeader":false,"wgULSisLanguageSelectorEmpty":false,"wgCheckUserClientHintsHeadersJsApi":["brands","architecture","bitness","fullVersionList","mobile","model","platform","platformVersion"]};RLSTATE={"ext.globalCssJs.user.styles":"ready","site.styles":"ready" ,"user.styles":"ready","ext.globalCssJs.user":"ready","user":"ready","user.options":"loading","ext.pygments":"ready","ext.discussionTools.init.styles":"ready","oojs-ui-core.styles":"ready","oojs-ui.styles.indicators":"ready","mediawiki.widgets.styles":"ready","oojs-ui-core.icons":"ready","skins.vector.search.codex.styles":"ready","skins.vector.styles":"ready","skins.vector.icons":"ready","ext.wikimediamessages.styles":"ready","ext.visualEditor.desktopArticleTarget.noscript":"ready","ext.uls.pt":"ready","wikibase.client.init":"ready","ext.wikimediaBadges":"ready"};RLPAGEMODULES=["ext.pygments.view","site","mediawiki.page.ready","mediawiki.toc","skins.vector.js","ext.centralNotice.geoIP","ext.centralNotice.startUp","ext.urlShortener.toolbar","ext.centralauth.centralautologin","mmv.bootstrap","ext.visualEditor.desktopArticleTarget.init","ext.visualEditor.targetLoader","ext.echo.centralauth","ext.discussionTools.init","ext.eventLogging","ext.wikimediaEvents","ext.navigationTiming", "ext.uls.compactlinks","ext.uls.interface","ext.checkUser.clientHints"];</script> <script>(RLQ=window.RLQ||[]).push(function(){mw.loader.impl(function(){return["user.options@12s5i",function($,jQuery,require,module){mw.user.tokens.set({"patrolToken":"+\\","watchToken":"+\\","csrfToken":"+\\"}); }];});});</script> <link rel="stylesheet" href="/w/load.php?lang=en&modules=ext.discussionTools.init.styles%7Cext.pygments%2CwikimediaBadges%7Cext.uls.pt%7Cext.visualEditor.desktopArticleTarget.noscript%7Cext.wikimediamessages.styles%7Cmediawiki.widgets.styles%7Coojs-ui-core.icons%2Cstyles%7Coojs-ui.styles.indicators%7Cskins.vector.icons%2Cstyles%7Cskins.vector.search.codex.styles%7Cwikibase.client.init&only=styles&skin=vector-2022"> <script async="" src="/w/load.php?lang=en&modules=startup&only=scripts&raw=1&skin=vector-2022"></script> <meta name="ResourceLoaderDynamicStyles" content=""> <link rel="stylesheet" href="/w/load.php?lang=en&modules=site.styles&only=styles&skin=vector-2022"> <meta name="generator" content="MediaWiki 1.44.0-wmf.4"> <meta name="referrer" content="origin"> <meta name="referrer" content="origin-when-cross-origin"> <meta name="robots" content="max-image-preview:standard"> <meta name="format-detection" content="telephone=no"> <meta name="viewport" content="width=1120"> <meta property="og:site_name" content="MediaWiki"> <meta property="og:title" content="Stable interface policy - MediaWiki"> <meta property="og:type" content="website"> <link rel="preconnect" href="//upload.wikimedia.org"> <link rel="alternate" media="only screen and (max-width: 640px)" href="//m.mediawiki.org/wiki/Stable_interface_policy"> <link rel="alternate" type="application/x-wiki" title="Edit" href="/w/index.php?title=Stable_interface_policy&action=edit"> <link rel="apple-touch-icon" href="/static/apple-touch/mediawiki.png"> <link rel="icon" href="/static/favicon/mediawiki.ico"> <link rel="search" type="application/opensearchdescription+xml" href="/w/rest.php/v1/search" title="MediaWiki (en)"> <link rel="EditURI" type="application/rsd+xml" href="//www.mediawiki.org/w/api.php?action=rsd"> <link rel="canonical" href="https://www.mediawiki.org/wiki/Stable_interface_policy"> <link rel="license" href="https://creativecommons.org/licenses/by-sa/4.0/"> <link rel="alternate" type="application/atom+xml" title="MediaWiki Atom feed" href="/w/index.php?title=Special:RecentChanges&feed=atom"> <link rel="dns-prefetch" href="//meta.wikimedia.org" /> <link rel="dns-prefetch" href="//login.wikimedia.org"> </head> <body class="ext-discussiontools-replytool-enabled ext-discussiontools-newtopictool-enabled ext-discussiontools-sourcemodetoolbar-enabled skin--responsive skin-vector skin-vector-search-vue mediawiki ltr sitedir-ltr mw-hide-empty-elt ns-0 ns-subject mw-editable page-Stable_interface_policy rootpage-Stable_interface_policy skin-vector-2022 action-view"><a class="mw-jump-link" href="#bodyContent">Jump to content</a> <div class="vector-header-container"> <header class="vector-header mw-header"> <div class="vector-header-start"> <nav class="vector-main-menu-landmark" aria-label="Site"> <div id="vector-main-menu-dropdown" class="vector-dropdown vector-main-menu-dropdown vector-button-flush-left vector-button-flush-right" > <input type="checkbox" id="vector-main-menu-dropdown-checkbox" role="button" aria-haspopup="true" data-event-name="ui.dropdown-vector-main-menu-dropdown" class="vector-dropdown-checkbox " aria-label="Main menu" > <label id="vector-main-menu-dropdown-label" for="vector-main-menu-dropdown-checkbox" class="vector-dropdown-label cdx-button cdx-button--fake-button cdx-button--fake-button--enabled cdx-button--weight-quiet cdx-button--icon-only " aria-hidden="true" ><span class="vector-icon mw-ui-icon-menu mw-ui-icon-wikimedia-menu"></span> <span class="vector-dropdown-label-text">Main menu</span> </label> <div class="vector-dropdown-content"> <div id="vector-main-menu-unpinned-container" class="vector-unpinned-container"> <div id="vector-main-menu" class="vector-main-menu vector-pinnable-element"> <div class="vector-pinnable-header vector-main-menu-pinnable-header vector-pinnable-header-unpinned" data-feature-name="main-menu-pinned" data-pinnable-element-id="vector-main-menu" data-pinned-container-id="vector-main-menu-pinned-container" data-unpinned-container-id="vector-main-menu-unpinned-container" > <div class="vector-pinnable-header-label">Main menu</div> <button class="vector-pinnable-header-toggle-button vector-pinnable-header-pin-button" data-event-name="pinnable-header.vector-main-menu.pin">move to sidebar</button> <button class="vector-pinnable-header-toggle-button vector-pinnable-header-unpin-button" data-event-name="pinnable-header.vector-main-menu.unpin">hide</button> </div> <div id="p-navigation" class="vector-menu mw-portlet mw-portlet-navigation" > <div class="vector-menu-heading"> Navigation </div> <div class="vector-menu-content"> <ul class="vector-menu-content-list"> <li id="n-mainpage-description" class="mw-list-item"><a href="/wiki/MediaWiki" title="Visit the main page [z]" accesskey="z"><span>Main page</span></a></li><li id="n-mw-download" class="mw-list-item"><a href="/wiki/Download"><span>Get MediaWiki</span></a></li><li id="n-mw-extensions" class="mw-list-item"><a href="/wiki/Special:MyLanguage/Category:Extensions"><span>Get extensions</span></a></li><li id="n-blog-text" class="mw-list-item"><a href="https://techblog.wikimedia.org/"><span>Tech blog</span></a></li><li id="n-mw-contribute" class="mw-list-item"><a href="/wiki/Special:MyLanguage/How_to_contribute"><span>Contribute</span></a></li> </ul> </div> </div> <div id="p-support" class="vector-menu mw-portlet mw-portlet-support" > <div class="vector-menu-heading"> Support </div> <div class="vector-menu-content"> <ul class="vector-menu-content-list"> <li id="n-help" class="mw-list-item"><a href="/wiki/Special:MyLanguage/Help:Contents" title="The place to find out"><span>User help</span></a></li><li id="n-mw-faq" class="mw-list-item"><a href="/wiki/Special:MyLanguage/Manual:FAQ"><span>FAQ</span></a></li><li id="n-mw-manual" class="mw-list-item"><a href="/wiki/Special:MyLanguage/Manual:Contents"><span>Technical manual</span></a></li><li id="n-mw-supportdesk" class="mw-list-item"><a href="/wiki/Project:Support_desk"><span>Support desk</span></a></li><li id="n-mw-communication" class="mw-list-item"><a href="/wiki/Special:MyLanguage/Communication"><span>Communication</span></a></li> </ul> </div> </div> <div id="p-development" class="vector-menu mw-portlet mw-portlet-development" > <div class="vector-menu-heading"> Development </div> <div class="vector-menu-content"> <ul class="vector-menu-content-list"> <li id="n-mw-developerportal" class="mw-list-item"><a href="https://developer.wikimedia.org/"><span>Developer portal</span></a></li><li id="n-svn-statistics" class="mw-list-item"><a href="/wiki/Development_statistics"><span>Code statistics</span></a></li> </ul> </div> </div> <div id="p-mediawiki.org" class="vector-menu mw-portlet mw-portlet-mediawiki_org" > <div class="vector-menu-heading"> mediawiki.org </div> <div class="vector-menu-content"> <ul class="vector-menu-content-list"> <li id="n-portal" class="mw-list-item"><a href="/wiki/Project:Help" title="About the project, what you can do, where to find things"><span>Community portal</span></a></li><li id="n-recentchanges" class="mw-list-item"><a href="/wiki/Special:RecentChanges" title="A list of recent changes in the wiki [r]" accesskey="r"><span>Recent changes</span></a></li><li id="n-mw-translate" class="mw-list-item"><a href="/wiki/Special:LanguageStats"><span>Translate content</span></a></li><li id="n-randompage" class="mw-list-item"><a href="/wiki/Special:Random" title="Load a random page [x]" accesskey="x"><span>Random page</span></a></li><li id="n-mw-discussion" class="mw-list-item"><a href="/wiki/Project:Village_Pump"><span>Village pump</span></a></li><li id="n-Sandboxlink-portlet-label" class="mw-list-item"><a href="/wiki/Project:Sandbox"><span>Sandbox</span></a></li> </ul> </div> </div> <div id="p-lang" class="vector-menu mw-portlet mw-portlet-lang" > <div class="vector-menu-heading"> In other languages </div> <div class="vector-menu-content"> <ul class="vector-menu-content-list"> </ul> <div class="after-portlet after-portlet-lang"><span class="wb-langlinks-add wb-langlinks-link"><a href="https://www.wikidata.org/wiki/Special:NewItem?site=mediawikiwiki&page=Stable+interface+policy" title="Add interlanguage links" class="wbc-editpage">Add links</a></span></div> </div> </div> </div> </div> </div> </div> </nav> <a href="/wiki/MediaWiki" class="mw-logo"> <img class="mw-logo-icon" src="/static/images/icons/mediawikiwiki.svg" alt="" aria-hidden="true" height="50" width="50"> <span class="mw-logo-container skin-invert"> <img class="mw-logo-wordmark" alt="MediaWiki" src="/static/images/mobile/copyright/mediawikiwiki-wordmark.svg" style="width: 7.5em; height: 1.125em;"> </span> </a> </div> <div class="vector-header-end"> <div id="p-search" role="search" class="vector-search-box-vue vector-search-box-collapses vector-search-box-show-thumbnail vector-search-box-auto-expand-width vector-search-box"> <a href="/wiki/Special:Search" class="cdx-button cdx-button--fake-button cdx-button--fake-button--enabled cdx-button--weight-quiet cdx-button--icon-only search-toggle" title="Search MediaWiki [f]" accesskey="f"><span class="vector-icon mw-ui-icon-search mw-ui-icon-wikimedia-search"></span> <span>Search</span> </a> <div class="vector-typeahead-search-container"> <div class="cdx-typeahead-search cdx-typeahead-search--show-thumbnail cdx-typeahead-search--auto-expand-width"> <form action="/w/index.php" id="searchform" class="cdx-search-input cdx-search-input--has-end-button"> <div id="simpleSearch" class="cdx-search-input__input-wrapper" data-search-loc="header-moved"> <div class="cdx-text-input cdx-text-input--has-start-icon"> <input class="cdx-text-input__input" type="search" name="search" placeholder="Search MediaWiki" aria-label="Search MediaWiki" autocapitalize="sentences" title="Search MediaWiki [f]" accesskey="f" id="searchInput" > <span class="cdx-text-input__icon cdx-text-input__start-icon"></span> </div> <input type="hidden" name="title" value="Special:Search"> </div> <button class="cdx-button cdx-search-input__end-button">Search</button> </form> </div> </div> </div> <nav class="vector-user-links vector-user-links-wide" aria-label="Personal tools"> <div class="vector-user-links-main"> <div id="p-vector-user-menu-preferences" class="vector-menu mw-portlet" > <div class="vector-menu-content"> <ul class="vector-menu-content-list"> <li id="ca-uls" class="mw-list-item active user-links-collapsible-item"><a data-mw="interface" href="#" class="uls-trigger cdx-button cdx-button--fake-button cdx-button--fake-button--enabled cdx-button--weight-quiet"><span class="vector-icon mw-ui-icon-wikimedia-language mw-ui-icon-wikimedia-wikimedia-language"></span> <span>English</span></a> </li> </ul> </div> </div> <div id="p-vector-user-menu-userpage" class="vector-menu mw-portlet emptyPortlet" > <div class="vector-menu-content"> <ul class="vector-menu-content-list"> </ul> </div> </div> <nav class="vector-appearance-landmark" aria-label="Appearance"> <div id="vector-appearance-dropdown" class="vector-dropdown " title="Change the appearance of the page's font size, width, and color" > <input type="checkbox" id="vector-appearance-dropdown-checkbox" role="button" aria-haspopup="true" data-event-name="ui.dropdown-vector-appearance-dropdown" class="vector-dropdown-checkbox " aria-label="Appearance" > <label id="vector-appearance-dropdown-label" for="vector-appearance-dropdown-checkbox" class="vector-dropdown-label cdx-button cdx-button--fake-button cdx-button--fake-button--enabled cdx-button--weight-quiet cdx-button--icon-only " aria-hidden="true" ><span class="vector-icon mw-ui-icon-appearance mw-ui-icon-wikimedia-appearance"></span> <span class="vector-dropdown-label-text">Appearance</span> </label> <div class="vector-dropdown-content"> <div id="vector-appearance-unpinned-container" class="vector-unpinned-container"> </div> </div> </div> </nav> <div id="p-vector-user-menu-notifications" class="vector-menu mw-portlet emptyPortlet" > <div class="vector-menu-content"> <ul class="vector-menu-content-list"> </ul> </div> </div> <div id="p-vector-user-menu-overflow" class="vector-menu mw-portlet" > <div class="vector-menu-content"> <ul class="vector-menu-content-list"> <li id="pt-sitesupport-2" class="user-links-collapsible-item mw-list-item user-links-collapsible-item"><a data-mw="interface" href="https://donate.wikimedia.org/?utm_source=donate&utm_medium=sidebar&utm_campaign=spontaneous&uselang=en" class=""><span>Donate</span></a> </li> <li id="pt-createaccount-2" class="user-links-collapsible-item mw-list-item user-links-collapsible-item"><a data-mw="interface" href="/w/index.php?title=Special:CreateAccount&returnto=Stable+interface+policy" title="You are encouraged to create an account and log in; however, it is not mandatory" class=""><span>Create account</span></a> </li> <li id="pt-login-2" class="user-links-collapsible-item mw-list-item user-links-collapsible-item"><a data-mw="interface" href="/w/index.php?title=Special:UserLogin&returnto=Stable+interface+policy" title="You are encouraged to log in; however, it is not mandatory [o]" accesskey="o" class=""><span>Log in</span></a> </li> </ul> </div> </div> </div> <div id="vector-user-links-dropdown" class="vector-dropdown vector-user-menu vector-button-flush-right vector-user-menu-logged-out" title="More options" > <input type="checkbox" id="vector-user-links-dropdown-checkbox" role="button" aria-haspopup="true" data-event-name="ui.dropdown-vector-user-links-dropdown" class="vector-dropdown-checkbox " aria-label="Personal tools" > <label id="vector-user-links-dropdown-label" for="vector-user-links-dropdown-checkbox" class="vector-dropdown-label cdx-button cdx-button--fake-button cdx-button--fake-button--enabled cdx-button--weight-quiet cdx-button--icon-only " aria-hidden="true" ><span class="vector-icon mw-ui-icon-ellipsis mw-ui-icon-wikimedia-ellipsis"></span> <span class="vector-dropdown-label-text">Personal tools</span> </label> <div class="vector-dropdown-content"> <div id="p-personal" class="vector-menu mw-portlet mw-portlet-personal user-links-collapsible-item" title="User menu" > <div class="vector-menu-content"> <ul class="vector-menu-content-list"> <li id="pt-sitesupport" class="user-links-collapsible-item mw-list-item"><a href="https://donate.wikimedia.org/?utm_source=donate&utm_medium=sidebar&utm_campaign=spontaneous&uselang=en"><span>Donate</span></a></li><li id="pt-createaccount" class="user-links-collapsible-item mw-list-item"><a href="/w/index.php?title=Special:CreateAccount&returnto=Stable+interface+policy" title="You are encouraged to create an account and log in; however, it is not mandatory"><span class="vector-icon mw-ui-icon-userAdd mw-ui-icon-wikimedia-userAdd"></span> <span>Create account</span></a></li><li id="pt-login" class="user-links-collapsible-item mw-list-item"><a href="/w/index.php?title=Special:UserLogin&returnto=Stable+interface+policy" title="You are encouraged to log in; however, it is not mandatory [o]" accesskey="o"><span class="vector-icon mw-ui-icon-logIn mw-ui-icon-wikimedia-logIn"></span> <span>Log in</span></a></li> </ul> </div> </div> <div id="p-user-menu-anon-editor" class="vector-menu mw-portlet mw-portlet-user-menu-anon-editor" > <div class="vector-menu-heading"> Pages for logged out editors <a href="/wiki/Help:Introduction" aria-label="Learn more about editing"><span>learn more</span></a> </div> <div class="vector-menu-content"> <ul class="vector-menu-content-list"> <li id="pt-anoncontribs" class="mw-list-item"><a href="/wiki/Special:MyContributions" title="A list of edits made from this IP address [y]" accesskey="y"><span>Contributions</span></a></li><li id="pt-anontalk" class="mw-list-item"><a href="/wiki/Special:MyTalk" title="Discussion about edits from this IP address [n]" accesskey="n"><span>Talk</span></a></li> </ul> </div> </div> </div> </div> </nav> </div> </header> </div> <div class="mw-page-container"> <div class="mw-page-container-inner"> <div class="vector-sitenotice-container"> <div id="siteNotice"></div> </div> <div class="vector-column-start"> <div class="vector-main-menu-container"> <div id="mw-navigation"> <nav id="mw-panel" class="vector-main-menu-landmark" aria-label="Site"> <div id="vector-main-menu-pinned-container" class="vector-pinned-container"> </div> </nav> </div> </div> <div class="vector-sticky-pinned-container"> <nav id="mw-panel-toc" aria-label="Contents" data-event-name="ui.sidebar-toc" class="mw-table-of-contents-container vector-toc-landmark"> <div id="vector-toc-pinned-container" class="vector-pinned-container"> <div id="vector-toc" class="vector-toc vector-pinnable-element"> <div class="vector-pinnable-header vector-toc-pinnable-header vector-pinnable-header-pinned" data-feature-name="toc-pinned" data-pinnable-element-id="vector-toc" > <h2 class="vector-pinnable-header-label">Contents</h2> <button class="vector-pinnable-header-toggle-button vector-pinnable-header-pin-button" data-event-name="pinnable-header.vector-toc.pin">move to sidebar</button> <button class="vector-pinnable-header-toggle-button vector-pinnable-header-unpin-button" data-event-name="pinnable-header.vector-toc.unpin">hide</button> </div> <ul class="vector-toc-contents" id="mw-panel-toc-list"> <li id="toc-mw-content-text" class="vector-toc-list-item vector-toc-level-1"> <a href="#" class="vector-toc-link"> <div class="vector-toc-text">Beginning</div> </a> </li> <li id="toc-Quick_guide" class="vector-toc-list-item vector-toc-level-1 vector-toc-list-item-expanded"> <a class="vector-toc-link" href="#Quick_guide"> <div class="vector-toc-text"> <span class="vector-toc-numb">1</span> <span>Quick guide</span> </div> </a> <button aria-controls="toc-Quick_guide-sublist" class="cdx-button cdx-button--weight-quiet cdx-button--icon-only vector-toc-toggle"> <span class="vector-icon mw-ui-icon-wikimedia-expand"></span> <span>Toggle Quick guide subsection</span> </button> <ul id="toc-Quick_guide-sublist" class="vector-toc-list"> <li id="toc-Using_code" class="vector-toc-list-item vector-toc-level-2"> <a class="vector-toc-link" href="#Using_code"> <div class="vector-toc-text"> <span class="vector-toc-numb">1.1</span> <span>Using code</span> </div> </a> <ul id="toc-Using_code-sublist" class="vector-toc-list"> </ul> </li> <li id="toc-Writing_code" class="vector-toc-list-item vector-toc-level-2"> <a class="vector-toc-link" href="#Writing_code"> <div class="vector-toc-text"> <span class="vector-toc-numb">1.2</span> <span>Writing code</span> </div> </a> <ul id="toc-Writing_code-sublist" class="vector-toc-list"> </ul> </li> </ul> </li> <li id="toc-Terminology" class="vector-toc-list-item vector-toc-level-1 vector-toc-list-item-expanded"> <a class="vector-toc-link" href="#Terminology"> <div class="vector-toc-text"> <span class="vector-toc-numb">2</span> <span>Terminology</span> </div> </a> <ul id="toc-Terminology-sublist" class="vector-toc-list"> </ul> </li> <li id="toc-Definition_of_the_stable_interface" class="vector-toc-list-item vector-toc-level-1 vector-toc-list-item-expanded"> <a class="vector-toc-link" href="#Definition_of_the_stable_interface"> <div class="vector-toc-text"> <span class="vector-toc-numb">3</span> <span>Definition of the stable interface</span> </div> </a> <button aria-controls="toc-Definition_of_the_stable_interface-sublist" class="cdx-button cdx-button--weight-quiet cdx-button--icon-only vector-toc-toggle"> <span class="vector-icon mw-ui-icon-wikimedia-expand"></span> <span>Toggle Definition of the stable interface subsection</span> </button> <ul id="toc-Definition_of_the_stable_interface-sublist" class="vector-toc-list"> <li id="toc-Stable_to_call" class="vector-toc-list-item vector-toc-level-2"> <a class="vector-toc-link" href="#Stable_to_call"> <div class="vector-toc-text"> <span class="vector-toc-numb">3.1</span> <span>Stable to call</span> </div> </a> <ul id="toc-Stable_to_call-sublist" class="vector-toc-list"> </ul> </li> <li id="toc-Stable_to_type" class="vector-toc-list-item vector-toc-level-2"> <a class="vector-toc-link" href="#Stable_to_type"> <div class="vector-toc-text"> <span class="vector-toc-numb">3.2</span> <span>Stable to type</span> </div> </a> <ul id="toc-Stable_to_type-sublist" class="vector-toc-list"> </ul> </li> <li id="toc-Stable_to_extend" class="vector-toc-list-item vector-toc-level-2"> <a class="vector-toc-link" href="#Stable_to_extend"> <div class="vector-toc-text"> <span class="vector-toc-numb">3.3</span> <span>Stable to extend</span> </div> </a> <ul id="toc-Stable_to_extend-sublist" class="vector-toc-list"> </ul> </li> <li id="toc-Stable_to_use" class="vector-toc-list-item vector-toc-level-2"> <a class="vector-toc-link" href="#Stable_to_use"> <div class="vector-toc-text"> <span class="vector-toc-numb">3.4</span> <span>Stable to use</span> </div> </a> <ul id="toc-Stable_to_use-sublist" class="vector-toc-list"> </ul> </li> <li id="toc-Stable_to_access" class="vector-toc-list-item vector-toc-level-2"> <a class="vector-toc-link" href="#Stable_to_access"> <div class="vector-toc-text"> <span class="vector-toc-numb">3.5</span> <span>Stable to access</span> </div> </a> <ul id="toc-Stable_to_access-sublist" class="vector-toc-list"> </ul> </li> <li id="toc-Stable_to_implement" class="vector-toc-list-item vector-toc-level-2"> <a class="vector-toc-link" href="#Stable_to_implement"> <div class="vector-toc-text"> <span class="vector-toc-numb">3.6</span> <span>Stable to implement</span> </div> </a> <ul id="toc-Stable_to_implement-sublist" class="vector-toc-list"> </ul> </li> <li id="toc-Stable_to_override" class="vector-toc-list-item vector-toc-level-2"> <a class="vector-toc-link" href="#Stable_to_override"> <div class="vector-toc-text"> <span class="vector-toc-numb">3.7</span> <span>Stable to override</span> </div> </a> <ul id="toc-Stable_to_override-sublist" class="vector-toc-list"> </ul> </li> <li id="toc-Global_variables" class="vector-toc-list-item vector-toc-level-2"> <a class="vector-toc-link" href="#Global_variables"> <div class="vector-toc-text"> <span class="vector-toc-numb">3.8</span> <span>Global variables</span> </div> </a> <ul id="toc-Global_variables-sublist" class="vector-toc-list"> </ul> </li> </ul> </li> <li id="toc-Stability_annotations" class="vector-toc-list-item vector-toc-level-1 vector-toc-list-item-expanded"> <a class="vector-toc-link" href="#Stability_annotations"> <div class="vector-toc-text"> <span class="vector-toc-numb">4</span> <span>Stability annotations</span> </div> </a> <button aria-controls="toc-Stability_annotations-sublist" class="cdx-button cdx-button--weight-quiet cdx-button--icon-only vector-toc-toggle"> <span class="vector-icon mw-ui-icon-wikimedia-expand"></span> <span>Toggle Stability annotations subsection</span> </button> <ul id="toc-Stability_annotations-sublist" class="vector-toc-list"> <li id="toc-Add_guarantees" class="vector-toc-list-item vector-toc-level-2"> <a class="vector-toc-link" href="#Add_guarantees"> <div class="vector-toc-text"> <span class="vector-toc-numb">4.1</span> <span>Add guarantees</span> </div> </a> <ul id="toc-Add_guarantees-sublist" class="vector-toc-list"> </ul> </li> <li id="toc-Remove_guarantees" class="vector-toc-list-item vector-toc-level-2"> <a class="vector-toc-link" href="#Remove_guarantees"> <div class="vector-toc-text"> <span class="vector-toc-numb">4.2</span> <span>Remove guarantees</span> </div> </a> <ul id="toc-Remove_guarantees-sublist" class="vector-toc-list"> </ul> </li> </ul> </li> <li id="toc-Deprecation_process" class="vector-toc-list-item vector-toc-level-1 vector-toc-list-item-expanded"> <a class="vector-toc-link" href="#Deprecation_process"> <div class="vector-toc-text"> <span class="vector-toc-numb">5</span> <span>Deprecation process</span> </div> </a> <button aria-controls="toc-Deprecation_process-sublist" class="cdx-button cdx-button--weight-quiet cdx-button--icon-only vector-toc-toggle"> <span class="vector-icon mw-ui-icon-wikimedia-expand"></span> <span>Toggle Deprecation process subsection</span> </button> <ul id="toc-Deprecation_process-sublist" class="vector-toc-list"> <li id="toc-Soft_deprecation" class="vector-toc-list-item vector-toc-level-2"> <a class="vector-toc-link" href="#Soft_deprecation"> <div class="vector-toc-text"> <span class="vector-toc-numb">5.1</span> <span>Soft deprecation</span> </div> </a> <ul id="toc-Soft_deprecation-sublist" class="vector-toc-list"> </ul> </li> <li id="toc-Hard_deprecation" class="vector-toc-list-item vector-toc-level-2"> <a class="vector-toc-link" href="#Hard_deprecation"> <div class="vector-toc-text"> <span class="vector-toc-numb">5.2</span> <span>Hard deprecation</span> </div> </a> <ul id="toc-Hard_deprecation-sublist" class="vector-toc-list"> </ul> </li> <li id="toc-Removal" class="vector-toc-list-item vector-toc-level-2"> <a class="vector-toc-link" href="#Removal"> <div class="vector-toc-text"> <span class="vector-toc-numb">5.3</span> <span>Removal</span> </div> </a> <ul id="toc-Removal-sublist" class="vector-toc-list"> </ul> </li> <li id="toc-Further_guidance" class="vector-toc-list-item vector-toc-level-2"> <a class="vector-toc-link" href="#Further_guidance"> <div class="vector-toc-text"> <span class="vector-toc-numb">5.4</span> <span>Further guidance</span> </div> </a> <ul id="toc-Further_guidance-sublist" class="vector-toc-list"> </ul> </li> </ul> </li> <li id="toc-Meta" class="vector-toc-list-item vector-toc-level-1 vector-toc-list-item-expanded"> <a class="vector-toc-link" href="#Meta"> <div class="vector-toc-text"> <span class="vector-toc-numb">6</span> <span>Meta</span> </div> </a> <button aria-controls="toc-Meta-sublist" class="cdx-button cdx-button--weight-quiet cdx-button--icon-only vector-toc-toggle"> <span class="vector-icon mw-ui-icon-wikimedia-expand"></span> <span>Toggle Meta subsection</span> </button> <ul id="toc-Meta-sublist" class="vector-toc-list"> <li id="toc-Motivation" class="vector-toc-list-item vector-toc-level-2"> <a class="vector-toc-link" href="#Motivation"> <div class="vector-toc-text"> <span class="vector-toc-numb">6.1</span> <span>Motivation</span> </div> </a> <ul id="toc-Motivation-sublist" class="vector-toc-list"> </ul> </li> <li id="toc-Scope" class="vector-toc-list-item vector-toc-level-2"> <a class="vector-toc-link" href="#Scope"> <div class="vector-toc-text"> <span class="vector-toc-numb">6.2</span> <span>Scope</span> </div> </a> <ul id="toc-Scope-sublist" class="vector-toc-list"> </ul> </li> <li id="toc-Ecosystem" class="vector-toc-list-item vector-toc-level-2"> <a class="vector-toc-link" href="#Ecosystem"> <div class="vector-toc-text"> <span class="vector-toc-numb">6.3</span> <span>Ecosystem</span> </div> </a> <ul id="toc-Ecosystem-sublist" class="vector-toc-list"> </ul> </li> <li id="toc-History" class="vector-toc-list-item vector-toc-level-2"> <a class="vector-toc-link" href="#History"> <div class="vector-toc-text"> <span class="vector-toc-numb">6.4</span> <span>History</span> </div> </a> <ul id="toc-History-sublist" class="vector-toc-list"> </ul> </li> </ul> </li> <li id="toc-Frontend_policy" class="vector-toc-list-item vector-toc-level-1 vector-toc-list-item-expanded"> <a class="vector-toc-link" href="#Frontend_policy"> <div class="vector-toc-text"> <span class="vector-toc-numb">7</span> <span>Frontend policy</span> </div> </a> <ul id="toc-Frontend_policy-sublist" class="vector-toc-list"> </ul> </li> </ul> </div> </div> </nav> </div> </div> <div class="mw-content-container"> <main id="content" class="mw-body"> <header class="mw-body-header vector-page-titlebar"> <nav aria-label="Contents" class="vector-toc-landmark"> <div id="vector-page-titlebar-toc" class="vector-dropdown vector-page-titlebar-toc vector-button-flush-left" > <input type="checkbox" id="vector-page-titlebar-toc-checkbox" role="button" aria-haspopup="true" data-event-name="ui.dropdown-vector-page-titlebar-toc" class="vector-dropdown-checkbox " aria-label="Toggle the table of contents" > <label id="vector-page-titlebar-toc-label" for="vector-page-titlebar-toc-checkbox" class="vector-dropdown-label cdx-button cdx-button--fake-button cdx-button--fake-button--enabled cdx-button--weight-quiet cdx-button--icon-only " aria-hidden="true" ><span class="vector-icon mw-ui-icon-listBullet mw-ui-icon-wikimedia-listBullet"></span> <span class="vector-dropdown-label-text">Toggle the table of contents</span> </label> <div class="vector-dropdown-content"> <div id="vector-page-titlebar-toc-unpinned-container" class="vector-unpinned-container"> </div> </div> </div> </nav> <h1 id="firstHeading" class="firstHeading mw-first-heading"><span class="mw-page-title-main">Stable interface policy</span></h1> <div class="mw-indicators"> </div> </header> <div class="vector-page-toolbar"> <div class="vector-page-toolbar-container"> <div id="left-navigation"> <nav aria-label="Namespaces"> <div id="p-associated-pages" class="vector-menu vector-menu-tabs mw-portlet mw-portlet-associated-pages" > <div class="vector-menu-content"> <ul class="vector-menu-content-list"> <li id="ca-nstab-main" class="selected vector-tab-noicon mw-list-item"><a href="/wiki/Stable_interface_policy" title="View the content page [c]" accesskey="c"><span>Page</span></a></li><li id="ca-talk" class="vector-tab-noicon mw-list-item"><a href="/wiki/Talk:Stable_interface_policy" rel="discussion" title="Discussion about the content page [t]" accesskey="t"><span>Discussion</span></a></li> </ul> </div> </div> <div id="vector-variants-dropdown" class="vector-dropdown emptyPortlet" > <input type="checkbox" id="vector-variants-dropdown-checkbox" role="button" aria-haspopup="true" data-event-name="ui.dropdown-vector-variants-dropdown" class="vector-dropdown-checkbox " aria-label="Change language variant" > <label id="vector-variants-dropdown-label" for="vector-variants-dropdown-checkbox" class="vector-dropdown-label cdx-button cdx-button--fake-button cdx-button--fake-button--enabled cdx-button--weight-quiet" aria-hidden="true" ><span class="vector-dropdown-label-text">English</span> </label> <div class="vector-dropdown-content"> <div id="p-variants" class="vector-menu mw-portlet mw-portlet-variants emptyPortlet" > <div class="vector-menu-content"> <ul class="vector-menu-content-list"> </ul> </div> </div> </div> </div> </nav> </div> <div id="right-navigation" class="vector-collapsible"> <nav aria-label="Views"> <div id="p-views" class="vector-menu vector-menu-tabs mw-portlet mw-portlet-views" > <div class="vector-menu-content"> <ul class="vector-menu-content-list"> <li id="ca-view" class="selected vector-tab-noicon mw-list-item"><a href="/wiki/Stable_interface_policy"><span>Read</span></a></li><li id="ca-edit" class="vector-tab-noicon mw-list-item"><a href="/w/index.php?title=Stable_interface_policy&action=edit" title="Edit the source code of this page [e]" accesskey="e"><span>Edit</span></a></li><li id="ca-history" class="vector-tab-noicon mw-list-item"><a href="/w/index.php?title=Stable_interface_policy&action=history" title="Past revisions of this page [h]" accesskey="h"><span>View history</span></a></li> </ul> </div> </div> </nav> <nav class="vector-page-tools-landmark" aria-label="Page tools"> <div id="vector-page-tools-dropdown" class="vector-dropdown vector-page-tools-dropdown" > <input type="checkbox" id="vector-page-tools-dropdown-checkbox" role="button" aria-haspopup="true" data-event-name="ui.dropdown-vector-page-tools-dropdown" class="vector-dropdown-checkbox " aria-label="Tools" > <label id="vector-page-tools-dropdown-label" for="vector-page-tools-dropdown-checkbox" class="vector-dropdown-label cdx-button cdx-button--fake-button cdx-button--fake-button--enabled cdx-button--weight-quiet" aria-hidden="true" ><span class="vector-dropdown-label-text">Tools</span> </label> <div class="vector-dropdown-content"> <div id="vector-page-tools-unpinned-container" class="vector-unpinned-container"> <div id="vector-page-tools" class="vector-page-tools vector-pinnable-element"> <div class="vector-pinnable-header vector-page-tools-pinnable-header vector-pinnable-header-unpinned" data-feature-name="page-tools-pinned" data-pinnable-element-id="vector-page-tools" data-pinned-container-id="vector-page-tools-pinned-container" data-unpinned-container-id="vector-page-tools-unpinned-container" > <div class="vector-pinnable-header-label">Tools</div> <button class="vector-pinnable-header-toggle-button vector-pinnable-header-pin-button" data-event-name="pinnable-header.vector-page-tools.pin">move to sidebar</button> <button class="vector-pinnable-header-toggle-button vector-pinnable-header-unpin-button" data-event-name="pinnable-header.vector-page-tools.unpin">hide</button> </div> <div id="p-cactions" class="vector-menu mw-portlet mw-portlet-cactions emptyPortlet vector-has-collapsible-items" title="More options" > <div class="vector-menu-heading"> Actions </div> <div class="vector-menu-content"> <ul class="vector-menu-content-list"> <li id="ca-more-view" class="selected vector-more-collapsible-item mw-list-item"><a href="/wiki/Stable_interface_policy"><span>Read</span></a></li><li id="ca-more-edit" class="vector-more-collapsible-item mw-list-item"><a href="/w/index.php?title=Stable_interface_policy&action=edit" title="Edit the source code of this page [e]" accesskey="e"><span>Edit</span></a></li><li id="ca-more-history" class="vector-more-collapsible-item mw-list-item"><a href="/w/index.php?title=Stable_interface_policy&action=history"><span>View history</span></a></li> </ul> </div> </div> <div id="p-tb" class="vector-menu mw-portlet mw-portlet-tb" > <div class="vector-menu-heading"> General </div> <div class="vector-menu-content"> <ul class="vector-menu-content-list"> <li id="t-whatlinkshere" class="mw-list-item"><a href="/wiki/Special:WhatLinksHere/Stable_interface_policy" title="A list of all wiki pages that link here [j]" accesskey="j"><span>What links here</span></a></li><li id="t-recentchangeslinked" class="mw-list-item"><a href="/wiki/Special:RecentChangesLinked/Stable_interface_policy" rel="nofollow" title="Recent changes in pages linked from this page [k]" accesskey="k"><span>Related changes</span></a></li><li id="t-upload" class="mw-list-item"><a href="//commons.wikimedia.org/wiki/Special:UploadWizard" title="Upload files [u]" accesskey="u"><span>Upload file</span></a></li><li id="t-specialpages" class="mw-list-item"><a href="/wiki/Special:SpecialPages" title="A list of all special pages [q]" accesskey="q"><span>Special pages</span></a></li><li id="t-permalink" class="mw-list-item"><a href="/w/index.php?title=Stable_interface_policy&oldid=6774239" title="Permanent link to this revision of this page"><span>Permanent link</span></a></li><li id="t-info" class="mw-list-item"><a href="/w/index.php?title=Stable_interface_policy&action=info" title="More information about this page"><span>Page information</span></a></li><li id="t-cite" class="mw-list-item"><a href="/w/index.php?title=Special:CiteThisPage&page=Stable_interface_policy&id=6774239&wpFormIdentifier=titleform" title="Information on how to cite this page"><span>Cite this page</span></a></li><li id="t-urlshortener" class="mw-list-item"><a href="/w/index.php?title=Special:UrlShortener&url=https%3A%2F%2Fwww.mediawiki.org%2Fwiki%2FStable_interface_policy"><span>Get shortened URL</span></a></li><li id="t-urlshortener-qrcode" class="mw-list-item"><a href="/w/index.php?title=Special:QrCode&url=https%3A%2F%2Fwww.mediawiki.org%2Fwiki%2FStable_interface_policy"><span>Download QR code</span></a></li> </ul> </div> </div> <div id="p-coll-print_export" class="vector-menu mw-portlet mw-portlet-coll-print_export" > <div class="vector-menu-heading"> Print/export </div> <div class="vector-menu-content"> <ul class="vector-menu-content-list"> <li id="coll-create_a_book" class="mw-list-item"><a href="/w/index.php?title=Special:Book&bookcmd=book_creator&referer=Stable+interface+policy"><span>Create a book</span></a></li><li id="coll-download-as-rl" class="mw-list-item"><a href="/w/index.php?title=Special:DownloadAsPdf&page=Stable_interface_policy&action=show-download-screen"><span>Download as PDF</span></a></li><li id="t-print" class="mw-list-item"><a href="/w/index.php?title=Stable_interface_policy&printable=yes" title="Printable version of this page [p]" accesskey="p"><span>Printable version</span></a></li> </ul> </div> </div> <div id="p-wikibase-otherprojects" class="vector-menu mw-portlet mw-portlet-wikibase-otherprojects emptyPortlet" > <div class="vector-menu-heading"> In other projects </div> <div class="vector-menu-content"> <ul class="vector-menu-content-list"> </ul> </div> </div> </div> </div> </div> </div> </nav> </div> </div> </div> <div class="vector-column-end"> <div class="vector-sticky-pinned-container"> <nav class="vector-page-tools-landmark" aria-label="Page tools"> <div id="vector-page-tools-pinned-container" class="vector-pinned-container"> </div> </nav> <nav class="vector-appearance-landmark" aria-label="Appearance"> <div id="vector-appearance-pinned-container" class="vector-pinned-container"> <div id="vector-appearance" class="vector-appearance vector-pinnable-element"> <div class="vector-pinnable-header vector-appearance-pinnable-header vector-pinnable-header-pinned" data-feature-name="appearance-pinned" data-pinnable-element-id="vector-appearance" data-pinned-container-id="vector-appearance-pinned-container" data-unpinned-container-id="vector-appearance-unpinned-container" > <div class="vector-pinnable-header-label">Appearance</div> <button class="vector-pinnable-header-toggle-button vector-pinnable-header-pin-button" data-event-name="pinnable-header.vector-appearance.pin">move to sidebar</button> <button class="vector-pinnable-header-toggle-button vector-pinnable-header-unpin-button" data-event-name="pinnable-header.vector-appearance.unpin">hide</button> </div> </div> </div> </nav> </div> </div> <div id="bodyContent" class="vector-body" aria-labelledby="firstHeading" data-mw-ve-target-container> <div class="vector-body-before-content"> <div id="siteSub" class="noprint">From mediawiki.org</div> </div> <div id="contentSub"><div id="mw-content-subtitle"></div></div> <div id="mw-content-text" class="mw-body-content"><div class="mw-content-ltr mw-parser-output" lang="en" dir="ltr"><style data-mw-deduplicate="TemplateStyles:r6651103">.mw-parser-output .nmbox{background:#f8f9fa;border:1px solid #AAA;box-sizing:border-box;margin:2px 0;padding:0}.mw-parser-output .nmbox *{box-sizing:border-box}.mw-parser-output .nmbox-header{background:#eaecf0;padding:4px 0.5em;font-weight:bold;text-align:center;white-space:nowrap}.mw-parser-output .nmbox .mbox-image{display:inline-block;padding-right:1em}.mw-parser-output .nmbox-text{border-top:1px solid #AAA;width:100%;padding:4px 0.5em}@media screen and (min-width:768px){.mw-parser-output .nmbox-header{display:table-cell;border-right:1px solid #AAA;width:1%}.mw-parser-output .nmbox-text{border-top:none;display:table-cell}}@media screen{html.skin-theme-clientpref-night .mw-parser-output .nmbox-header,html.skin-theme-clientpref-night .mw-parser-output .nmbox{background:transparent;color:inherit}}@media screen and (prefers-color-scheme:dark){html.skin-theme-clientpref-os .mw-parser-output .nmbox-header,html.skin-theme-clientpref-os .mw-parser-output .nmbox{background:transparent;color:inherit}}</style> <div class="nmbox noprint mw-content-ltr"><div class="nmbox-header"><a href="/wiki/Special:MyLanguage/Project:Language_policy" title="Special:MyLanguage/Project:Language policy">Languages:</a><span style="display:none"><a href="/wiki/Project:Language_policy" title="Project:Language policy"> </a></span> </div> <div class="nmbox-text mbox-text"><b><a class="mw-selflink selflink">English</a></b> • <bdi lang="ja"><span class="plainlinks"><a class="external text" href="https://www.mediawiki.org/wiki/Stable_interface_policy/ja">日本語</a></span></bdi><span class="autonym"></span><span class="autonym"></span></div> </div> <style data-mw-deduplicate="TemplateStyles:r6824882">.mw-parser-output table.ambox{margin:0 10%;width:unset;border:1px solid #a2a9b1;border-left:10px solid #36c;background-color:#fbfbfb;box-sizing:border-box}.mw-parser-output table.ambox+table.ambox,.mw-parser-output table.ambox+link+table.ambox,.mw-parser-output table.ambox+style+table.ambox{margin-top:-1px}.mw-parser-output .ambox td.mbox-empty-cell{border:none;padding:0;width:1px}.mw-parser-output .ambox th.mbox-text,.mw-parser-output .ambox td.mbox-text{border:none;padding:0.25em 0.5em;width:100%}.mw-parser-output .ambox td.mbox-image{padding:2px 0 2px 0.5em}.mw-parser-output .ambox td.mbox-imageright{padding:2px 0.5em 2px 0}.mw-parser-output table.ambox-notice{border-left-color:#36c}.mw-parser-output table.ambox-speedy{background-color:var(--background-color-error-subtle,#fee7e6)}.mw-parser-output table.ambox-delete,.mw-parser-output table.ambox-speedy{border-left-color:var(--background-color-error--active,#b32424)}.mw-parser-output table.ambox-content{border-left-color:#f28500}.mw-parser-output table.ambox-style{border-left-color:#fc3}.mw-parser-output table.ambox-move{border-left-color:#9932cc}.mw-parser-output table.ambox-protection{border-left-color:#a2a9b1}html body.mediawiki .mw-parser-output .ambox.mbox-small{clear:right;float:right;margin:4px 0 4px 1em;box-sizing:border-box;width:238px;font-size:88%;line-height:1.25em}html body.mediawiki .mw-parser-output .ambox.mbox-small-left{margin:4px 1em 4px 0;box-sizing:border-box;overflow:hidden;width:238px;border-collapse:collapse;font-size:88%;line-height:1.25em}</style><table class="ambox ambox-notice plainlinks metadata" role="presentation"><tbody><tr><td class="mbox-image"><div style="width:52px"><span typeof="mw:File"><a href="/wiki/File:OOjs_UI_icon_check-constructive.svg" class="mw-file-description"><img src="//upload.wikimedia.org/wikipedia/commons/thumb/f/f6/OOjs_UI_icon_check-constructive.svg/30px-OOjs_UI_icon_check-constructive.svg.png" decoding="async" width="30" height="30" class="mw-file-element" srcset="//upload.wikimedia.org/wikipedia/commons/thumb/f/f6/OOjs_UI_icon_check-constructive.svg/45px-OOjs_UI_icon_check-constructive.svg.png 1.5x, //upload.wikimedia.org/wikipedia/commons/thumb/f/f6/OOjs_UI_icon_check-constructive.svg/60px-OOjs_UI_icon_check-constructive.svg.png 2x" data-file-width="20" data-file-height="20"/></a></span></div></td><td class="mbox-text"><div class="mbox-text-span">This page documents an official <a href="/wiki/Special:MyLanguage/Development_policy" title="Special:MyLanguage/Development policy">Wikimedia development policy</a>. There is no current mechanism to make changes, as the <a href="/wiki/Special:MyLanguage/Requests_for_comment" title="Special:MyLanguage/Requests for comment">TechCom RFC process</a> is defunct.</div></td></tr></tbody></table> <style data-mw-deduplicate="TemplateStyles:r6605224">.mw-parser-output .tpl-sidebar{background-color:var(--background-color-interactive-subtle,#f8f9fa);border:1px solid var(--border-color-divider,#a2a9b1);color:var(--color-base,#202122);width:22em;padding:.2em;text-align:center;line-height:1.4em;font-size:88%}.mw-parser-output .tpl-sidebar-pagedir-ltr,.mw-parser-output .tpl-sidebar.tpl-sidebar-floatright{float:right;clear:right;margin:.5em 0 1em 1em}.mw-parser-output .tpl-sidebar-pagedir-rtl,.mw-parser-output .tpl-sidebar.tpl-sidebar-floatleft{float:left;clear:left;margin:.5em 1em 1em 0}.mw-parser-output .tpl-sidebar.tpl-sidebar-floatnone{float:none;clear:both;margin:.5em 0 1em 1em}.mw-parser-output .tpl-sidebar>caption{padding-bottom:.2em;font-size:125%;line-height:1.2em;font-weight:bold}.mw-parser-output .tpl-sidebar>tbody>tr>th,.mw-parser-output .tpl-sidebar>tbody>tr>td{padding:0}.mw-parser-output .tpl-sidebar .tpl-sidebar-topimage>td{padding:.4em 0}.mw-parser-output .tpl-sidebar-imagecaption{padding-top:.2em;line-height:1.2em}.mw-parser-output .tpl-sidebar .tpl-sidebar-pretitle>td{padding-top:.4em;line-height:1.2em}.mw-parser-output .tpl-sidebar .tpl-sidebar-topimage+.tpl-sidebar-pretitle>td{padding-top:.2em}.mw-parser-output .tpl-sidebar .tpl-sidebar-title>th{padding:.2em .4em .2em;font-size:145%;line-height:1.2em}.mw-parser-output .tpl-sidebar .tpl-sidebar-pretitle+.tpl-sidebar-title>th{padding-top:0}.mw-parser-output .tpl-sidebar .tpl-sidebar-image>td{padding:.2em 0 .4em}.mw-parser-output .tpl-sidebar .tpl-sidebar-abovebelow>td{padding:.3em .4em;font-weight:bold}.mw-parser-output .tpl-sidebar .tpl-sidebar-heading>th{padding-top:.2em}.mw-parser-output .tpl-sidebar .tpl-sidebar-image~.tpl-sidebar-heading-first>th{padding-top:.4em}.mw-parser-output .tpl-sidebar .tpl-sidebar-content>td{padding-bottom:.2em}.mw-parser-output .tpl-sidebar :not(.tpl-sidebar-heading)+.tpl-sidebar-content-first>td{padding-top:.2em}.mw-parser-output .tpl-sidebar-navbar>td{font-size:115%}.mw-parser-output .tpl-sidebar-pagedir-ltr .tpl-sidebar-navbar>td{text-align:right}.mw-parser-output .tpl-sidebar-pagedir-rtl .tpl-sidebar-navbar>td{text-align:left}</style><table class="vertical-navbox tpl-sidebar tpl-sidebar-pagedir-ltr nowraplinks" role="navigation" style="width:22em; border-spacing: 0.4em 0;"><tbody><tr class="tpl-sidebar-title"> <th class="" style="">Development policies</th> </tr><tr class="tpl-sidebar-content tpl-sidebar-content-first"> <td class="" style=";"> <style data-mw-deduplicate="TemplateStyles:r6219282">.mw-parser-output .plainlist ul{line-height:inherit;list-style:none none;margin:0}.mw-parser-output .plainlist ul li{margin-bottom:0}</style><div class="plainlist"> <ul><li><a href="/wiki/Special:MyLanguage/Development_policy" title="Special:MyLanguage/Development policy">Development policy</a><span style="display:none"><a href="/wiki/Development_policy" title="Development policy"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/Wikimedia_Engineering_Architecture_Principles" title="Special:MyLanguage/Wikimedia Engineering Architecture Principles">Architecture principles</a><span style="display:none"><a href="/wiki/Wikimedia_Engineering_Architecture_Principles" title="Wikimedia Engineering Architecture Principles"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/Wikimedia_services_policy" title="Special:MyLanguage/Wikimedia services policy">Services policy</a><span style="display:none"><a href="/wiki/Wikimedia_services_policy" title="Wikimedia services policy"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/Support_policy_for_PHP" title="Special:MyLanguage/Support policy for PHP">Support policy for PHP</a><span style="display:none"><a href="/wiki/Support_policy_for_PHP" title="Support policy for PHP"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/Gerrit/Privilege_policy" title="Special:MyLanguage/Gerrit/Privilege policy">Gerrit privilege policy</a><span style="display:none"><a href="/wiki/Gerrit/Privilege_policy" title="Gerrit/Privilege policy"> </a></span></li> <li><b><a href="/wiki/Special:MyLanguage/Stable_interface_policy" title="Special:MyLanguage/Stable interface policy">Stable interface policy</a></b><span style="display:none"><a class="mw-selflink selflink"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/MediaWiki_database_policy" title="Special:MyLanguage/MediaWiki database policy">MediaWiki database policy</a><span style="display:none"><a href="/wiki/MediaWiki_database_policy" title="MediaWiki database policy"> </a></span></li></ul> </div></td> </tr><tr class="tpl-sidebar-heading"> <th class="" style=";">See also</th> </tr><tr class="tpl-sidebar-content"> <td class="" style=";"> <a href="/wiki/Special:MyLanguage/Development_guidelines" title="Special:MyLanguage/Development guidelines">Development guidelines</a><span style="display:none"><a href="/wiki/Development_guidelines" title="Development guidelines"> </a></span></td> </tr><tr class="tpl-sidebar-navbar"> <td style=""><style data-mw-deduplicate="TemplateStyles:r4692751">.mw-parser-output .navbar{display:inline;font-size:88%;font-weight:normal}.mw-parser-output .navbar ul{display:inline;white-space:nowrap}.mw-parser-output .navbar li{word-spacing:-0.125em}.mw-parser-output .navbox .navbar{display:block;font-size:100%}.mw-parser-output .navbox-title .navbar{float:left;text-align:left;margin-right:0.5em;width:6em}</style><span class="noprint plainlinks navbar" style=""><small><span style="white-space:nowrap;word-spacing:-.12em;"><a href="/wiki/Template:Development_policy" title="Template:Development policy"><span style="" title="View this template">v</span></a><span style=""> <b>·</b> </span><a class="external text" href="https://www.mediawiki.org/wiki/Template_talk:Development_policy"><span style="" title="Discuss this template">d</span></a><span style=""> <b>·</b> </span><a class="external text" href="https://www.mediawiki.org/w/index.php?title=Template:Development_policy&action=edit"><span style="" title="Edit this template">e</span></a></span></small></span></td> </tr> </tbody></table> <link rel="mw-deduplicated-inline-style" href="mw-data:TemplateStyles:r6605224"><table class="vertical-navbox tpl-sidebar tpl-sidebar-pagedir-ltr nowraplinks" role="navigation" style="width:22em; border-spacing: 0.4em 0;"><tbody><tr class="tpl-sidebar-title"> <th class="" style="">Deprecation policies</th> </tr><tr class="tpl-sidebar-content tpl-sidebar-content-first"> <td class="" style=";"> <link rel="mw-deduplicated-inline-style" href="mw-data:TemplateStyles:r6219282"><div class="plainlist"> <ul><li><b><a href="/wiki/Special:MyLanguage/Stable_interface_policy" title="Special:MyLanguage/Stable interface policy">PHP interfaces</a></b><span style="display:none"><a class="mw-selflink selflink"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/Requests_for_comment/API_roadmap#Deprecation_process" title="Special:MyLanguage/Requests for comment/API roadmap">Action API (api.php)</a><span style="display:none"><a href="/wiki/Requests_for_comment/API_roadmap#Deprecation_process" title="Requests for comment/API roadmap"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/API_versioning" title="Special:MyLanguage/API versioning">REST APIs</a><span style="display:none"><a href="/wiki/API_versioning" title="API versioning"> </a></span></li> <li><a href="https://www.wikidata.org/wiki/Wikidata:Stable_Interface_Policy" class="extiw" title="d:Wikidata:Stable Interface Policy">Wikidata APIs</a></li></ul> </div></td> </tr><tr class="tpl-sidebar-heading"> <th class="" style=";">See also</th> </tr><tr class="tpl-sidebar-content"> <td class="" style=";"> <link rel="mw-deduplicated-inline-style" href="mw-data:TemplateStyles:r6219282"><div class="plainlist"> <ul><li><a href="/wiki/Special:MyLanguage/Version_lifecycle" title="Special:MyLanguage/Version lifecycle">Version lifecycle</a><span style="display:none"><a href="/wiki/Version_lifecycle" title="Version lifecycle"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/Compatibility" title="Special:MyLanguage/Compatibility">Compatibility</a><span style="display:none"><a href="/wiki/Compatibility" title="Compatibility"> </a></span></li></ul> </div></td> </tr><tr class="tpl-sidebar-navbar"> <td style=""><link rel="mw-deduplicated-inline-style" href="mw-data:TemplateStyles:r4692751"><span class="noprint plainlinks navbar" style=""><small><span style="white-space:nowrap;word-spacing:-.12em;"><a href="/wiki/Template:Deprecation_policies" title="Template:Deprecation policies"><span style="" title="View this template">v</span></a><span style=""> <b>·</b> </span><a class="external text" href="https://www.mediawiki.org/wiki/Template_talk:Deprecation_policies"><span style="" title="Discuss this template">d</span></a><span style=""> <b>·</b> </span><a class="external text" href="https://www.mediawiki.org/w/index.php?title=Template:Deprecation_policies&action=edit"><span style="" title="Edit this template">e</span></a></span></small></span></td> </tr> </tbody></table> <p>The <b>stable interface policy for MediaWiki PHP code</b> defines what parts of <a href="#Scope">the software</a> are considered stable and safe for use by other components. Code that is considered part of this "stable interface" is subject to the <a href="#Deprecation_process">deprecation process</a>. </p> <div style="clear: both; margin-bottom: .5em; float: right; margin-left:2em; width: auto;"><meta property="mw:PageProp/toc"/></div> <div class="mw-heading mw-heading2 ext-discussiontools-init-section"><h2 id="Quick_guide" data-mw-thread-id="h-Quick_guide"><span data-mw-comment-start="" id="h-Quick_guide"></span>Quick guide<span data-mw-comment-end="h-Quick_guide"></span></h2><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/w/index.php?title=Stable_interface_policy&action=edit&section=1" title="Edit section: Quick guide"><span>edit</span></a><span class="mw-editsection-bracket">]</span></span></div> <div class="mw-heading mw-heading3"><h3 id="Using_code" data-mw-thread-id="h-Using_code-Quick_guide"><span data-mw-comment-start="" id="h-Using_code-Quick_guide"></span>Using code<span data-mw-comment-end="h-Using_code-Quick_guide"></span></h3><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/w/index.php?title=Stable_interface_policy&action=edit&section=2" title="Edit section: Using code"><span>edit</span></a><span class="mw-editsection-bracket">]</span></span></div> <ul><li>It is generally <a href="#Stable_to_call">stable to call</a> public methods on a class instance.</li> <li>It is generally <a href="#Stable_to_call">not stable to construct</a> a class (instantiate).</li> <li>It is generally <a href="#Stable_to_extend">not stable to extend</a> a class (subclass) and <a href="#Stable_to_implement">not stable to implement</a> an interface.</li></ul> <div class="mw-heading mw-heading3"><h3 id="Writing_code" data-mw-thread-id="h-Writing_code-Quick_guide"><span data-mw-comment-start="" id="h-Writing_code-Quick_guide"></span>Writing code<span data-mw-comment-end="h-Writing_code-Quick_guide"></span></h3><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/w/index.php?title=Stable_interface_policy&action=edit&section=3" title="Edit section: Writing code"><span>edit</span></a><span class="mw-editsection-bracket">]</span></span></div> <p>When changing existing code: </p> <ul><li>Keep <b>public methods</b> and <b>hook signatures</b> compatible for callers. Follow the <a href="#Deprecation_process">deprecation process</a> for breaking changes.</li> <li>Keep <b>constructor signatures</b> compatible, if it is marked <code>@stable to call</code>.</li> <li>Keep <b>method signatures</b> compatible for subclasses, if the method is marked <code>@stable to override</code>.</li></ul> <p>When creating new code: </p> <ul><li>When defining hooks, keep the signature minimal. Expose narrow interfaces, ideally only pure value objects, as parameters.</li> <li>Avoid using interfaces as extension points. It is recommended to use an abstract base class instead. See <a href="#Stable_to_extend">Stable to extend</a>.</li></ul> <div class="mw-heading mw-heading2 ext-discussiontools-init-section"><h2 id="Terminology" data-mw-thread-id="h-Terminology"><span data-mw-comment-start="" id="h-Terminology"></span>Terminology<span data-mw-comment-end="h-Terminology"></span></h2><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/w/index.php?title=Stable_interface_policy&action=edit&section=4" title="Edit section: Terminology"><span>edit</span></a><span class="mw-editsection-bracket">]</span></span></div> <ul><li><b>Authors</b>: You are working on something that others will use. For example, a class in MediaWiki core that extensions can use.</li> <li><b>Users</b>: You are working on something that uses a stable interface. For example, a class in an extension that interacts with MediaWiki core.</li> <li><b>Wikimedia maintained code</b> is defined as any code running on Wikimedia sites or officially <a href="https://phabricator.wikimedia.org/diffusion/MREL/browse/master/make-release/settings.yaml" class="extiw" title="phab:diffusion/MREL/browse/master/make-release/settings.yaml">published</a> by Wikimedia for use by others.</li> <li>The <b>MediaWiki ecosystem</b> includes community mantained extensions that meet the criteria described in the <a href="#Ecosystem">"Ecosystem"</a> section below.</li></ul> <div class="mw-heading mw-heading2 ext-discussiontools-init-section"><h2 id="Definition_of_the_stable_interface" data-mw-thread-id="h-Definition_of_the_stable_interface"><span data-mw-comment-start="" id="h-Definition_of_the_stable_interface"></span>Definition of the stable interface<span data-mw-comment-end="h-Definition_of_the_stable_interface"></span></h2><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/w/index.php?title=Stable_interface_policy&action=edit&section=5" title="Edit section: Definition of the stable interface"><span>edit</span></a><span class="mw-editsection-bracket">]</span></span></div> <div class="mw-heading mw-heading3"><h3 id="Stable_to_call" data-mw-thread-id="h-Stable_to_call-Definition_of_the_stable_interface"><span data-mw-comment-start="" id="h-Stable_to_call-Definition_of_the_stable_interface"></span>Stable to call<span data-mw-comment-end="h-Stable_to_call-Definition_of_the_stable_interface"></span></h3><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/w/index.php?title=Stable_interface_policy&action=edit&section=6" title="Edit section: Stable to call"><span>edit</span></a><span class="mw-editsection-bracket">]</span></span></div> <style data-mw-deduplicate="TemplateStyles:r6651107">.mw-parser-output .note{background-position:left 7px top 50%;padding:0.5em 0.5em 0.5em 40px;margin:0.5em 0;overflow:hidden;background-color:#f8f9fa;color:#333;background-repeat:no-repeat;border:1px solid #ddd}.mw-parser-output .note-inline{display:inline-block;vertical-align:middle}.mw-parser-output .note-info{background-color:#eaf3ff;color:#333;background-image:url("https://upload.wikimedia.org/wikipedia/commons/e/ec/OOjs_UI_icon_information-progressive.svg");background-size:25px;border-color:#a3caff;padding-left:40px;min-height:25px}.mw-parser-output .note-reminder{background-color:#fff9ea;color:#333;background-image:url("https://upload.wikimedia.org/wikipedia/commons/a/a8/OOjs_UI_icon_lightbulb-yellow.svg");background-size:25px;border-color:#fc3;min-height:25px}.mw-parser-output .note-warn{background-color:#fff9ea;color:#333;background-image:url("https://upload.wikimedia.org/wikipedia/commons/3/3b/OOjs_UI_icon_alert-warning.svg");background-size:25px;border-color:#fc3;min-height:25px}.mw-parser-output .note-error{background-color:#fee7e6;color:#333;background-image:url("https://upload.wikimedia.org/wikipedia/commons/b/bf/OOjs_UI_icon_notice-destructive.svg");background-size:25px;border-color:#c33;min-height:25px}@media screen{html.skin-theme-clientpref-night .mw-parser-output .note{background-color:transparent;color:inherit}}@media screen and (prefers-color-scheme:dark){html.skin-theme-clientpref-os .mw-parser-output .note{background-color:transparent;color:inherit}}</style><div role="note" class="note note-reminder">It's generally <b>stable to call public methods</b> and access public class fields – unless these are marked otherwise.</div> <link rel="mw-deduplicated-inline-style" href="mw-data:TemplateStyles:r6651107"><div role="note" class="note note-warn">It's generally <b>not stable to directly instantiate classes</b> using the <code>new</code> operator – unless these are marked as <code>@newable</code>.</div> <p><i>Stable to call</i> 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 <a href="#Deprecation_process">deprecation process</a>. </p><p>Note that methods are <a href="#Stable_to_override">not stable to override</a> by default. </p><p>Included: </p> <ul><li>Global functions of which the name starts with the "wf" prefix.</li> <li>Public methods on any class instance.</li> <li>Protected methods of a class that is <a href="#Stable_to_extend">stable to extend</a>.</li> <li>All methods in traits that are <a href="#Stable_to_use">stable to use</a>.</li> <li>Constructor methods that are marked <code>@stable to call</code>. This means their class will be considered "newable" and thus may be instantiated using the <code>new</code> operator in any code.</li> <li>Constructor methods of classes marked <code>@newable</code> as well as classes that are <a href="#Stable_to_extend">stable to extend</a>.</li></ul> <p>Not included: </p> <ul><li>Any constructor method, unless marked <code>@stable to call</code>.</li> <li>Any method or function marked <code>@deprecated</code>, <code>@internal</code> or <code>@unstable</code>.</li> <li>Legacy class methods that do not have an explicit visibility modifier. These are technically public, but considered unstable.</li></ul> <p>For authors: </p> <ul><li>It is recommended to only mark constructors as stable to call if they are for value objects or for extendable classes.</li> <li>When making a constructor method <code>@stable to call</code>, consider marking the class it belongs to as <code>@newable</code>. 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 <code>new</code> operator. It is at the author's discretion to decide whether or not to mark a class with a stable constructor as <code>@newable</code>. 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.</li> <li>For complex classes that may involve <a href="/wiki/Dependency_Injection" title="Dependency Injection">dependency injection</a>, 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.</li></ul> <div class="mw-heading mw-heading3"><h3 id="Stable_to_type" data-mw-thread-id="h-Stable_to_type-Definition_of_the_stable_interface"><span data-mw-comment-start="" id="h-Stable_to_type-Definition_of_the_stable_interface"></span>Stable to type<span data-mw-comment-end="h-Stable_to_type-Definition_of_the_stable_interface"></span></h3><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/w/index.php?title=Stable_interface_policy&action=edit&section=7" title="Edit section: Stable to type"><span>edit</span></a><span class="mw-editsection-bracket">]</span></span></div> <link rel="mw-deduplicated-inline-style" href="mw-data:TemplateStyles:r6651107"><div role="note" class="note note-reminder">It's generally <b>stable to mention interfaces and classes</b> in type hints for parameters and return values.</div> <p><i>Stable to type</i> 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 <a href="#Stable_to_call">stable to call</a>. You can type against these interfaces and classes from various contexts; such as argument type declarations ("type hints"), return types, <code>catch</code> statements, and <code>instanceof</code> assertions. </p><p>Remember that by default interfaces are <a href="#Stable_to_implement">not stable to implement</a>, 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 <code>@stable to extend</code>, <code>@stable to implement</code>, or <code>@newable</code>. </p><p>Included: </p> <ul><li>All classes and interfaces.</li></ul> <p>Not included: </p> <ul><li>Any class or interface marked <code>@deprecated</code>, <code>@internal</code> or <code>@unstable</code>.</li></ul> <p>For authors: </p> <ul><li>Avoid using interfaces as extension points. It is recommended to use an abstract base class instead. See <a href="#Stable_to_extend">Stable to extend</a>.</li> <li>When you do create interfaces, it is recommended that you explicitly mark them as <code>@stable to type</code>. This is intended to aid the discovery of limited guarantees around interfaces.</li></ul> <div class="mw-heading mw-heading3"><h3 id="Stable_to_extend" data-mw-thread-id="h-Stable_to_extend-Definition_of_the_stable_interface"><span data-mw-comment-start="" id="h-Stable_to_extend-Definition_of_the_stable_interface"></span>Stable to extend<span data-mw-comment-end="h-Stable_to_extend-Definition_of_the_stable_interface"></span></h3><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/w/index.php?title=Stable_interface_policy&action=edit&section=8" title="Edit section: Stable to extend"><span>edit</span></a><span class="mw-editsection-bracket">]</span></span></div> <link rel="mw-deduplicated-inline-style" href="mw-data:TemplateStyles:r6651107"><div role="note" class="note note-warn">It's generally <b>not stable to extend classes</b> – unless these are marked <code>@stable to extend</code>. This means constructor signatures may break, protected methods are unstable, and new abstract methods may be added without notice.</div> <p><i>Stable to extend</i> 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 <a href="#Deprecation_process">deprecation process</a>. Protected (and public) methods of extendable classes are automatically <a href="#Stable_to_call">stable to call</a>, unless they are marked <code>@deprecated</code>, <code>@internal</code> or <code>@unstable</code>. Remember that by default methods remain not <a href="#Stable_to_override">stable to override</a>, unless they are abstract. </p><p>Included: </p> <ul><li>Only classes that are marked <code>@stable to extend</code>.</li></ul> <p>For authors: </p> <ul><li>Constructor methods of extendable classes must be marked <code><a href="#Stable_to_call">@stable to call</a></code>.</li></ul> <ul><li>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 <a href="#Stable_to_implement">stable to implement</a>, you commit to never changing its method signatures, and never adding new methods – unless the interface as a whole is deprecated first.</li></ul> <div class="mw-heading mw-heading3"><h3 id="Stable_to_use" data-mw-thread-id="h-Stable_to_use-Definition_of_the_stable_interface"><span data-mw-comment-start="" id="h-Stable_to_use-Definition_of_the_stable_interface"></span>Stable to use<span data-mw-comment-end="h-Stable_to_use-Definition_of_the_stable_interface"></span></h3><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/w/index.php?title=Stable_interface_policy&action=edit&section=9" title="Edit section: Stable to use"><span>edit</span></a><span class="mw-editsection-bracket">]</span></span></div> <link rel="mw-deduplicated-inline-style" href="mw-data:TemplateStyles:r6651107"><div role="note" class="note note-warn">It's generally <b>not stable to use traits</b> – unless these are marked <code>@stable to use</code>. This means method signatures may break and new abstract methods may be added without notice.</div> <p><i>Stable to use</i> can apply to traits. It means all methods defined in the trait will stay backward-compatible between releases. Changes that affect classes using the trait will follow the <a href="#Deprecation_process">deprecation process</a>. All methods of usable traits are automatically <a href="#Stable_to_call">stable to call</a>, unless they are marked <code>@deprecated</code>, <code>@internal</code> or <code>@unstable</code>. Remember that by default methods remain not <a href="#Stable_to_override">stable to override</a>, unless they are abstract. </p><p>Included: </p> <ul><li>Only traits that are marked <code>@stable to use</code>.</li></ul> <div class="mw-heading mw-heading3"><h3 id="Stable_to_access" data-mw-thread-id="h-Stable_to_access-Definition_of_the_stable_interface"><span data-mw-comment-start="" id="h-Stable_to_access-Definition_of_the_stable_interface"></span>Stable to access<span data-mw-comment-end="h-Stable_to_access-Definition_of_the_stable_interface"></span></h3><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/w/index.php?title=Stable_interface_policy&action=edit&section=10" title="Edit section: Stable to access"><span>edit</span></a><span class="mw-editsection-bracket">]</span></span></div> <link rel="mw-deduplicated-inline-style" href="mw-data:TemplateStyles:r6651107"><div role="note" class="note note-warn">It's generally <b>not stable to write to public and protected fields</b>, but it is stable to read them.</div> <p><i>Stable to access</i> 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. </p><p>Included: </p> <ul><li>Public fields</li> <li>Protected fields of classes that are <a href="#Stable_to_extend">stable to extend</a></li></ul> <p>Not included: </p> <ul><li>write access</li> <li>any field marked as <code>@deprecated</code>, <code>@internal</code> or <code>@unstable</code></li></ul> <p>For authors: </p> <ul><li>Public fields should generally be avoided in favor of getters and setters.</li> <li>Base classes should generally not expect subclasses to modify protected fields directly. If this is desired, it must be explicitly documented.</li> <li>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.</li></ul> <div class="mw-heading mw-heading3"><h3 id="Stable_to_implement" data-mw-thread-id="h-Stable_to_implement-Definition_of_the_stable_interface"><span data-mw-comment-start="" id="h-Stable_to_implement-Definition_of_the_stable_interface"></span>Stable to implement<span data-mw-comment-end="h-Stable_to_implement-Definition_of_the_stable_interface"></span></h3><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/w/index.php?title=Stable_interface_policy&action=edit&section=11" title="Edit section: Stable to implement"><span>edit</span></a><span class="mw-editsection-bracket">]</span></span></div> <link rel="mw-deduplicated-inline-style" href="mw-data:TemplateStyles:r6651107"><div role="note" class="note note-warn">It's generally <b>not stable to implement interfaces</b> – unless these are marked <code>@stable to implement</code>. This means existing signatures may change and new required methods may be added without notice.</div> <p><i>Stable to implement</i> 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 <a href="#Deprecation_process">deprecation process</a>. </p><p>Included: </p> <ul><li>Only interfaces that are marked <code>@stable to implement</code>.</li></ul> <p>For authors: </p> <ul><li>Do not add methods to interfaces marked as <code>@stable to implement</code>.</li> <li>Do not break method signatures in interfaces that are <code>@stable to implement</code>.</li> <li>Any <a href="/wiki/Manual:Hooks" title="Manual:Hooks">hook interface</a> that is documented (and not deprecated) should be marked <code>@stable to implement</code>.</li> <li>Avoid using interfaces as extension points other than hook interfaces. It is recommended to use an abstract base class instead. See <a href="#Stable_to_extend">Stable to extend</a>.</li></ul> <div class="mw-heading mw-heading3"><h3 id="Stable_to_override" data-mw-thread-id="h-Stable_to_override-Definition_of_the_stable_interface"><span data-mw-comment-start="" id="h-Stable_to_override-Definition_of_the_stable_interface"></span>Stable to override<span data-mw-comment-end="h-Stable_to_override-Definition_of_the_stable_interface"></span></h3><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/w/index.php?title=Stable_interface_policy&action=edit&section=12" title="Edit section: Stable to override"><span>edit</span></a><span class="mw-editsection-bracket">]</span></span></div> <link rel="mw-deduplicated-inline-style" href="mw-data:TemplateStyles:r6651107"><div role="note" class="note note-warn">It's generally <b>not stable to override methods in subclasses</b> unless the method is marked <code>@stable to override</code>.</div> <p><i>Stable to override</i> can apply to class methods and <a href="/wiki/Manual:Hooks" title="Manual:Hooks">hooks</a>. 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 <a href="#Deprecation_process">deprecation process</a>. </p><p>Included: </p> <ul><li>Any <a href="/wiki/Manual:Hooks" title="Manual:Hooks">hook</a> 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 <a href="/wiki/Manual:Hooks#Handling_hooks_in_MediaWiki_1.35_and_later" title="Manual:Hooks">implement hook interfaces</a>, rather than registering hook callbacks.</li></ul> <ul><li>Methods that are declared as <code>abstract</code> in classes that are <a href="#Stable_to_extend">stable to extend</a>.</li> <li>Any method marked <code>@stable to override</code>.</li></ul> <p>Not included: </p> <ul><li>Any method marked <code>@deprecated</code>, <code>@internal</code> or <code>@unstable</code>.</li></ul> <p>For authors: </p><p>When hard deprecating code that is stable to override, </p> <ul><li>a deprecation warning SHOULD be triggered in case the method is overridden by a subclass, typically using <code>MWDebug::detectDeprecatedOverride</code>.</li> <li>the method MUST still be called if it is overridden.</li></ul> <div class="mw-heading mw-heading3"><h3 id="Global_variables" data-mw-thread-id="h-Global_variables-Definition_of_the_stable_interface"><span data-mw-comment-start="" id="h-Global_variables-Definition_of_the_stable_interface"></span>Global variables<span data-mw-comment-end="h-Global_variables-Definition_of_the_stable_interface"></span></h3><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/w/index.php?title=Stable_interface_policy&action=edit&section=13" title="Edit section: Global variables"><span>edit</span></a><span class="mw-editsection-bracket">]</span></span></div> <link rel="mw-deduplicated-inline-style" href="mw-data:TemplateStyles:r6651107"><div role="note" class="note note-warn">It's <b>not stable to use global variables</b>.</div> <p>Global variables are not stable, not even those with the "wg" prefix. </p><p>For users: </p> <ul><li>To access site configuration, use <code class="mw-highlight mw-highlight-lang-php mw-content-ltr" style="" dir="ltr"><span class="nx">MediaWikiServices</span><span class="o">::</span><span class="na">getMainConfig</span><span class="p">()</span></code> instead.</li> <li>To access service objects, use <code class="mw-highlight mw-highlight-lang-php mw-content-ltr" style="" dir="ltr"><span class="nx">MediaWikiServices</span><span class="o">::</span><span class="na">get</span><span class="o">*</span></code> methods instead.</li></ul> <p>For authors: </p> <ul><li>When access to global state cannot be avoided, static methods SHOULD be used.</li></ul> <div class="mw-heading mw-heading2 ext-discussiontools-init-section"><h2 id="Stability_annotations" data-mw-thread-id="h-Stability_annotations"><span data-mw-comment-start="" id="h-Stability_annotations"></span>Stability annotations<span data-mw-comment-end="h-Stability_annotations"></span></h2><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/w/index.php?title=Stable_interface_policy&action=edit&section=14" title="Edit section: Stability annotations"><span>edit</span></a><span class="mw-editsection-bracket">]</span></span></div> <div class="mw-heading mw-heading3"><h3 id="Add_guarantees" data-mw-thread-id="h-Add_guarantees-Stability_annotations"><span data-mw-comment-start="" id="h-Add_guarantees-Stability_annotations"></span>Add guarantees<span data-mw-comment-end="h-Add_guarantees-Stability_annotations"></span></h3><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/w/index.php?title=Stable_interface_policy&action=edit&section=15" title="Edit section: Add guarantees"><span>edit</span></a><span class="mw-editsection-bracket">]</span></span></div> <ul><li><code>@stable to call</code>: See <a href="#Stable_to_call">Stable to call</a>.</li> <li><code>@stable to type</code>: See <a href="#Stable_to_type">Stable to type</a>.</li> <li><code>@stable to extend</code>: See <a href="#Stable_to_extend">Stable to extend</a>.</li> <li><code>@stable to implement</code>: See <a href="#Stable_to_extend">Stable to implement</a></li> <li><code>@stable to override</code>: See <a href="#Stable_to_override">Stable to override</a>.</li> <li><code>@newable</code>: See <a href="#Stable_to_call">Stable to call</a>.</li></ul><p> The <code>@stable</code> annotations can be followed by a <code>Since</code> segment to indicate that a particular use of the class or method is only supported since a specific version. For example:</p><div class="mw-highlight mw-highlight-lang-php mw-content-ltr" dir="ltr"><pre><span></span><span class="sd">/**</span> <span class="sd"> * @since 1.17</span> <span class="sd"> * @stable to extend Since 1.35</span> <span class="sd"> */</span> <span class="k">class</span> <span class="nc">Foo</span> <span class="p">{</span> <span class="cm">/* … */</span> <span class="p">}</span> </pre></div><p>The <code>@stable</code> annotations can be followed by a <code>Deprecated since</code> 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. </p><div class="mw-highlight mw-highlight-lang-php mw-content-ltr" dir="ltr"><pre><span></span><span class="sd">/**</span> <span class="sd"> * @stable to extend Deprecated since 1.35</span> <span class="sd"> */</span> <span class="k">class</span> <span class="nc">Foo</span> <span class="p">{</span> <span class="cm">/* … */</span> <span class="p">}</span> </pre></div> <div class="mw-heading mw-heading3"><h3 id="Remove_guarantees" data-mw-thread-id="h-Remove_guarantees-Stability_annotations"><span data-mw-comment-start="" id="h-Remove_guarantees-Stability_annotations"></span>Remove guarantees<span data-mw-comment-end="h-Remove_guarantees-Stability_annotations"></span></h3><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/w/index.php?title=Stable_interface_policy&action=edit&section=16" title="Edit section: Remove guarantees"><span>edit</span></a><span class="mw-editsection-bracket">]</span></span></div> <ul><li><code>@internal</code>: Do not use outside the original module. It may change without notice.</li> <li><code>@unstable</code>: It may change without notice. Similar to <code>@internal</code>, except that unstable things are aimed at external use and intended to become stable in the future.</li> <li><code>@deprecated</code>: This means something should not be used anywhere, as this may be removed in a future release, per the <a href="#Deprecation_Process">deprecation process</a>. This must include a <code>since</code> segment, and must include instructions for what to use instead (or state that there is no alternative). For example:</li></ul> <div class="mw-highlight mw-highlight-lang-php mw-content-ltr" dir="ltr"><pre><span></span><span class="sd">/**</span> <span class="sd"> * @deprecated Since 1.35, use expandFoo() instead.</span> <span class="sd"> */</span> <span class="k">public</span> <span class="k">function</span> <span class="nf">getSomething</span><span class="p">(</span> <span class="nx">Foo</span> <span class="nv">$foo</span> <span class="p">);</span> </pre></div> <p><span class="anchor" id="Deprecation_policy"></span> </p> <div class="mw-heading mw-heading2 ext-discussiontools-init-section"><h2 id="Deprecation_process" data-mw-thread-id="h-Deprecation_process"><span data-mw-comment-start="" id="h-Deprecation_process"></span>Deprecation process<span data-mw-comment-end="h-Deprecation_process"></span></h2><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/w/index.php?title=Stable_interface_policy&action=edit&section=17" title="Edit section: Deprecation process"><span>edit</span></a><span class="mw-editsection-bracket">]</span></span></div> <p>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 <a href="#Scope">scope</a> of this policy and defines a <a href="#Definition_of_the_stable_interface">stable interface</a> is subject to the deprecation process defined here. </p><p>The deprecation process generally consists of the following steps, described in more detail below: </p> <ol><li><b>soft deprecation</b>, immediately followed by updating any code using the deprecated functionality.</li> <li><b>hard deprecation</b>, as soon as the deprecated code appears to be unused, ideally within the same release as soft deprecation.</li> <li><b>removal</b> of the deprecated code, after at least one release branch has been cut and at least three months have passed.</li></ol> <p>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. </p><p>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. <a href="//wikiapiary.com/wiki/Extension:Extensions" class="extiw" title="wikiapiary:Extension:Extensions">WikiApiary.com</a> and <a class="external text" href="https://grafana.wikimedia.org/d/000000161/extension-distributor-downloads">ExtensionDistributor</a> can be used as indicators for an extension's relevance. </p><p>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. </p> <div class="mw-heading mw-heading3"><h3 id="Soft_deprecation" data-mw-thread-id="h-Soft_deprecation-Deprecation_process"><span data-mw-comment-start="" id="h-Soft_deprecation-Deprecation_process"></span>Soft deprecation<span data-mw-comment-end="h-Soft_deprecation-Deprecation_process"></span></h3><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/w/index.php?title=Stable_interface_policy&action=edit&section=18" title="Edit section: Soft deprecation"><span>edit</span></a><span class="mw-editsection-bracket">]</span></span></div> <p>Soft deprecation occurs when a developer adds a <code>@deprecated</code> annotation to the documentation comment of a method, function, class, or interface. </p><p>The following rules apply to soft deprecation: </p> <ul><li>The documentation comment MUST mention what the alternative method or migration path is. If there is no alternative, it should state that.</li> <li>The documentation comment MUST state what MediaWiki core version the deprecation occurred in.</li> <li>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.</li> <li>Any relevant documentation in the Git repository and on mediawiki.org MUST be updated once the change is approved. (Using alert templates on the documentation page, such as <style data-mw-deduplicate="TemplateStyles:r4719022">.mw-parser-output .monospaced{font-family:monospace,monospace}</style><span class="monospaced">{{<a href="/wiki/Template:Deprecated" title="Template:Deprecated">Deprecated</a>}}</span>).</li> <li>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 <a href="/wiki/Manual:Hooks" title="Manual:Hooks">Manual:Hooks</a> page.</li> <li>Developers or teams deprecating code SHOULD remove usages in Wikimedia maintained code as soon as possible.</li> <li>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.</li> <li>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.</li> <li>If the deprecated code is unused in Wikimedia maintained code at the time of deprecation, it SHOULD be hard deprecated immediately.</li></ul> <p><span class="anchor" id="Changes_without_deprecation"></span> </p> <div class="mw-heading mw-heading3"><h3 id="Hard_deprecation" data-mw-thread-id="h-Hard_deprecation-Deprecation_process"><span data-mw-comment-start="" id="h-Hard_deprecation-Deprecation_process"></span>Hard deprecation<span data-mw-comment-end="h-Hard_deprecation-Deprecation_process"></span></h3><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/w/index.php?title=Stable_interface_policy&action=edit&section=19" title="Edit section: Hard deprecation"><span>edit</span></a><span class="mw-editsection-bracket">]</span></span></div> <p>Hard deprecation occurs when the code starts emitting deprecation warnings, typically by calling <code>wfDeprecated( __METHOD__, '1.xx' );</code>. Deprecation warnings cause unit tests to fail. </p><p>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 <code>@warning</code> 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 <code>@internal</code>. </p><p>The following rules apply to hard deprecation: </p> <ul><li>Code that is hard deprecated MUST also be soft deprecated.</li> <li>The version number in the <code>wfDeprecated()</code> call MUST match the one in the <code>@deprecated</code> annotation, even if the hard deprecation occurs in a different release.</li> <li>Any soft deprecated code SHOULD be hard deprecated as soon as it is no longer used in any Wikimedia maintained code.</li> <li>Hard deprecated code MAY act as no-ops instead of actually functioning, though this is not recommended.</li> <li>Hard deprecation MUST NOT be applied to code still used in Wikimedia maintained code. Such usage MUST be removed first.</li></ul> <ul><li>Deprecation with far-reaching impact SHOULD be announced by email to wikitech-l or mediawiki-l.</li></ul> <div class="mw-heading mw-heading3"><h3 id="Removal" data-mw-thread-id="h-Removal-Deprecation_process"><span data-mw-comment-start="" id="h-Removal-Deprecation_process"></span>Removal<span data-mw-comment-end="h-Removal-Deprecation_process"></span></h3><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/w/index.php?title=Stable_interface_policy&action=edit&section=20" title="Edit section: Removal"><span>edit</span></a><span class="mw-editsection-bracket">]</span></span></div> <p>The following rules apply to the removal of code: </p> <ul><li>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 <i>hard deprecation</i> section.</li> <li>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.</li> <li>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.</li> <li>All removals of code that falls under the stable interface policy MUST be mentioned in the relevant RELEASE-NOTES file.</li> <li>Removals that may have a severe impact SHOULD be mentioned in the "Upgrade notices for MediaWiki administrators" section of the wiki release page.</li> <li>As one of the <a href="/wiki/Principles" title="Principles">principles</a> 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.</li></ul> <div class="mw-heading mw-heading3"><h3 id="Further_guidance" data-mw-thread-id="h-Further_guidance-Deprecation_process"><span data-mw-comment-start="" id="h-Further_guidance-Deprecation_process"></span>Further guidance<span data-mw-comment-end="h-Further_guidance-Deprecation_process"></span></h3><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/w/index.php?title=Stable_interface_policy&action=edit&section=21" title="Edit section: Further guidance"><span>edit</span></a><span class="mw-editsection-bracket">]</span></span></div> <ul><li>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.</li> <li>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.</li> <li>Developers SHOULD consider the impact of their proposed changes by searching for existing usage in extensions using tools such <a href="/wiki/Codesearch" title="Codesearch">Codesearch</a> .</li> <li>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.</li> <li>Deprecations and removals MUST first take place on the master branch. Deprecations and removals SHOULD NOT be backported to release branches or release candidates.</li> <li>Developers SHOULD deprecate related parts of code together so affected code can be updated all at once.</li> <li>When a task is related to a deprecation, it is RECOMMENDED to tag it specifically in the bug tracker; for instance with the <a href="https://phabricator.wikimedia.org/project/view/3473/" class="extiw" title="phab:project/view/3473/">"Deprecation process" tag</a> in Phabricator.</li></ul> <p>And finally: As with all policies, developers should apply their best judgement when applying it. </p> <div class="mw-heading mw-heading2 ext-discussiontools-init-section"><h2 id="Meta" data-mw-thread-id="h-Meta"><span data-mw-comment-start="" id="h-Meta"></span>Meta<span data-mw-comment-end="h-Meta"></span></h2><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/w/index.php?title=Stable_interface_policy&action=edit&section=22" title="Edit section: Meta"><span>edit</span></a><span class="mw-editsection-bracket">]</span></span></div> <div class="mw-heading mw-heading3"><h3 id="Motivation" data-mw-thread-id="h-Motivation-Meta"><span data-mw-comment-start="" id="h-Motivation-Meta"></span>Motivation<span data-mw-comment-end="h-Motivation-Meta"></span></h3><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/w/index.php?title=Stable_interface_policy&action=edit&section=23" title="Edit section: Motivation"><span>edit</span></a><span class="mw-editsection-bracket">]</span></span></div> <p>The motivation for this policy is two-fold: </p> <ul><li>Offer guarantees to extension developers, providing guidance on what aspects of MediaWiki core they can safely rely upon.</li> <li>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.</li></ul> <p>This policy is designed to make extensions more robust against changes in MediaWiki core, and provide more freedom for MediaWiki core code to evolve. </p> <div class="mw-heading mw-heading3"><h3 id="Scope" data-mw-thread-id="h-Scope-Meta"><span data-mw-comment-start="" id="h-Scope-Meta"></span>Scope<span data-mw-comment-end="h-Scope-Meta"></span></h3><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/w/index.php?title=Stable_interface_policy&action=edit&section=24" title="Edit section: Scope"><span>edit</span></a><span class="mw-editsection-bracket">]</span></span></div> <p>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: </p> <ul><li>PHP code of MediaWiki core (mediawiki/core.git) as published in official releases.</li> <li>Libraries maintained by Wikimedia, inside the core repository or in separate repositories, as published in official releases.</li> <li>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.</li> <li>Code in a repository in the MediaWiki ecosystem if and only if it explicitly opts into this policy.</li></ul> <p>This policy does <i>not</i> apply to the following: </p> <ul><li>Any unreleased code, in particular code as it is on the master or a development branch of the repository.</li> <li>Web APIs such as <a href="/wiki/Api.php" class="mw-redirect" title="Api.php">api.php</a> or <a href="/wiki/API:REST_API" title="API:REST API">rest.php</a>.</li> <li>client-side JavaScript</li> <li>The structure of HTML output from index.php and other endpoints</li> <li>The structure of <a href="/wiki/SQL/XML_Dumps" title="SQL/XML Dumps">dumps</a> or exports</li> <li>The <a href="/wiki/Manual:Database_layout" title="Manual:Database layout">database schema</a>.</li></ul> <p>Those may have their own policies and practices for maintaining stable interfaces. </p> <div class="mw-heading mw-heading3"><h3 id="Ecosystem" data-mw-thread-id="h-Ecosystem-Meta"><span data-mw-comment-start="" id="h-Ecosystem-Meta"></span>Ecosystem<span data-mw-comment-end="h-Ecosystem-Meta"></span></h3><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/w/index.php?title=Stable_interface_policy&action=edit&section=25" title="Edit section: Ecosystem"><span>edit</span></a><span class="mw-editsection-bracket">]</span></span></div> <p>Providing a stable interface enables a community of third parties to create and maintain components, forming a "<a href="https://en.wikipedia.org/wiki/Software_ecosystem" class="extiw" title="en:Software ecosystem">software ecosystem</a>". For the purpose of this policy, the <i>MediaWiki ecosystem</i> is thought to consist of extensions actively maintained by entities other than the Wikimedia Foundation, if they meet all of the following criteria: </p> <ul><li>the extension is <a href="https://en.wikipedia.org/wiki/Free_software" class="extiw" title="en:Free software">free software</a></li> <li>the extension has a page on mediawiki.org, using the <a href="/wiki/Template:Extension" title="Template:Extension">Extension template</a> to make it discoverable.</li> <li>the extension is maintained either in a repository hosted by the Wikimedia Foundation, or is <a rel="nofollow" class="external text" href="https://github.com/MWStake/nonwmf-extensions">listed as a non-wikimedia extension</a> by the <a href="/wiki/MediaWiki_Stakeholders%27_Group" title="MediaWiki Stakeholders' Group">MediaWiki Stakeholders' Group</a>.</li></ul> <p>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 <a rel="nofollow" class="external text" href="https://codesearch.wmcloud.org">codesearch</a> tool. </p> <div class="mw-heading mw-heading3"><h3 id="History" data-mw-thread-id="h-History-Meta"><span data-mw-comment-start="" id="h-History-Meta"></span>History<span data-mw-comment-end="h-History-Meta"></span></h3><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/w/index.php?title=Stable_interface_policy&action=edit&section=26" title="Edit section: History"><span>edit</span></a><span class="mw-editsection-bracket">]</span></span></div> <ul><li>This policy was established in January 2017 with RFC <a href="https://phabricator.wikimedia.org/T146965" class="extiw" title="phab:T146965">T146965</a> (effective since <a href="/wiki/MediaWiki_1.29" title="MediaWiki 1.29">MediaWiki 1.29</a>), and superseded the guideline archived at <a href="/wiki/Deprecation_policy/Until_2017" title="Deprecation policy/Until 2017">Deprecation policy/Until 2017</a>.</li> <li>This policy was amended in March 2020 with RFC <a href="https://phabricator.wikimedia.org/T193613" class="extiw" title="phab:T193613">T193613</a> , and in June 2020 with RFC <a href="https://phabricator.wikimedia.org/T255803" class="extiw" title="phab:T255803">T255803</a> (effective since <a href="/wiki/MediaWiki_1.35" title="MediaWiki 1.35">MediaWiki 1.35</a>). The policy for MediaWiki 1.34 and earlier can be found at <i><a class="external text" href="https://www.mediawiki.org/w/index.php?title=Stable_interface_policy&oldid=4155520#Stable_interface_up_to_MediaWiki_1.34">Stable interfaces up to MediaWiki 1.34</a></i> .</li> <li>This policy was amended in January 2021 with RFC <a href="https://phabricator.wikimedia.org/T268326" class="extiw" title="phab:T268326">T268326</a> (effective since <a href="/wiki/MediaWiki_1.36" title="MediaWiki 1.36">MediaWiki 1.36</a>).</li></ul> <div class="mw-heading mw-heading2 ext-discussiontools-init-section"><h2 id="Frontend_policy" data-mw-thread-id="h-Frontend_policy"><span data-mw-comment-start="" id="h-Frontend_policy"></span>Frontend policy<span data-mw-comment-end="h-Frontend_policy"></span></h2><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/w/index.php?title=Stable_interface_policy&action=edit&section=27" title="Edit section: Frontend policy"><span>edit</span></a><span class="mw-editsection-bracket">]</span></span></div><p> There is also a separate <a href="/wiki/Stable_interface_policy/Frontend" title="Stable interface policy/Frontend">Stable interface policy/Frontend</a> policy that defines what parts of the software are considered stable and safe for use by browser-based code from other components.</p><div class="navbox-styles nomobile"><style data-mw-deduplicate="TemplateStyles:r6230902">.mw-parser-output .navbox{border:1px solid #aaa;box-sizing:border-box;width:100%;margin:auto;clear:both;font-size:88%;text-align:center;padding:1px}.mw-parser-output .navbox-inner,.mw-parser-output .navbox-subgroup{width:100%}.mw-parser-output .navbox+.navbox-styles+.navbox{margin-top:-1px}.mw-parser-output .navbox th,.mw-parser-output .navbox-title,.mw-parser-output .navbox-abovebelow{text-align:center;padding-left:1em;padding-right:1em}.mw-parser-output th.navbox-group{white-space:nowrap;text-align:right}.mw-parser-output .navbox,.mw-parser-output .navbox-subgroup{background:#fdfdfd}.mw-parser-output .navbox-list{border-color:#fdfdfd}.mw-parser-output .navbox th,.mw-parser-output .navbox-title{background:#eaeeff}.mw-parser-output .navbox-abovebelow,.mw-parser-output th.navbox-group,.mw-parser-output .navbox-subgroup .navbox-title{background:#ddddff}.mw-parser-output .navbox-subgroup .navbox-group,.mw-parser-output .navbox-subgroup .navbox-abovebelow{background:#e6e6ff}.mw-parser-output .navbox-even{background:#f7f7f7}.mw-parser-output .navbox-odd{background:transparent}.mw-parser-output th.navbox-title1{border-left:2px solid #fdfdfd;width:100%}.mw-parser-output td.navbox-list1{text-align:left;border-left-width:2px;border-left-style:solid}.mw-parser-output .navbox .hlist td dl,.mw-parser-output .navbox .hlist td ol,.mw-parser-output .navbox .hlist td ul,.mw-parser-output .navbox td.hlist dl,.mw-parser-output .navbox td.hlist ol,.mw-parser-output .navbox td.hlist ul{padding:0.125em 0}.mw-parser-output .navbox .hlist dd,.mw-parser-output .navbox .hlist dt,.mw-parser-output .navbox .hlist li{white-space:nowrap}.mw-parser-output .navbox .hlist dd dl,.mw-parser-output .navbox .hlist dt dl,.mw-parser-output .navbox .hlist li ol,.mw-parser-output .navbox .hlist li ul{white-space:normal}.mw-parser-output ol+.navbox-styles+.navbox,.mw-parser-output ul+.navbox-styles+.navbox{margin-top:0.5em}</style></div><div role="navigation" class="navbox" aria-labelledby="Development_guidelines" style="border: 1px solid #aaa; padding: 3px;;padding:3px"><table class="nowraplinks hlist navbox-inner" style="border-spacing:0;background:transparent;color:inherit"><tbody><tr><th scope="col" class="navbox-title" colspan="2"><style data-mw-deduplicate="TemplateStyles:r6387430">.mw-parser-output .hlist dl,.mw-parser-output .hlist ol,.mw-parser-output .hlist ul{margin:0;padding:0}.mw-parser-output .hlist dd,.mw-parser-output .hlist dt,.mw-parser-output .hlist li{margin:0;display:inline}.mw-parser-output .hlist dl dl,.mw-parser-output .hlist dl ol,.mw-parser-output .hlist dl ul,.mw-parser-output .hlist ol dl,.mw-parser-output .hlist ol ol,.mw-parser-output .hlist ol ul,.mw-parser-output .hlist ul dl,.mw-parser-output .hlist ul ol,.mw-parser-output .hlist ul ul{display:inline}.mw-parser-output .hlist .mw-empty-li,.mw-parser-output .hlist .mw-empty-elt{display:none}.mw-parser-output .hlist dt:after{content:": "}.mw-parser-output .hlist dd:after,.mw-parser-output .hlist li:after{content:" · ";font-weight:bold}.mw-parser-output .hlist dd:last-child:after,.mw-parser-output .hlist dt:last-child:after,.mw-parser-output .hlist li:last-child:after{content:none}.mw-parser-output .hlist dd dd:first-child:before,.mw-parser-output .hlist dd dt:first-child:before,.mw-parser-output .hlist dd li:first-child:before,.mw-parser-output .hlist dt dd:first-child:before,.mw-parser-output .hlist dt dt:first-child:before,.mw-parser-output .hlist dt li:first-child:before,.mw-parser-output .hlist li dd:first-child:before,.mw-parser-output .hlist li dt:first-child:before,.mw-parser-output .hlist li li:first-child:before{content:" (";font-weight:normal}.mw-parser-output .hlist dd dd:last-child:after,.mw-parser-output .hlist dd dt:last-child:after,.mw-parser-output .hlist dd li:last-child:after,.mw-parser-output .hlist dt dd:last-child:after,.mw-parser-output .hlist dt dt:last-child:after,.mw-parser-output .hlist dt li:last-child:after,.mw-parser-output .hlist li dd:last-child:after,.mw-parser-output .hlist li dt:last-child:after,.mw-parser-output .hlist li li:last-child:after{content:")";font-weight:normal}.mw-parser-output .hlist ol{counter-reset:listitem}.mw-parser-output .hlist ol>li{counter-increment:listitem}.mw-parser-output .hlist ol>li:before{content:" "counter(listitem)"\a0 "}.mw-parser-output .hlist dd ol>li:first-child:before,.mw-parser-output .hlist dt ol>li:first-child:before,.mw-parser-output .hlist li ol>li:first-child:before{content:" ("counter(listitem)"\a0 "}</style><link rel="mw-deduplicated-inline-style" href="mw-data:TemplateStyles:r4692751"><div class="plainlinks hlist navbar mini"><ul><li class="nv-view"><a href="/wiki/Template:Development_guidelines_navigation" title="Template:Development guidelines navigation"><abbr title="View this template" style=";;background:none transparent;border:none;box-shadow:none; padding:0;">v</abbr></a></li><li class="nv-talk"><a href="/wiki/Template_talk:Development_guidelines_navigation" title="Template talk:Development guidelines navigation"><abbr title="Discuss this template" style=";;background:none transparent;border:none;box-shadow:none; padding:0;">t</abbr></a></li><li class="nv-edit"><a class="external text" href="https://www.mediawiki.org/w/index.php?title=Template:Development_guidelines_navigation&action=edit"><abbr title="Edit this template" style=";;background:none transparent;border:none;box-shadow:none; padding:0;">e</abbr></a></li></ul></div><div id="Development_guidelines" style="font-size:114%;margin:0 4em"><a href="/wiki/Special:MyLanguage/Development_guidelines" title="Special:MyLanguage/Development guidelines"><span style="font-weight: bold;">Development guidelines</span></a><span style="display:none"><a href="/wiki/Development_guidelines" title="Development guidelines"> </a></span></div></th></tr><tr><th scope="row" class="navbox-group" style="width:1%">Policies</th><td class="navbox-list1 navbox-list navbox-odd" style="width:100%;padding:0px"><div style="padding:0em 0.25em"> <ul><li><a href="/wiki/Special:MyLanguage/Development_policy" title="Special:MyLanguage/Development policy">Development policy</a><span style="display:none"><a href="/wiki/Development_policy" title="Development policy"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/Wikimedia_Engineering_Architecture_Principles" title="Special:MyLanguage/Wikimedia Engineering Architecture Principles">Architecture principles</a><span style="display:none"><a href="/wiki/Wikimedia_Engineering_Architecture_Principles" title="Wikimedia Engineering Architecture Principles"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/Wikimedia_services_policy" title="Special:MyLanguage/Wikimedia services policy">Services policy</a><span style="display:none"><a href="/wiki/Wikimedia_services_policy" title="Wikimedia services policy"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/Support_policy_for_PHP" title="Special:MyLanguage/Support policy for PHP">Support policy for PHP</a><span style="display:none"><a href="/wiki/Support_policy_for_PHP" title="Support policy for PHP"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/Gerrit/Privilege_policy" title="Special:MyLanguage/Gerrit/Privilege policy">Gerrit/Privilege policy</a><span style="display:none"><a href="/wiki/Gerrit/Privilege_policy" title="Gerrit/Privilege policy"> </a></span></li> <li><b><a href="/wiki/Special:MyLanguage/Stable_interface_policy" title="Special:MyLanguage/Stable interface policy">Stable interface policy</a></b><span style="display:none"><a class="mw-selflink selflink"> </a></span> <ul><li><a href="/wiki/Special:MyLanguage/Stable_interface_policy/Frontend" title="Special:MyLanguage/Stable interface policy/Frontend">Frontend</a><span style="display:none"><a href="/wiki/Stable_interface_policy/Frontend" title="Stable interface policy/Frontend"> </a></span></li></ul></li> <li><a href="/wiki/Special:MyLanguage/MediaWiki_database_policy" title="Special:MyLanguage/MediaWiki database policy">MediaWiki database policy</a><span style="display:none"><a href="/wiki/MediaWiki_database_policy" title="MediaWiki database policy"> </a></span></li></ul> </div></td></tr><tr><th scope="row" class="navbox-group" style="width:1%">General guidelines</th><td class="navbox-list1 navbox-list navbox-even" style="width:100%;padding:0px"><div style="padding:0em 0.25em"> <ul><li><a href="/wiki/Special:MyLanguage/Security_for_developers" title="Special:MyLanguage/Security for developers">Security for developers</a><span style="display:none"><a href="/wiki/Security_for_developers" title="Security for developers"> </a></span></li> <li><a href="https://wikitech.wikimedia.org/wiki/Performance/Guides/Backend_performance_practices" class="extiw" title="wikitech:Performance/Guides/Backend performance practices">Performance guidelines</a></li> <li><a href="/wiki/Special:MyLanguage/Gerrit/Commit_message_guidelines" title="Special:MyLanguage/Gerrit/Commit message guidelines">Commit message guidelines</a><span style="display:none"><a href="/wiki/Gerrit/Commit_message_guidelines" title="Gerrit/Commit message guidelines"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/Security_checklist_for_developers" title="Special:MyLanguage/Security checklist for developers">Security checklist for developers</a><span style="display:none"><a href="/wiki/Security_checklist_for_developers" title="Security checklist for developers"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/Localisation" title="Special:MyLanguage/Localisation">Localisation</a><span style="display:none"><a href="/wiki/Localisation" title="Localisation"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/Design/Living_style_guide" title="Special:MyLanguage/Design/Living style guide">Design style guide</a><span style="display:none"><a href="/wiki/Design/Living_style_guide" title="Design/Living style guide"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/Documentation/Style_guide" title="Special:MyLanguage/Documentation/Style guide">Documentation/Style guide</a><span style="display:none"><a href="/wiki/Documentation/Style_guide" title="Documentation/Style guide"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/Accessibility_guide_for_developers" title="Special:MyLanguage/Accessibility guide for developers">Accessibility guide for developers</a><span style="display:none"><a href="/wiki/Accessibility_guide_for_developers" title="Accessibility guide for developers"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/Inclusive_language" title="Special:MyLanguage/Inclusive language">Inclusive language</a><span style="display:none"><a href="/wiki/Inclusive_language" title="Inclusive language"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/Guidelines_for_a_healthy_code_review_culture" title="Special:MyLanguage/Guidelines for a healthy code review culture">Guidelines for a healthy code review culture</a><span style="display:none"><a href="/wiki/Guidelines_for_a_healthy_code_review_culture" title="Guidelines for a healthy code review culture"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/Collaborative_programming" title="Special:MyLanguage/Collaborative programming">Collaborative programming</a><span style="display:none"><a href="/wiki/Collaborative_programming" title="Collaborative programming"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/Best_practices_for_extensions" title="Special:MyLanguage/Best practices for extensions">Best practices for extensions</a><span style="display:none"><a href="/wiki/Best_practices_for_extensions" title="Best practices for extensions"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/Manual:Pre-commit_checklist" title="Special:MyLanguage/Manual:Pre-commit checklist">Pre-commit checklist</a><span style="display:none"><a href="/wiki/Manual:Pre-commit_checklist" title="Manual:Pre-commit checklist"> </a></span></li></ul> </div></td></tr><tr><th scope="row" class="navbox-group" style="width:1%">Code conventions</th><td class="navbox-list1 navbox-list navbox-odd" style="width:100%;padding:0px"><div style="padding:0em 0.25em"> <ul><li><a href="/wiki/Special:MyLanguage/Manual:Coding_conventions#Code_structure" title="Special:MyLanguage/Manual:Coding conventions">All languages</a><span style="display:none"><a href="/wiki/Manual:Coding_conventions#Code_structure" title="Manual:Coding conventions"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/Manual:Coding_conventions/PHP" title="Special:MyLanguage/Manual:Coding conventions/PHP">PHP</a><span style="display:none"><a href="/wiki/Manual:Coding_conventions/PHP" title="Manual:Coding conventions/PHP"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/Manual:PHP_unit_testing/Writing_unit_tests#Test_conventions" title="Special:MyLanguage/Manual:PHP unit testing/Writing unit tests">PHPUnit</a><span style="display:none"><a href="/wiki/Manual:PHP_unit_testing/Writing_unit_tests#Test_conventions" title="Manual:PHP unit testing/Writing unit tests"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/Manual:Coding_conventions/JavaScript" title="Special:MyLanguage/Manual:Coding conventions/JavaScript">JavaScript</a><span style="display:none"><a href="/wiki/Manual:Coding_conventions/JavaScript" title="Manual:Coding conventions/JavaScript"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/Manual:Coding_conventions/CSS" title="Special:MyLanguage/Manual:Coding conventions/CSS">CSS</a><span style="display:none"><a href="/wiki/Manual:Coding_conventions/CSS" title="Manual:Coding conventions/CSS"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/Manual:Coding_conventions/Selenium" title="Special:MyLanguage/Manual:Coding conventions/Selenium">Selenium</a><span style="display:none"><a href="/wiki/Manual:Coding_conventions/Selenium" title="Manual:Coding conventions/Selenium"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/Manual:Coding_conventions/Lua" title="Special:MyLanguage/Manual:Coding conventions/Lua">Lua</a><span style="display:none"><a href="/wiki/Manual:Coding_conventions/Lua" title="Manual:Coding conventions/Lua"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/Manual:Coding_conventions/Python" title="Special:MyLanguage/Manual:Coding conventions/Python">Python</a><span style="display:none"><a href="/wiki/Manual:Coding_conventions/Python" title="Manual:Coding conventions/Python"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/Manual:Coding_conventions/Java" title="Special:MyLanguage/Manual:Coding conventions/Java">Java</a><span style="display:none"><a href="/wiki/Manual:Coding_conventions/Java" title="Manual:Coding conventions/Java"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/Manual:Coding_conventions/SVG" title="Special:MyLanguage/Manual:Coding conventions/SVG">SVG</a><span style="display:none"><a href="/wiki/Manual:Coding_conventions/SVG" title="Manual:Coding conventions/SVG"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/Manual:Coding_conventions/Vue" title="Special:MyLanguage/Manual:Coding conventions/Vue">Vue</a><span style="display:none"><a href="/wiki/Manual:Coding_conventions/Vue" title="Manual:Coding conventions/Vue"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/Manual:Coding_conventions/Database" title="Special:MyLanguage/Manual:Coding conventions/Database">Database schemas</a><span style="display:none"><a href="/wiki/Manual:Coding_conventions/Database" title="Manual:Coding conventions/Database"> </a></span></li> <li><a href="/wiki/Special:MyLanguage/Product_Analytics/Style_guide" title="Special:MyLanguage/Product Analytics/Style guide">Analytics (Python, R, SQL)</a><span style="display:none"><a href="/wiki/Product_Analytics/Style_guide" title="Product Analytics/Style guide"> </a></span></li></ul> </div></td></tr><tr><th scope="row" class="navbox-group" style="width:1%">API client code</th><td class="navbox-list1 navbox-list navbox-even" style="width:100%;padding:0px"><div style="padding:0em 0.25em"> <ul><li><a href="/wiki/Special:MyLanguage/API:Client_code/Gold_standard" title="Special:MyLanguage/API:Client code/Gold standard">Standards for API client libraries</a><span style="display:none"><a href="/wiki/API:Client_code/Gold_standard" title="API:Client code/Gold standard"> </a></span></li></ul> </div></td></tr><tr><th scope="row" class="navbox-group" style="width:1%">Drafts</th><td class="navbox-list1 navbox-list navbox-odd" style="width:100%;padding:0px"><div style="padding:0em 0.25em"> <ul><li><i><a href="/wiki/Special:MyLanguage/Manual:Coding_conventions/Documentation" title="Special:MyLanguage/Manual:Coding conventions/Documentation">Code documentation</a><span style="display:none"><a href="/wiki/Manual:Coding_conventions/Documentation" title="Manual:Coding conventions/Documentation"> </a></span></i></li></ul> </div></td></tr></tbody></table></div>    </div><noscript><img src="https://login.wikimedia.org/wiki/Special:CentralAutoLogin/start?type=1x1" alt="" width="1" height="1" style="border: none; position: absolute;"></noscript> <div class="printfooter" data-nosnippet="">Retrieved from "<a dir="ltr" href="https://www.mediawiki.org/w/index.php?title=Stable_interface_policy&oldid=6774239">https://www.mediawiki.org/w/index.php?title=Stable_interface_policy&oldid=6774239</a>"</div></div> <div id="catlinks" class="catlinks" data-mw="interface"><div id="mw-normal-catlinks" class="mw-normal-catlinks"><a href="/wiki/Special:Categories" title="Special:Categories">Categories</a>: <ul><li><a href="/wiki/Category:Wikimedia_development_policies" title="Category:Wikimedia development policies">Wikimedia development policies</a></li><li><a href="/wiki/Category:Development_guidelines" title="Category:Development guidelines">Development guidelines</a></li></ul></div><div id="mw-hidden-catlinks" class="mw-hidden-catlinks mw-hidden-cats-hidden">Hidden category: <ul><li><a href="/wiki/Category:Languages_pages" title="Category:Languages pages">Languages pages</a></li></ul></div></div> </div> </main> </div> <div class="mw-footer-container"> <footer id="footer" class="mw-footer" > <ul id="footer-info"> <li id="footer-info-lastmod"> This page was last edited on 27 September 2024, at 18:48.</li> <li id="footer-info-copyright">Text is available under the <a rel="nofollow" class="external text" href="https://creativecommons.org/licenses/by-sa/4.0/deed.en">Creative Commons Attribution-ShareAlike License</a>; additional terms may apply. Text in <a class="external text" href="https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Contents">the Help: namespace</a> is available under the <a rel="nofollow" class="external text" href="https://creativecommons.org/publicdomain/zero/1.0/">Creative Commons CC0 License</a>. By using this site, you agree to the <a class="external text" href="https://foundation.wikimedia.org/wiki/Special:MyLanguage/Policy:Terms_of_Use">Terms of Use</a> and <a class="external text" href="https://foundation.wikimedia.org/wiki/Special:MyLanguage/Policy:Privacy_policy">Privacy Policy</a>.</li> </ul> <ul id="footer-places"> <li id="footer-places-privacy"><a href="https://foundation.wikimedia.org/wiki/Special:MyLanguage/Policy:Privacy_policy">Privacy policy</a></li> <li id="footer-places-about"><a href="/wiki/Project:About">About mediawiki.org</a></li> <li id="footer-places-disclaimers"><a href="/wiki/Project:General_disclaimer">Disclaimers</a></li> <li id="footer-places-wm-codeofconduct"><a href="https://www.mediawiki.org/wiki/Special:MyLanguage/Code_of_Conduct">Code of Conduct</a></li> <li id="footer-places-developers"><a href="https://developer.wikimedia.org">Developers</a></li> <li id="footer-places-statslink"><a href="https://stats.wikimedia.org/#/www.mediawiki.org">Statistics</a></li> <li id="footer-places-cookiestatement"><a href="https://foundation.wikimedia.org/wiki/Special:MyLanguage/Policy:Cookie_statement">Cookie statement</a></li> <li id="footer-places-mobileview"><a href="//m.mediawiki.org/w/index.php?title=Stable_interface_policy&mobileaction=toggle_view_mobile" class="noprint stopMobileRedirectToggle">Mobile view</a></li> </ul> <ul id="footer-icons" class="noprint"> <li id="footer-copyrightico"><a href="https://wikimediafoundation.org/" class="cdx-button cdx-button--fake-button cdx-button--size-large cdx-button--fake-button--enabled"><img src="/static/images/footer/wikimedia-button.svg" width="84" height="29" alt="Wikimedia Foundation" loading="lazy"></a></li> <li id="footer-poweredbyico"><a href="https://www.mediawiki.org/" class="cdx-button cdx-button--fake-button cdx-button--size-large cdx-button--fake-button--enabled"><img src="/w/resources/assets/poweredby_mediawiki.svg" alt="Powered by MediaWiki" width="88" height="31" loading="lazy"></a></li> </ul> </footer> </div> </div> </div> <div class="vector-settings" id="p-dock-bottom"> <ul></ul> </div><script>(RLQ=window.RLQ||[]).push(function(){mw.config.set({"wgHostname":"mw-web.codfw.canary-84779d6bf6-hj2hv","wgBackendResponseTime":134,"wgDiscussionToolsPageThreads":[{"headingLevel":2,"name":"h-","type":"heading","level":0,"id":"h-Quick_guide","replies":[{"headingLevel":3,"name":"h-","type":"heading","level":0,"id":"h-Using_code-Quick_guide","replies":[]},{"headingLevel":3,"name":"h-","type":"heading","level":0,"id":"h-Writing_code-Quick_guide","replies":[]}]},{"headingLevel":2,"name":"h-","type":"heading","level":0,"id":"h-Terminology","replies":[]},{"headingLevel":2,"name":"h-","type":"heading","level":0,"id":"h-Definition_of_the_stable_interface","replies":[{"headingLevel":3,"name":"h-","type":"heading","level":0,"id":"h-Stable_to_call-Definition_of_the_stable_interface","replies":[]},{"headingLevel":3,"name":"h-","type":"heading","level":0,"id":"h-Stable_to_type-Definition_of_the_stable_interface","replies":[]},{"headingLevel":3,"name":"h-","type":"heading","level":0,"id":"h-Stable_to_extend-Definition_of_the_stable_interface","replies":[]},{"headingLevel":3,"name":"h-","type":"heading","level":0,"id":"h-Stable_to_use-Definition_of_the_stable_interface","replies":[]},{"headingLevel":3,"name":"h-","type":"heading","level":0,"id":"h-Stable_to_access-Definition_of_the_stable_interface","replies":[]},{"headingLevel":3,"name":"h-","type":"heading","level":0,"id":"h-Stable_to_implement-Definition_of_the_stable_interface","replies":[]},{"headingLevel":3,"name":"h-","type":"heading","level":0,"id":"h-Stable_to_override-Definition_of_the_stable_interface","replies":[]},{"headingLevel":3,"name":"h-","type":"heading","level":0,"id":"h-Global_variables-Definition_of_the_stable_interface","replies":[]}]},{"headingLevel":2,"name":"h-","type":"heading","level":0,"id":"h-Stability_annotations","replies":[{"headingLevel":3,"name":"h-","type":"heading","level":0,"id":"h-Add_guarantees-Stability_annotations","replies":[]},{"headingLevel":3,"name":"h-","type":"heading","level":0,"id":"h-Remove_guarantees-Stability_annotations","replies":[]}]},{"headingLevel":2,"name":"h-","type":"heading","level":0,"id":"h-Deprecation_process","replies":[{"headingLevel":3,"name":"h-","type":"heading","level":0,"id":"h-Soft_deprecation-Deprecation_process","replies":[]},{"headingLevel":3,"name":"h-","type":"heading","level":0,"id":"h-Hard_deprecation-Deprecation_process","replies":[]},{"headingLevel":3,"name":"h-","type":"heading","level":0,"id":"h-Removal-Deprecation_process","replies":[]},{"headingLevel":3,"name":"h-","type":"heading","level":0,"id":"h-Further_guidance-Deprecation_process","replies":[]}]},{"headingLevel":2,"name":"h-","type":"heading","level":0,"id":"h-Meta","replies":[{"headingLevel":3,"name":"h-","type":"heading","level":0,"id":"h-Motivation-Meta","replies":[]},{"headingLevel":3,"name":"h-","type":"heading","level":0,"id":"h-Scope-Meta","replies":[]},{"headingLevel":3,"name":"h-","type":"heading","level":0,"id":"h-Ecosystem-Meta","replies":[]},{"headingLevel":3,"name":"h-","type":"heading","level":0,"id":"h-History-Meta","replies":[]}]},{"headingLevel":2,"name":"h-","type":"heading","level":0,"id":"h-Frontend_policy","replies":[]}],"wgPageParseReport":{"discussiontools":{"limitreport-timeusage":"0.029"},"limitreport":{"cputime":"0.805","walltime":"0.983","ppvisitednodes":{"value":9833,"limit":1000000},"postexpandincludesize":{"value":96228,"limit":2097152},"templateargumentsize":{"value":31745,"limit":2097152},"expansiondepth":{"value":21,"limit":100},"expensivefunctioncount":{"value":132,"limit":500},"unstrip-depth":{"value":0,"limit":20},"unstrip-size":{"value":29899,"limit":5000000},"entityaccesscount":{"value":0,"limit":400},"timingprofile":["100.00% 854.167 1 -total"," 49.55% 423.251 1 Template:Languages"," 43.57% 372.175 260 Template:Translatable"," 40.84% 348.841 157 Template:Languages/Lang"," 39.14% 334.345 210 Template:Pagelang"," 30.89% 263.891 1 Template:Nmbox"," 29.74% 254.010 50 Template:Ll"," 24.76% 211.474 1 Template:Development_guidelines_navigation"," 24.12% 206.028 1 Template:Navbox"," 14.90% 127.303 1 Template:Development_policy"]},"scribunto":{"limitreport-timeusage":{"value":"0.324","limit":"10.000"},"limitreport-memusage":{"value":1869798,"limit":52428800}},"cachereport":{"origin":"mw-web.codfw.main-757f7495fb-sf8r5","timestamp":"20241105001213","ttl":2592000,"transientcontent":false}}});});</script> </body> </html>