Zásady stabilního rozhraní/Frontend

This page is a translated version of the page Stable interface policy/Frontend and the translation is 100% complete.

Zásady stabilního rozhraní pro kód frontendu MediaWiki (CSS, JavaScript a HTML) definují, které části softwaru jsou považovány za stabilní a bezpečné pro použití kódem založeným na prohlížeči z jiných komponent.

Pokyny k PHP naleznete v stable interface policy . Zásady stabilního rozhraní frontendu jsou udržovány odděleně od zásad stabilního rozhraní PHP kvůli rozdílům v publiku a rozsahu (např. tato zásada se týká také vývojářů gadgetů).

Tento dokument se vztahuje na všechny vývojáře kódu založeného na prohlížeči, který se spoléhá na MediaWiki. Rozsah těchto zásad se týká kódu hostovaného na wiki, který běží na jednom z projektů Wikimedie. Zásady se nevztahují na gadgety spuštěné na instancích MediaWiki třetích stran.

Vývojáři gadgetů na projektech Wikimedia Foundation by měli navíc zvážit Recommendations for gadget developers on Wikimedia wikis jako doplněk.

Stručný návod

Použití kódu

Objekt mw je primární stabilní API pro interakci s MediaWiki v prohlížeči.
HTML by nemělo být považováno za stabilní. Přímý přístup a manipulace s DOM není bezpečná. Jediný bezpečný způsob, jak přistupovat k částem DOM, je prostřednictvím utilit poskytovaných prostřednictvím objektu mw k získání nebo úpravě existujících prvků na stránce, nikoli pomocí dotazů DOM. Pokud neexistuje žádná užitečná funkce, která by vyhovovala vašemu případu použití, dejte nám prosím vědět.

Komunikace

Prostudujte si doc.wikimedia.org (zejména dokumentaci jádra MediaWiki) pro dokumentaci dostupných stabilních rozhraní.
Požádejte o rozhraní API prostřednictvím Phabricatoru, kde rozhraní API chybí, místo abyste se spoléhali na nestabilní funkce, struktury nebo identifikátory.
Přečtěte si a reagujte na upozornění na ukončení podpory ve vývojářské konzoli JavaScriptu v aktuální verzi.
Chcete-li se dozvědět o ukončení podpory, přihlaste se k odběru Technického zpravodaje (Tech News).
Pokud píšete "kód hostovaný na Wiki" (viz část terminologie níže), prosím přečtěte si doporučení pro vývojáře kódu on-wiki .

Psaní kódu

HTML není stabilní rozhraní, ale poskytovatelé musí vzít v úvahu komunikační změny, které mění značení HTML s ID nebo atributy třídy HTML obsahujícími mw-, protože je mohli historicky používat vývojáři kódu založeného na wiki.
Při přejmenování nebo odebrání modulů ResourceLoader postupujte podle procesu ukončení podpory
Omezte kód vystavený na objektu mw, protože musí být udržován jako stabilní API, pokud nebyl označen jako @private.
Udržujte veřejné metody vystavené na objektu mw a mw.hook podpisy kompatibilní pro volající. Pro zrušení změn postupujte podle procesu ukončení podpory.

Komunikace

Spolupracujte s vývojáři gadgetů na deaktivaci nebo opravě neudržovaných gadgetů, které narušují naši schopnost sledovat chyby JavaScriptu.
Spolupracujte s vývojáři gadgetů a dalšími vývojáři rozšíření na identifikaci a přidání chybějících stabilních rozhraní API.

Terminologie

