MediaWiki

Doporučené postupy pro rozšíření

This page is a translated version of the page Best practices for extensions and the translation is 100% complete.
Languages:

Tato stránka dokumentuje aktuální osvědčené postupy pro vývoj rozšíření MediaWiki. Pokud není uvedeno jinak, platí to i pro vzhledy.

Každé položce je přiřazeno hodnocení, které odráží její relativní důležitost. Hodnocení používá klíčová slova definovaná v RFC 2119. Zde je jejich význam v kontextu:

  • MUST: Tato položka je povinná. Splnění těchto pouze znamená, že vaše rozšíření bude fungovat, ale může být neudržitelné.
  • SHOULD: Tato položka je doporučena. Splnění těchto podmínek znamená, že vaše rozšíření funguje dobře a pravděpodobně bude dobře fungovat i v budoucnu.
  • OPTIONAL: Tato položka je volitelná. Doporučujeme vám to zvážit. Rozšíření, která toto splňují, lze považovat za splňující "zlatý standard", po kterém všichni toužíme, a mohou být použita jako příklad pro ostatní vývojáře.

Pracovní postup

  • MUST: Použijte standardní sledovač problémů . Vytvořte nebo požádejte o vytvoření projektu ve Phabricatoru pro vaše rozšíření.
  • MUST: Použijte standardní systém Code review .
  • MUST: Před nasazením na wikiny Wikimedia Foundation – absolvujte kontroly výkonu a zabezpečení .
  • SHOULD: Rozšíření by mělo být vhodné pro použití na jakékoli wiki, vyhněte se specifikům hardcodingu pro Wikimedia Foundation nebo jiné organizace.
  • SHOULD: Před nasazením na wikiny Wikimedia Foundation – přidejte rozšíření a svůj tým na stránku Maintainers .
  • SHOULD: Mějte spolusprávce! Měli by být minimálně dva správci. (Nemusí být zaměstnanci Wikimedia Foundation.)
  • OPTIONAL: Vytvořte průvodce instalací MediaWiki-Docker pro své rozšíření.
  • OPTIONAL: Vytvořte pro své rozšíření roli MediaWiki-Vagrant .

Architektura kódu

  • MUST: Použijte strukturované protokolování s názvem kanálu specifickým pro vaše rozšíření a s odpovídajícím použitím úrovní závažnosti zpráv. To pomáhá s laděním. Pro nasazení Wikimedia Foundation to také pomáhá vašemu týmu při monitorování rozšíření. Viz také: Logstash na Wikitech.
  • SHOULD: Poskytněte stejnou funkcionalitu prostřednictvím rozhraní API (Action API nebo REST API ) a grafického rozhraní (index.php).
    • OPTIONAL: Funkce by měla být implementována bez významné duplikace kódu (např. sdílená třída back-endové služby s lehkým rozhraním API a vazbami SpecialPage.)
  • SHOULD: Použijte Dependency Injection ("DI") a servisní třídy registrované v servisní struktuře.
  • SHOULD: Vyhněte se globálnímu stavu, zejména singletonům nebo jinému skrytému stavu prostřednictvím statické proměnné třídy (s výjimkou protokolů ladění a jiných stavů přímo o aktuálním procesu a ne o nějaké konkrétní wiki nebo volajícím). Vyhněte se statickým voláním čehokoli jiného než bezstavových obslužných metod.
  • SHOULD: Při psaní nových tříd služeb založených na DI se vyhněte použití starších nefaktorovaných globálních nebo statických funkcí z nesouvisejících tříd.
  • SHOULD: Výjimky vkládejte pouze v situacích, které by volající neměli řešit, a proto mají vybuchnout.
  • SHOULD: Nekódujte wikitext a domněnky o šablonách napevno, zejména způsobem, který není konfigurovatelný pro každý web.
  • SHOULD: Kód by měl být čitelný pro toho, kdo se v dané oblasti vyzná.
  • SHOULD: Mějte jasné oddělení obav mezi tím, co skutečně dělá, a tím, jak je prezentováno uživateli.
  • SHOULD: Dobře si rozmyslete, než přidáte nová veřejná API, která musí zůstat kvůli kompatibilitě obsahu, jako je nová funkce syntaxe wikitextu.
  • SHOULD: Není těsně integrována funkce vzhledu s funkcí rozšíření.
  • SHOULD: Nepřidávejte nové uživatelské preference , pokud k tomu nemáte opravdu dobrý důvod.
  • OPTIONAL: Ukažte metody JavaScriptu pro použití user scripts a gadgety a povolte snadné ladění z konzole.