MAY, MUST, SHOULD: Viz RFC 2119, abyste porozuměli jazyku používanému v těchto zásadách k označení úrovní požadavků.
Wikimedia wikis (wikiny Wikimedie): všechny veřejné projekty Wikimedia Foundation
wiki-hosted code (kód hostovaný na wiki): kód, který se spouští na projektech Wikimedia Foundation, jejichž zdrojový kód je uložen na stránce, kterou lze upravovat na wiki
frontend code (kód frontend): jakýkoli kód, který je spuštěn prohlížečem, jako je HTML, CSS a JavaScript na straně klienta, včetně kódu hostovaného na wiki i kódu MediaWiki nasazeného na straně serveru (jádro MediaWiki, rozšíření a vzhledy)
MediaWiki developer (vývojář MediaWiki): někdo, kdo přispívá kódem do jádra MediaWiki nebo do rozšíření nebo vzhledu MediaWiki, který je nasazen na jakémkoli projektu Wikimedia Foundation
providers (poskytovatelé): Vývojáři MediaWiki, kteří definují stabilní rozhraní
consumers (spotřebitelé): kód, který využívá stabilní rozhraní, a správci takového kódu, včetně vývojářů MediaWiki a také vývojářů kódu hostovaného na wiki
caching implications (důsledky ukládání do mezipaměti): Důsledky ukládání do mezipaměti se používají k popisu situace na produkčních webech Wikimedia, kde je uživatelům poskytováno staré označení HTML spolu s novými styly. HTML ukládáme do mezipaměti po delší dobu než aktiva JavaScript a CSS. Důsledky ukládání do mezipaměti se vztahují na jakoukoli stránku, která je uložena v mezipaměti ve vrstvě edge (obvykle každá stránka, kterou mohou vykreslit anonymní uživatelé s výjimkou speciálního jmenného prostoru). Podrobné vysvětlení ukládání do mezipaměti je mimo rozsah tohoto dokumentu; více informací viz Funkce pro čtení/web/vytváření s ohledem na HTML uložené v mezipaměti .
popularity of a gadget (popularita gadgetu): Popularita gadgetu se týká toho, jak široce používaný nebo důležitý je gadget v ekosystému Wikimedie. Popularitu lze hodnotit pomocí Special:GadgetUsage a Uživatelských skriptů/Nejvíce importovaných skriptů) pomocí Global Search. Obecným pravidlem je, že popularitu lze posuzovat podle více než 50 skriptů ve jmenném prostoru MediaWiki nebo více než 1000 skriptů napříč uživatelem a jmenným prostorem MediaWiki ovlivněných jakoukoli danou změnou. Při určování použití a popularity použijte svůj nejlepší úsudek. Například gadget Twinkle je široce používán, takže problém, který má dopad na gadget Twinkle, může být závažnější než změna, která má dopad na 100 uživatelských skriptů. Účastníci vývoje Wikimedie by měli být shovívaví, když se vyskytnou chyby, a navrhnout revize naší definice popularity gadgetů na základě zkušeností z reálného světa prostřednictvím diskuze na diskusní stránce.
Codesearch (hledání kódu): nástroj MediaWiki Codesearch dostupný na codesearch.wmcloud.org
Global Search (globální vyhledávání): vyhledávací nástroj pro Wikimedia wiki dostupný na global-search.toolforge.org

Definice stabilního rozhraní

Co lze považovat za stabilní?

Moduly ResourceLoader

Všechny moduly ResourceLoader uvnitř jádra MediaWiki MUSÍ být považovány za stabilní při načítání a musí se řídit procesem ukončení, pokud nejsou označeny jako zastaralé. U modulů poskytovaných rozšířením nebo vzhledem MediaWiki není nutné řídit se procesem ukončení podpory, pokud jste modul výslovně neurčili jako pro použití jinými rozšířeními, vzhledy nebo gadgety.

Kód JavaScript

Poznámka: Naším cílem je vyjasnit stabilní smlouvy, které byly před vydáním 1.42 jako součást phab:T348076 nejednoznačné, přidáním značek @stable, @ignore a @internal. Mějte prosím trpělivost, když provádíme toto čištění naší dokumentace!

Kód JavaScriptu, který je považován za stabilní MUSÍ následovat proces ukončení podpory. To zahrnuje:

Kód, který se ve své JavaScriptové dokumentaci deklaruje jako stabilní buď na doc.wikimedia.org nebo ResourceLoader/Core modules , nejlépe pomocí značky @stable. Pokud je vlastnost nebo modul označen jako stabilní, znamená to, že všechny jeho veřejné metody jsou také stabilní.
Poznámka: Jasnější pokyny k dokumentaci budou poskytnuty jako součást phab:T138401.
```
// Provider of mediawiki.foo.module:
/**
* mediawiki.foo.module
* @stable for use inside gadgets and extensions
*/
module.exports = {
    stableMethod
};

// Consumer of mediawiki.foo.module:
var foo = require( 'mediawiki.foo.module' );
foo.stableMethod();
```

Kód, který je definován na veřejném objektu mw, který nebyl zdokumentován jako @private, bez ohledu na to, jak byl kód přidán (rozšíření, vzhled nebo kód založený na wiki), i když kód nebyl označen jako @stable.

mw.mobileFrontend = {
    /**
     * Even though this code is on the global mw method it has been documented as
     * private so it is not stable.
     * @private
    */
    privateMethod: function () { ... },
    /**
     * If the method is on the mw object and not marked as private, it can be considered
     * stable. If the provider does not want to consider the method private, the method
     * must follow the deprecation process.
     */
    stableMethod: function () {
        this.privateMethod();
    }
};
// consumer of mw public method
mw.mobileFrontend.stableMethod();

Podpis funkce funkce zpětného volání pro háčky spouštěné pomocí objektu mw.hook v základním kódu MediaWiki BY MĚL být považován za stabilní, pokud není označen jako @private nebo @internal. Spotřebitelé mohou očekávat, že háček bude spuštěn za okolností popsaných v jeho dokumentaci.

// Hooks are stable.
mw.hook.fire( 'foo',  alert, 'This hook should be considered stable and is subject to the deprecation policy' );

// The following code is safe to use given it uses code that is described as stable.
mw.hook.add( 'foo', function ( fn, message ) {
    fn( message );
} );

Další informace pro poskytovatele

Poskytovatelé BY MĚLI dokumentovat všechny stabilní metody na doc.wikimedia.org a dodržovat aktuální konvence kódování .

Poskytovatelé, kteří se chtějí vyhnout přidávání kódu na veřejný objekt mw SHOULD, místo toho sdílejí kód mezi moduly pomocí ResourceLoader/Package files (pomocí module.exports a require( '<názvu souboru>' )). Viz OptionalParamWidget.js jako příklad třídy, která není definována na objektu mw a může být použita pouze mediawiki.special.apisandbox.

Poskytovatelé používající ResourceLoader/Package files SHOULD omezují, jaké funkce jsou exportovány v souboru hlavního modulu na ty, které je třeba sdílet mezi více moduly ResourceLoader.

Další informace pro spotřebitele

Funkce require() je přístupná pouze pro moduly ResourceLoader a v současné době NEMĚLO by se považovat za stabilní rozhraní mimo moduly ResourceLoader, kde není definováno.

Co není stabilní?

Značky HTML a CSS nelze považovat za stabilní (pokud to není výslovně uvedeno). Veškerý kód frontendu (včetně kódu hostovaného na wiki, rozšíření a vzhledů), který se spoléhá na strukturu HTML, tak činí na vlastní riziko. Spotřebitelé však často spoléhají na strukturu DOM a nestabilní identifikátory z historických důvodů kvůli chybějícím rozhraním API. Například:

Stabilní

$( '<div>Hello world</div>').prependTo( mw.util.$content );

Nestabilní

$( '<div>Hello world</div>').prependTo( '#content' );

Rady pro poskytovatele

Vývojáři MediaWiki nejsou povinni, ale jsou povinni respektovat stávající práci vývojářů gadgetů tím, že proaktivně komunikují jakékoli změny značení HTML tam, kde nejsou v současné době k dispozici alternativní API, zejména v projektech, které mají vysokou viditelnost nebo fungují v jmenný prostor článku. Tento požadavek bude zrušen 2 roky po zavedení stabilních zásad frontendu (září 2025).

V případech, kdy by pro vývojáře kódu hostovaného na wiki a vývojáře MediaWiki mohlo být vzájemně výhodné sdílet šablony stylů, například z důvodů výkonu, i když to není doporučeno, vztah MUSÍ být zdokumentován ve zdrojově řízeném kódu pomocí značek @public a @since a odkazu na diskuzi na wiki. Třídy definované v atributech třídy HTML, které si přejí být považovány za stabilní, MUSÍ přidat vložený komentář s uvedením, ve které verzi MediaWiki byly představeny, pomocí anotace @since a musí následovat proces ukončení podpory v příslušné sekci níže. Například:

Ano