Dokumentace

  • MUST: Mít Stránka rozšíření:… na mediawiki.org.
    • MUST: Přidejte jej do příslušných kategorií rozšíření .
    • MUST: Stručně vysvětlete, co dělá.
    • MUST: Dokument poskytne háčky pod Extension:ExtensionName/Hooks/HookName pomocí {{Template:ExtensionHook}} (pokud existují).
    • MUST: Uveďte všechna rozšíření, na kterých závisí, a jak je nainstalovat a nakonfigurovat.
    • SHOULD: Nastavte zásadu kompatibility pro vaše rozšíření v informačním poli.
    • SHOULD: Popište všechna nastavení konfigurace na jednom místě, od nejpoužívanějších po nejobskurnější.
    • OPTIONAL: Uveďte všechna podobná rozšíření a vysvětlete, v čem se liší a v čem se liší od nich.
    • OPTIONAL: Napište pokyny, jak rozšíření odinstalovat, nebo zdokumentujte omezenou možnost odinstalovat.
  • MUST: Pokud má rozšíření webové uživatelské rozhraní, použijte stránku Nápověda:Rozšíření:… na mediawiki.org.
    • OPTIONAL: Přidejte snímky obrazovky ve více jazycích a v ideálním případě přidejte jeden v jazyce zprava doleva .
    • OPTIONAL: Uveďte některé okrajové případy, které byly testovány – pro prokázání náležité péče nejen testování na jednoduchých/obecných článcích.
  • SHOULD: V dokumentaci podle potřeby důsledně používejte ‎<code>, ‎<syntaxhighlight>, ‎<kbd> a ‎<pre>.
  • OPTIONAL: Přidejte nebo aktualizujte stránku rozšíření na WikiApiary .

Struktura souboru

Celkově by uspořádání souborů rozšíření mělo být organizováno: Konzistentní pojmenování, struktura adresářů, která je logická a není chaotická.

  • MUST: Pomocí následujícího standardního rozložení adresářů:
    • src/ (při použití jmenných mezer PSR4, preferováno) nebo includes/: Obsahuje všechny (a pouze) třídy PHP.
      • i18n soubory pro speciální alias stránky, kouzelná slova nebo jmenné prostory umístěné v kořenové složce.
      • SHOULD: Pro třídy a soubory použijte strukturu PSR-4, místo výpisu všech tříd použijte Extension.json/Schema#AutoloadNamespaces v extension.json.
      • SHOULD: Třídy ve jmenném prostoru MediaWiki\Extension\<ExtensionName> (nebo MediaWiki\Skin\<SkinName> v případě vzhledu). MediaWiki\<ExtensionName> je přípustné, pokud je název rozšíření dostatečně jedinečné slovo a ne něco obecného (např. ne sloveso nebo podstatné jméno).
      • SHOULD: Jedna třída na soubor.
    • modules/ (nebo resources) - obsahuje JavaScript a CSS pro ResourceLoader .
    • maintenance/ skripty příkazového řádku údržby
    • i18n/ - obsahuje lokalizované zprávy v souborech JSON.
    • sql/ - SQL soubory pro úpravy databáze (např. volané LoadExtensionSchemaUpdates )
    • tests/:
      • tests/parser/ - obsahuje test parseru souborů.
      • tests/phpunit/ - obsahuje testovací případy PHUnit .
        • tests/phpunit/unit/ - obsahuje testovací případy rozšiřující MediaWikiUnitTestCase
        • tests/phpunit/integration/ - obsahuje testovací případy rozšiřující MediaWikiIntegrationTestCase
      • tests/qunit/ - obsahuje testovací případy Qunit .
      • tests/selenium/ - obsahuje test prohlížeče Selenium .
    • COPYING nebo LICENSE - obsahuje úplnou kopii příslušné licence, pod kterou je kód uvolněn.
  • SHOULD: Vyhněte se tomu, aby bylo v kořenovém adresáři mnoho souborů.
  • SHOULD: Vyhněte se desítkám vnořených adresářů, které všechny obsahují pouze jednu nebo dvě věci.
  • SHOULD: Vyhněte se tomu, abyste měli velmi velké soubory nebo velmi mnoho malých souborů (ale pokračujte podle jedné třídy na vzor souboru – mnoho malých tříd může být známkou toho, že se něco pokazilo).
  • SHOULD: Napište soubor README, který shrnuje dokumenty a poskytne podrobné pokyny k instalaci.
  • SHOULD: Deklarujte cizí zdroje v souboru foreign-resources.yaml.

Databáze

  • MUST: Pokud přidáváte databázové tabulky, použijte háček LoadExtensionSchemaUpdates , aby update.php fungoval.
  • MUST: Pro veškerý přístup k databázi používá knihovnu Wikimedia-Rdbms . Vyhnete se tak většině vektorů útoků SQL injection, zajistíte správnost transakcí a dodržíte osvědčené postupy pro výkon.
  • SHOULD: Pracujte dobře v distribuovaném prostředí (souběžnost, více databází, shlukování).
  • SHOULD: Pokud to vyžaduje vytrvalost, vytvořte pěkné SQL (primární klíče, indexy, kde je potřeba) a použijte nějaký cachovací mechanismus tam, kde je to nutné.
  • SHOULD: Nikdy nepřidávejte pole do základních tabulek ani je žádným způsobem neměňte. Chcete-li zachovat data přidružená k základním tabulkám, vytvořte vyhrazenou tabulku pro rozšíření a odkazujte na primární klíč základní tabulky. To usnadňuje odstranění rozšíření.
  • SHOULD: Měl by používat abstraktní schéma .
  • OPTIONAL: Pokud rozšíření přetrvává v datech a podporuje odinstalaci, poskytněte skript údržby, který to automatizuje (např. přetažení tabulek, odstranění příslušných položek protokolu a vlastností stránky).

Konvence kódování

Celkově dodržujte konvence kódování MediaWiki pro PHP , JavaScript , CSS a jakékoli další jazyky, které se používají a mají příslušné konvence kódu.

  • SHOULD: Spusťte MediaWiki-CodeSniffer , abyste prosadili konvence PHP (zkontrolujte vstupní body CI ).
  • SHOULD: Spusťte Phan pro statickou analýzu PHP (zkontrolujte vstupní body CI ).
  • SHOULD: Spusťte ESLint for JavaScript konvence a statickou analýzu (zkontrolujte vstupní body CI ).
  • SHOULD: Spusťte Stylelint pro konvence CSS (zkontrolujte vstupní body CI ).
  • SHOULD: Vyhněte se psaní celého kódu do jedné velké funkce (zejména v JavaScriptu).
  • OPTIONAL: Obecně používejte komentáře ke kódu, abyste zdokumentovali, proč kód existuje, ne co kód dělá. V dlouhých blocích kódu je přidávání komentářů uvádějících, co každý odstavec dělá, příjemné pro snadnou analýzu, ale obecně by se komentáře měly zaměřit na otázky, na které nelze odpovědět pouhým přečtením kódu.

Testování

Jazyk