/**
 * When changing this file or associated markup, please take care to note it is stable and in use on various wikis!
 */

/* BEGIN */
/**
 * @public for use by templates
 * @stable this class is used by 10,000+ templates on page load and should not be removed from the page without following the deprecation process. See discussion on [[mediawiki:Can we share the banana styles?]] for more context.
 * @since August 2023 (MediaWiki 1.41)
 */
.mw-banana {
   color: yellow;
   padding: 10px;
}

Ne

.mw-banana {
   color: yellow;
   padding: 10px;
}

Rady pro spotřebitele

Kód hostovaný na wiki NEMĚL používat šablony stylů definované jádrem MediaWiki pro stylování vlastních značek HTML, protože to může vést ke zneužití, nedorozumění a poškození (T213239, T287997), pokud tento vztah nevyjasní pohlcující kód prostřednictvím značek @public a @since (viz rady pro poskytovatele). Místo toho kód hostovaný na wiki BY MĚL definovat svou vlastní třídu a pravidla stylu.

Například: Gadgety by neměly replikovat označení HTML rozbalovací nabídky ve Vectoru pomocí šablon stylů Vector. Šablona stylů není stabilní a může se bez upozornění změnit. Místo toho by kód hostovaný na wiki měl používat funkci mw.util.addPortletLink k přidání dalších položek nabídky, protože jako součást objektu mw by měl být považován za stabilní, a pokud napodobuje značku HTML, měl by také napodobovat CSS, které s ním souvisí, aby se mohl spolehnout na tom, že se styly nemění.

Pokyny pro spotřebitele, kteří potřebují bezpečně změnit značení HTML a třídy CSS

Vývojáři MediaWiki MUSÍ chápat a zvažovat důsledky ukládání do mezipaměti, konkrétně to, že HTML z předchozího nasazení může být uživatelům poskytováno spolu s novějšími CSS. U stránek, které jsou uloženy do mezipaměti, vývojáři MediaWiki MUSÍ zvážit, jak bude stylizován HTML, který je starší než týden (například HTML vygenerovaný během posledního cvičného cyklu).

Vývojáři MediaWiki BY MĚLI nejprve zhodnotit dopad své změny na HTML značkování na kód hostovaný na wiki na základě na základě komunikačních pokynů a zda je komunikace doporučena.

Zvláštní opatrnost "MUSÍ" být věnována, když:

změna jakéhokoli prvku pomocí třídy nebo ID s předponou mw-, jak je tradičně předpona některými spojována jako stabilní rozhraní.
odstranění atributu třídy elementu HTML z výstupního HTML, který poskytuje analyzátor wikitextu MediaWiki (například .wikitable a .external).
- V případě přejmenování ID, která by mohla být mylně považována za stabilní (například kvůli historickému spojení s předponou mw- nebo ID, které se za více než 5 let nezměnilo), vývojáři BY MĚLI zvážit delší čas odklad, protože neexistuje způsob, jak zajistit zpětnou kompatibilitu.
- V případě přejmenování tříd se doporučuje, aby nová třída MOHLA BÝT přidána spolu s odstraněnou třídou po dobu alespoň jeden cyklus vydání MediaWiki pro případ, že by se na ně třetí strany mohly spoléhat, např. pro zpracování HTML. Vložený komentář SHOULD označuje, ve kterém vydání byla stará třída zastaralá.
- Tam, kde API neexistují, BY MĚLI poskytovatelé vytvářet úlohy pro chybějící API na Phabricatoru.

Vývojáři MediaWiki MUSÍ dodržovat konvence z Příručky:Coding_conventions/CSS#Naming . Výhody používání konvencí pojmenování jsou dvojí:

Vývojáři mohou použít nástroj Codesearch ke snadnému vyhledání místa, kde se generuje HTML.
Vývojáři gadgetů kvůli historickému používání často spoléhají na selektory s předponou mw- a předpokládají, že jsou stabilní a nejsou náchylné ke změnám.

Pokyny pro spotřebitele, jak se vyhnout spoléhání se na strukturu HTML

Pro přidávání položek do nabídek se doporučuje metoda mw.util.addPortletLink, spíše než spoléhání se na jQuery. Chcete-li přidat titulky, použijte místo přidávání k prvkům #contentSub nebo #mw-content-subtitle mw.util.addSubtitle.

Pokud zjistíte, že se spoléháte na CSS v jádru, MĚLI BYSTE požadovat funkci pro generování značek, které jsou kompatibilní pro daný CSS. Tam, kde API neexistují, spotřebitelé BY MĚLI požadovat API pro přístup k prvkům nebo rozšíření existujících prvků prostřednictvím Phabricatoru.

Pokyny pro poskytovatele upravující výchozí styly

Vývojáři MediaWiki MAY změní výchozí CSS pro obsah generovaný wikitextem (jako je změna výchozích barev odkazů nebo změna typografie). I když je to vzácné, vývojáři BY MĚLI konzultovat globální vyhledávání, aby se informovali o potenciálních místních přepsáních provedených editory v MediaWiki:Common.css a BY MĚLI postupovat podle pokynů pro sdělování změn vývojářům gadgetů, když změna může být kontroverzní nebo potenciálně způsobit vizuální změny.

Proces ukončení podpory

U frontendového kódu neděláme rozdíl mezi měkkým a tvrdým ukončením podpory, protože nezaznamenáváme upozornění na ukončení podpory a jejich primárním účelem je komunikace s vývojáři.

Pokyny pro poskytovatele, kteří provádějí zásadní změny ve stabilních rozhraních JavaScriptu

Kód, který nikdy nebyl součástí veřejné verze MediaWiki a nikdy nebyl spotřebován podle Codesearch a Global Search MŮŽE být změněn (včetně explicitně označených jako @private) nebo odstraněn bez ukončení podpory, protože kód se nikdy nestal součástí stabilního rozhraní ani nebyl použit.

Při ukončení podpory kódu JavaScript:

Do dokumentace JavaScriptu MUSÍ být přidáno @deprecated a BY MĚLO zaznamenat číslo vydání MediaWiki.
K signalizaci ukončení API MUSÍ být použita metoda mw.log.deprecate. Zpráva o ukončení podpory BY MĚLA uvádět vydání, ve kterém k ukončení podpory došlo.

Například:

/**
 * @deprecated 1.40 use mw.util.bar instead.
 */
 mw.util.foo = function () {
    mw.log.deprecate(
        'Foo has been deprecated in MediaWiki 1.40. Please use mw.util.bar instead.'
    );
    mw.util.bar();
};

Zastaralé metody NESMÍ být odstraněny, dokud nebudou zaznamenávat upozornění na ukončení alespoň v jednom stabilním vydání a po dobu alespoň jednoho měsíce v produkčním prostředí Wikimedie. Vývojáři MediaWiki MUSÍ dodržovat pokyny pro oznámení změn vývojářům gadgetů.

Při změně podpisu funkce nebo odstranění háčku spotřebitelé MUSÍ zavolat funkci mw.log.deprecate v rámci zpětného volání, které definuje. Například:

/**
 * Fired when indicators are being added to the DOM
 *
 * @event foo
 * @deprecated 1.40 use X instead.
 * @member mw.hook
 * @param {jQuery} $content jQuery object with the elements of the indicators
 */
mw.hook( 'foo' ).add( function ( p ) {
    mw.log.deprecate(
        'The hook `foo` has been deprecated in MediaWiki 1.40. Please use X instead.'
    );
} ).fire( param1 );

Pokyny pro poskytovatele, kteří odebírají moduly ResourceLoader

Kód, který nikdy nebyl součástí veřejné verze MediaWiki a nikdy nebyl spotřebován podle Codesearch a Global Search MŮŽE být změněn nebo odstraněn bez ukončení podpory, protože kód se nikdy nestal součástí stabilní rozhraní nebo používané.

Před odstraněním modulu MUSÍ být modul zastaralý, takže jeho použití zaznamenává varování o tvrdém ukončení pro alespoň jedno vydání MediaWiki před odstraněním pomocí zastaralého klíče v jeho definici ResourceLoader. Toto je podpora vývojářů třetích stran, kteří potřebují být upozorněni a reagovat na jakékoli změny v upstreamu.