Různé aspekty jazykové podpory jsou také známé jako Lokalizace (L10n), internacionalizace (i18n), vícejazyčnost a globalizace. Celkově by vaše rozšíření mělo být plně použitelné a kompatibilní s neangličtinou a jazyky, které se nepíší zleva doprava.

  • MUST: Používejte správné funkce Lokalizace (wfMessage ) a nemějte v kódu pevně zakódované nepřeložitelné řetězce.
  • MUST: Použijte standardní internacionalizační systémy v MediaWiki.
  • MUST: Pro všechny zprávy rozhraní použijte jasnou a jedinečnou předponu pojmenovanou podle přípony.
  • MUST: Pravidelně posílejte zprávy a slučujte aktualizované překlady z Translatewiki.net . U rozšíření hostovaných ve Wikimedia Gerrit to za vás obvykle proaktivně udělají pracovníci translatewiki.net. Spustí automatický proces, který se přihlásí k odběru nových zpráv z vašeho rozšíření a také jednou denně automaticky exportuje a sloučí aktualizované překlady zpět do vašeho úložiště. Pokud se tak nestane do týdne, kontaktujte pracovníky TWN.
  • MUST: Přidejte qqq.json dokumentaci ke zprávě pro všechny zprávy, které existují v en.json
  • SHOULD: lint soubory zpráv v CI pomocí banana-checker.
  • SHOULD: Escapujte parametry do lokalizačních zpráv co nejblíže výstupu. Dokumentujte, zda funkce berou/přijímají wikitext vs. HTML.
  • OPTIONAL: Pokud rozšíření používá konkrétní termíny, napište si glosář těchto termínů a odkaz na něj z dokumentace zprávy. Příklad: Abstraktní Wikipedie/Glosář.

Dostupnost

Viz Průvodce přístupností pro vývojáře . Všimněte si, že tyto ještě nejsou začleněny do pokynů a pro účely rozšíření mohou být osvědčené postupy považovány za NEPOVINNÉ, čeká se na další diskusi.

Zabezpečení

Viz také Bezpečnost pro vývojáře .

  • MUST: Shelling by měl escapovat argumenty.
  • MUST: Všechny akce zápisu musí být chráněny proti Falšování požadavků napříč weby (CSRF).
  • MUST: Ujistěte se, že při refaktorování nebo psaní nového kódu jsou stále pokryty problémy související se soukromím (kontrolní uživatel, potlačení a odstranění revizí a protokolů).
  • SHOULD: Použijte standardní systém tokenů MediaWiki CSRF.
  • SHOULD: Po vyčištění HTML neupravujte (běžným vzorem je použití regulárního výrazu, ale to je špatné).
  • SHOULD: Nenačítejte žádné zdroje z externích domén. To je také potřeba pro soukromí a zlepšuje to výkon.
  • SHOULD: Vytvoření nových uživatelských práv nebo skupin uživatelů nejprve prodiskutujte s komunitou. Přidání uživatelských práv je v kódu snadné, ale musí být pečlivě zváženo s ohledem na to, kdo může tato práva udělovat a kdo tato práva standardně nese.
TODO: Měla by rozšíření vytvářet skupiny uživatelů ve výchozí konfiguraci? Nebo bychom měli ve výchozím nastavení ponechat nová práva nepřiřazená nebo přiřazená základním skupinám?


Neobjevujte / nezneužívejte MediaWiki

Jako obecný princip se nepoužívá nebo nesouhlasí s funkcemi, které již poskytuje jádro MediaWiki.

  • MUST: Používejte funkce/obálky MediaWiki pro věci jako WebRequest vs. $_GET, atd.
  • MUST: Kde je to možné, používejte háčky , nikoli zástupná řešení nebo nové způsoby úpravy, vkládání nebo rozšiřování funkcí.
  • MUST Použijte metody ověřování/čištění MediaWiki např. ve třídách Html a Sanitizer.
  • MUST: Nevypínejte mezipaměť analyzátoru, pokud k tomu nemáte opravdu dobrý důvod.
  • MUST: Použijte Composer pro správu PHP knihovny třetí strany.
  • SHOULD: Neimplementujte kolo. Preferujte stabilní a dobře udržované knihovny, pokud existují.
  • SHOULD: Nezakazujte OutputPage . (T140664)
  • SHOULD: Pokud existuje abstrakce (např. Příručka:ContentHandler ), použijte ji místo háčků.
  • SHOULD: Nedělejte si věci těžší – používejte standardní funkce, jako jsou testy extension.json/automatické zjišťování PHPUnit.
  • SHOULD: Použijte globální konfiguraci MediaWiki, jako je režim pouze pro čtení.


Nezařazené

  • Měli byste mít znalost, kdy použít metody ParserOutput vs. podobné metody na OutputPage.

Meta

Tato stránka byla poprvé vytvořena během Wikimania Hackathon 2017.

Související odkazy

Retrieved from "https://www.mediawiki.org/w/index.php?title=Best_practices_for_extensions/cs&oldid=6480307"