Při zastarávání modulu ResourceLoader nastavte zastaralý klíč na přidruženém ResourceLoaderu. Vývojář MUSÍ dokumentovat ukončení podpory v RELEASE_NOTES a uvést číslo verze, ve které k ukončení podpory došlo. Například:

[
	'wvui' => [
		'deprecated' => 'Deprecated in 1.39. Use `@wikimedia/codex` instead.',
		'packageFiles' => [
			'resources/src/wvui/wvui.js',
			'resources/lib/wvui/wvui.commonjs2.js',
		],
	],
]

Vývojáři MOHOU opravit spotřebitele modulu před ukončením podpory, ale není to vyžadováno jako předchůdce ukončení podpory.

Při dokončení ukončení podpory MUSÍ být odstranění zdokumentováno v RELEASE_NOTES. Sdělte změnu vývojářům gadgetů podle pokynů pro komunikaci.

Povinnosti vývojáře MediaWiki

Poskytovatelé

Vývojáři MediaWiki MUSÍ věnovat pozornost lístkům Phabricatoru s požadavky na údržbu kódu a sdělovat jakékoli problémy, které vidí při jejich řešení.
Všechny nové kódy MediaWiki nasazené na Wikimedii BY MĚLY zvážit poskytnutí stabilního způsobu podpory rozšiřitelnosti kódu on-wiki, pokud je tato vlastnost požadována.
Vývojáři MediaWiki MUSÍ každoročně revidovat populární gadgety pomocí Global Search, aby vyhodnotili kód, který vytváří předpoklady o struktuře HTML, a označili příležitosti a plánovali konstrukci nových API. Vývojáři MediaWiki MOHOU hodnotit jako součást svého plánovacího procesu a MUSÍ hodnotit v situacích, kdy vývojář gadgetu vyvolá lístek Phabricatoru poté, co došlo k incidentu (například v situaci, kdy oblíbené přestávky gadgetů).
Vývojáři MediaWiki MOŽNÁ používají označení funkcí (jako je BetaFeatures nebo uživatelské preference) v nasazení, aby umožnili editorům otestovat rozhraní před vývojem a MĚLI BY inzerovat jejich dostupnost prostřednictvím Technického zpravodaje.

Uživatelé

Vývojáři MediaWiki BY MĚLI pravidelně kontrolovat konzoli JavaScriptu, zda neobsahuje upozornění na ukončení podpory a varování, a zapojit je do jednoho cyklu vydání, a to buď tím, že problém opraví, nebo objasní, proč to není možné.
Nově napsaný kód BY NEMĚL používat zastaralé moduly ResourceLoader (například jQuery.UI).

Jak mohou poskytovatelé provést zásadní změny, které ovlivňují široce používané, ale neudržované gadgety

Při provádění přerušovaných změn je navzdory dobrým úmyslům nevyhnutelné i při dobré komunikaci, že některé skripty na wiki nebudou jejich správci aktualizovány a změna povede k produkčním chybám anebo narušení pracovních postupů editoru.

Chyby na straně klienta vyskytující se v kódu hostovaném na wiki jsou sledovány spolu s chybami v kódu MediaWiki na Grafana a lze je dále prozkoumat v naší instanci logstash.

Při provádění přerušujících změn jsou vývojáři MediaWiki povinni opravit nebo zakázat určité gadgety v následujících scénářích:

Vývojáři MediaWiki MUSÍ opravit nebo zakázat protokolování chyb pro jakýkoli kód hostovaný na wiki anebo chyby uživatelského skriptu s množstvím chyb, které spouštějí výstrahy prostřednictvím výstražných systémů Wikimedie. Zdravé metriky nám pomáhají mít větší jistotu při nasazování kódu. V ideálním případě BY MĚL správce provést opravu kódu po diskuzi na diskusní stránce skriptu, avšak v časově citlivých situacích vývojáři MediaWiki MOHOU zasáhnout sami, pokud jim to vyhovuje.
Vývojáři MediaWiki SMÍ opravit nebo deaktivovat chyby v kódu hostovaném na wiki anebo uživatelském skriptu, které podkopávají soukromí uživatelů. Pokud například aktivní uživatel spouští chybu při každém načtení stránky, která odhaluje historii stránky, doporučujeme chybu opravit.
Vývojáři MediaWiki MOHOU opravit nebo deaktivovat kód hostovaný na wiki, který je poškozený, za předpokladu, že shrnutí úprav nebo diskusní stránka dokumentuje, jak lze problém vyřešit.
Vývojáři MediaWiki MŮŽOU spouštět roboty, aby automatizovali opravy kódu hostovaného na wiki tam, kde je rozlišení jednoduché. Příklad: Metoda je přejmenována.

Jak sdělit změny spotřebitelům

Komunikace o změnách pro vývojáře kódu hostovaném na wiki

Jsou-li ovlivněny některé gadgety/skripty, vývojáři MediaWiki BY MĚLI upozornit Technický zpravodaj. U změn, které ovlivňují populární gadgety takovým způsobem, že narušují funkčnost nebo kde se změnila stabilní rozhraní (bez ohledu na to, zda jsou používána), tak vývojáři MediaWiki MUSÍ učinit. Pokud jsou vývojáři MediaWiki přesvědčeni, že gadgety nebudou vážně ovlivněny (například pokud je gadget po změně stále funkční, ale stylově odlišný), lze komunikaci přeskočit.

Pokud je vyžadována komunikace:

Lhůta alespoň jednoho měsíce MUSÍ být poskytnuta vývojářům kódu hostovaným na wiki, aby reagovali a vznesli jakékoli obavy týkající se změny bez ohledu na vydání MediaWiki.
Vývojáři MediaWiki MUSÍ zvážit jakoukoli zpětnou vazbu od vývojářů gadgetů, aby minimalizovali narušení (například vytvořit lístky pro zavádění API tam, kde chybí).

Pro veškerou komunikaci:

Položka Technického zpravodaje MUSÍ zmínit v názvu "BREAKING CHANGE" (přelomovou změnu) a v popisu poskytnout kroky k vyřešení problému.
Poskytovatelé BY MĚLI použít svůj nejlepší úsudek k určení časové osy pro změny, které mají dopad na nestabilní rozhraní.

Když se dozvíte o rozbití miniaplikací na wikinách Wikimedie, na které se nevztahují zásady kódu hostovaného na wiki, např. používající nestabilní rozhraní kvůli nedostupnosti, vývojáři MediaWiki MUSÍ posoudit zahrnutí nového stabilního rozhraní, aby se omezilo budoucí poškození.

Komunikace změn s ostatními vývojáři MediaWiki

Pokud je kód běžící na projektech Wikimedie ovlivněn změnami, vývojáři MUSÍ otevřít lístek(y) Phabricatoru a sledovat problém pro ovlivněné vzhledy anebo rozšíření. Lístek(y) Phabricator BY MĚL označit dotčený projekt a podrobně popsat časovou osu pro odstranění a poskytnout podrobnosti o požadované změně. Vývojáři MOHOU poskytnout záplaty a doporučuje se, aby tak učinili zejména v případě, kdy je oprava jednoduchá.

Zásady stabilního rozhraní/Frontend

Contents

Stručný návod

Použití kódu

Komunikace

Psaní kódu

Komunikace

Terminologie

Definice stabilního rozhraní

Co lze považovat za stabilní?

Moduly ResourceLoader

Kód JavaScript

Další informace pro poskytovatele

Další informace pro spotřebitele

Co není stabilní?

Rady pro poskytovatele

Rady pro spotřebitele

Pokyny pro spotřebitele, kteří potřebují bezpečně změnit značení HTML a třídy CSS

Pokyny pro spotřebitele, jak se vyhnout spoléhání se na strukturu HTML

Pokyny pro poskytovatele upravující výchozí styly

Proces ukončení podpory

Pokyny pro poskytovatele, kteří provádějí zásadní změny ve stabilních rozhraních JavaScriptu

Pokyny pro poskytovatele, kteří odebírají moduly ResourceLoader

Povinnosti vývojáře MediaWiki

Poskytovatelé

Uživatelé

Jak mohou poskytovatelé provést zásadní změny, které ovlivňují široce používané, ale neudržované gadgety

Jak sdělit změny spotřebitelům

Komunikace o změnách pro vývojáře kódu hostovaném na wiki

Komunikace změn s ostatními vývojáři MediaWiki

Meta

Motivace

Historie