Psaní rozšíření pro nasazení

Tato stránka dokumentuje kroky potřebné pro správce nebo správce kódu rozšíření MediaWiki, aby toto rozšíření prošlo procesem kontroly před případným nasazením rozšíření na wiki Wikimedie. Vše, co je nasazeno na serverech Wikimedie, musí být zkontrolováno z hlediska bezpečnosti a škálovatelnosti. Tam, kde je níže uvedeno slovo "rozšíření", je synonymem "vzhled" nebo "kód".

Psaní rozšíření pro nasazení může být časově náročný projekt. Jakékoli zainteresované straně se doporučuje, aby zahájila proces dlouho před termínem.

Můžete si prohlédnout seznam všech rozšíření čekajících na kontrolu.

Jakmile rozšíření projde kontrolami, může Wikimedia Foundation Release Manager naplánovat nasazení rozšíření.

Kontrolní seznam/proces

Obecné předpoklady a očekávání

Postupujte podle obecných pokynů a doporučení pro psaní rozšíření. Přečtěte si Konvence kódování, Kontrolní seznam předběžného potvrzení, Pokyny k výkonu a Bezpečnost pro vývojáře a ujistěte se, že váš kód je v souladu s těmito pokyny.

• WMF stewardship: Find at least one WMF team (or staff member on behalf of their team) to agree to offer basic support for the extension for when it's deployed to Wikimedia Production. Do this step before any other steps. Due to technical debt, WMF capacity to steward extensions is limited.
• Dokumentace:
  • Vytvořte Extension:My Extension stránku ve jmenném prostoru Extension : na mediawiki.org pro dokumentaci pro vývojáře a lidi, kteří budou instalovat nebo konfigurovat rozšíření. Použijte k tomu Template:Extension . Můžete použít pole níže, které vám s tím pomůže.
    
    
  • Vytvořte Help:Extension:My Extension stránku ve jmenném prostoru Help:Extension: na mediawiki.org pro dokumentaci koncového uživatele vašeho rozšíření. Propojte jej se stránkou Extension:My Extension výše. Viz také Příručka:Vývoj rozšíření#dokumentace nápovědy . Příklad: Nápověda:VisualEditor/Uživatelská příručka . Screencast může být užitečný při vysvětlení, jak věci fungují. Můžete použít pole níže, které vám s tím pomůže.
    
    
• Hosting kódu - Požádejte o nové úložiště Git/Gerrit pro uložení zdrojového kódu vašeho rozšíření. Gerrit je místo, kde proběhne veškerá kontrola kódu.
• Sledování problému: - Požádejte o projekt na Phabricator u, abyste mohli sledovat chyby a požadavky na funkce pro vaše rozšíření. Získejte upozornění na nové úkoly nahlášené ve vašem projektu.
• Správcovství - Přidejte projekt na stránku Developers/Maintainers a uveďte, kdo bude odpovědný za jeho dlouhodobé vedení a údržbu.
• Lokalizace - Vaše rozšíření bude muset být přeložitelné na Translatewiki.net , než bude možné jej kdekoli nasadit. To vyžaduje, aby váš kód měl správné soubory i18n atd.
  • Jakmile je rozšíření nasazeno na testovací wiki Wikimedie, mělo by být přidáno do skupiny "Extensions used by Wikimedia - Upcoming" (rozšíření používaná Wikimedií – nadcházející).
  • Jakmile je rozšíření nasazeno na jakékoli produkční wiki Wikimedie, mělo by být přidáno do jedné z dalších skupin "Rozšíření používaná Wikimedií - *": "Main" (hlavní) pro rozšíření, která se používají na všech wikinách nebo jsou jinak velmi nápadná. "Advanced" (pokročilé) pro rozšíření pro pokročilé uživatele nebo rozšíření, která fungují pouze na některých wikinách. A tak dále. Soubory zpráv a rozšíření API, které jsou určeny pouze pro vysoce technické osoby, musí být ve skupině "Technical" (technické).
• Nasazení brány a příznaky funkcí - Wikimedia Foundation provozuje téměř tisíc wikin ve stovkách jazyků. Když nasadíme kód do našeho clusteru, povolíme rozšíření na základě wiki-by-wiki a často je pro každé nakonfigurujeme jinak. Rozšíření by měla mít příznaky funkcí (např. wgMaxGeoSearchRadius) pro zapnutí a vypnutí konkrétního chování nebo konfiguraci některé části rozšíření, pokud to dává smysl. Když jsou rozšíření nasazena, budou chráněna globální konfigurační proměnnou specifickou pro Wikimedii, jako je wmgUseEventLogging. To umožňuje rozšíření nasadit na podmnožinu wikin (například test a test2), aniž by to ovlivnilo všechny wikiny. Pro referenci můžete prohledávat stávající velmi velké CommonSettings.php a InitialiseSettings.php.
• Testování jednotek - Buďte milí, připravte se na dostatečné automatizované testování. Různé části kódu vyžadují různé typy testování. Konkrétně se podívejte na Příručka:Testování PHP kódu a Příručka:Testování jednotek JavaScriptu .
• Schéma databáze - Více vám řekne Zásady databáze MediaWiki . Pokud váš kód vyžaduje změnu schématu (např. nový sloupec ve stávající tabulce), ať už pro jádro, nebo rozšíření, mějte na paměti, že ke změně schématu může na clusteru Wikimedia dojít až po letech. Pokud je to možné, vyhněte se změnám schématu.
• Kompatibilita - Vaše rozšíření musí být kompatibilní se všemi rozšířeními nasazenými v clusteru Wikimedie.
• Hostování testovací verze - Toolforge nebo Cloud VPS lze použít k hostování testovacích wikiN s nainstalovaným rozšířením pro testování a ukázky. Další informace naleznete v příručce Začínáme s cloudovými službami.
• Recenze kódu - Během celého procesu vývoje a nasazení byste měli úzce spolupracovat s důvěryhodnými a zavedenými vývojáři MediaWiki (ideálně správci jádra nebo rozšíření, které již byly nasazeny na stránky Wikimedie), abyste se ujistili, že jste obeznámeni se specifickými požadavky a zvláštnostmi pro psaní kódu nasazeného na Wikimedii. Pokud nemáte na mysli žádné konkrétní vývojáře, zeptejte se v IRC nebo na konferencích vývojářů . Všechna rozšíření nasazená na Wikimedii a rozšíření, která jsou v procesu nasazování, musí dodržovat Gerrit/Pravidla přednostního práva .

Po provedení výše uvedených kroků zvažte získání podpory komunity pro váš nápad:

• Podporu komunity lze projevit aktivní diskusí o potřebě rozšíření na wiki a zdokumentováním odpovědí. Pokud neexistuje aktivní podpora komunity, lze podporu budovat prostřednictvím diskusí a návrhů.
• Zveřejněte svůj nápad na wikitech-l mailing listu, abyste získali zpětnou vazbu od zkušených vývojářů a Wikimedianů. Lidé vás mohou odkázat na jiné rozšíření, které se již používá, jehož funkce duplikuje to, co chcete, nebo by se daly snadno rozšířit, aby dělaly to, co chcete. V takovém případě byste měli použít Git k práci na rozšíření, které se již používá.
• Sdělte své nápady a plány dotčených wikinami, abyste získali podporu, návrhy a další zpětnou vazbu.
• Aby byly níže uvedené kroky pro recenzenty jednodušší a rychlejší, doporučujeme vám také vytvořit roli MW-Vagrant pro rozšíření.

Pokud jste pozorně dodržovali výše uvedené rady a zpětnou vazbu od prvních recenzentů, měli byste mít s dalšími kroky menší problémy.

Příprava na nasazení

1. Vytvořte úlohu sledování produkčního nasazení v rámci Phabricatoru (v projektech #Wikimedia-Extension-setup a #Wikimedia-Extension-Review-Queue), abyste získali rozšíření do kontrolní fronty. Tento úkol by se měl týkat pouze samotného nasazení. Všechny problémy, které blokují nasazení, by měly být samostatnými dílčími úkoly (uvedenými v části „Graf úkolů“), které blokují tento nadřazený úkol.
2. Vaše chyba sledování nasazení by měla odkazovat na konsenzus komunity na wiki (anebo podporu/přání komunity) ohledně instalace rozšíření na konkrétní wiki, pokud je to možné.
3. Vyžádejte si a zapracujte zpětnou vazbu z následujících recenzí. Ty mohou být zahrnuty jako "kontrolní seznam" v popisu úlohy sledování produkčního nasazení (např. phab:T190716) nebo jako dílčí položky úlohy sledování produkčního nasazení. Všimněte si také, že ne každá recenze uvedená níže je tvrdým požadavkem pro produkční nasazení a že neexistuje žádné konkrétní pořadí recenzí, které je třeba dodržovat.
   • Případně recenzi od vlastníka produktu pro dotčenou oblast. Pokud si nejste jisti, kdo by to mohl být, bude pravděpodobně dobré obrátit se na různé technické týmy v rámci odvětví produktů nebo technologií, které vás požádají o další informace a pokyny.
   • Recenze designu, je-li k dispozici.
   • Recenze funkce beta , pokud vaše rozšíření přidává funkci beta.
   • Kontrola zabezpečení aplikace : K otevření požadavku vytvoření úkolu kontroly zabezpečení aplikace a jeho označení jako dílčího úkolu úlohy sledování produkčního nasazení (prostřednictvím "Edit Task" (pravit úlohu)v pravém horním rohu ). Kontrola připravenosti zabezpečení může blokovat produkční nasazení v závislosti na podrobnostech požadavku a jeho výsledcích.
   • Kontrola zabezpečení pro všechny nové externí závislosti , které by pak měly být přidány k mediawiki/vendor. Zde je základní seznam bezpečnostní tým jej obvykle kontroluje při kontrole kódu třetí strany/dodavatele.
   • {{$1|Recenze výkonu}}. Tato recenze obvykle neblokuje produkční nasazení.
   • Pokud máte důvody se domnívat, že je potřeba revize databáze, vytvořte požadavek ve Phabricatoru.
   • IMPORTANT: Jakékoli závažné (tj. blokující) problémy identifikované ve výše uvedených recenzích musí být vyřešeny před jakýmkoli pokusem o nasazení kódu do produkce.
4. Požádejte o nasazení do Beta Cluster . Další informace naleznete níže v #Nasazení do Beta clusteru. I když je důrazně doporučeno nechat si před nasazením beta clusteru provést kontrolu připravenosti na zabezpečení , načasování různých milníků projektu a povaha samotného projektu tomu nemusí vyhovovat. V tomto případě je nejlepší prodiskutovat všechna navrhovaná nasazení beta clusteru s týmem zabezpečení mimo jakékoli požadované kontroly. Mít řádný a dlouhodobý plán údržby pro kódovou základnu, který se nespoléhá na jednotlivé dobrovolníky, je často překážkou pro absolvování kontroly zabezpečení aplikace.
5. Ujistěte se, že je rozšíření automaticky větvené pomocí make-wmf-branch.
   • IMPORTANT: Neobdržení uspokojivého kontroly bezpečnostní připravenosti je blokátor tohoto kroku.
   • IMPORTANT: Udělejte to brzy! V ideálním případě alespoň tři týdny před cílovým datem nasazení, abyste zajistili, že vaše rozšíření bude přítomno jako submodul v požadovaných větvích. (Rozšiřující submodul musí být přítomen ve všech větvích aktuálně spuštěných v clusteru, jinak selže tvůrce mezipaměti lokalizace.)
6. Požádejte o datum/čas nasazení v úloze sledování nasazení, aby bylo přidáno do kalendáře nasazení.
   • "Vy" (osoba nebo osoby, které to řídí/požadují) budete muset být online (na IRC v #wikimedia-operations ^{připojit se}) a během nasazení k dispozici, abyste mohli reagovat na jakékoli problémy, které mohou nastat.

Tento seznam nastiňuje široký postup, který je třeba dodržovat, včetně požadavků, které by měly být splněny, ale nejedná se o "proces". Zejména činnost odesílání nového rozšíření do výroby nemá vlastníka WMF, což může ztěžovat hledání recenzí na související opravy. V případě problémů se doporučuje vyhledat lidi (viz Gerrit/Kontrola kódu/Získávání recenzí#Přidání recenzentů ). Vývojáři jsou upozorněni, že pouhé otevření úloh Phabricatoru a čekání na někoho, kdo se jim bude věnovat, pravděpodobně nebude dostatečné. Viz vysvětlení Martina Urbance na phab:T61245#9152895.

Nasazení do Beta Clusteru

Než povolíte nové rozšíření v produkci, musí být otestováno na Beta Clusteru. Zde jsou kroky potřebné k nasazení a povolení nového rozšíření v Beta verzi. (Pokud má vaše rozšíření více kroků/závislostí, řekněme Wikibase, nezapomeňte se před nasazením s někým poradit.)

Postup

1. Přidejte nový submodul rozšíření do gitu mediawiki/extensions repo, pokud v něm ještě není. Viz příklad. To povede k nasazení (nepoužití) kódu do Beta Clusteru.
2. Přesuňte konfiguraci CI svého rozšíření do sekce "Wikimedia production", přidejte šablonu úlohy "in-wikimedia-production" a ujistěte se, že má a předává všechny očekávané úlohy pro produkční kód. Viz příklad.
3. Přidejte své rozšíření do nástroje pro vydání json make-wmf-branch alespoň dva týdny před cílovým datem pro aktivaci v Beta Clusteru. Rozšíření přidá jako podmodul mediawiki/core, když se týdenní větev nasazení přeruší, a kód bude nasazen (nepoužit) do výroby (viz vysvětlení v dalším kroku). Viz příklad.
4. Přidejte své rozšíření na extension-list. Viz příklad. To vyžaduje, aby byl kód přítomen na každé větvi běžící v produkci, protože extension-list se používá k vytvoření databáze CDB pro soubory i18n v beta i produkční verzi.
5. Přidejte proměnnou konfigurace rozšíření na InitialiseSettings.php a nastavte ji jako výchozí false. Viz příklad.
6. Přidejte konfigurační proměnnou rozšíření (stejně jako v předchozím kroku) na InitialiseSettings-labs.php a nastavte ji na true na wiki Beta Cluster, kde chcete, aby byla. Možná ji budete chtít vypnout pro loginwiki (která nemá většinu rozšíření). Viz příklad.
7. Načtěte rozšíření na CommonSettings-labs.php. Viz příklad.

Poznámky

Beta Cluster používá stejný adresář wmf-config v úložišti operations/mediawiki-config jako produkce, ale servery Beta Cluster navíc načítají soubory InitialiseSettings-labs.php a CommonSettings-labs.php, takže můžete mít nastavení, která se vztahují pouze na Beta Cluster. Přečtěte si více o těchto konfiguračních souborech). Při testování na Beta Clusteru před uvedením do používání mohou tyto hodnoty přepsat wmgUseMyExtension a nastavit jej na true na jedné nebo více wikinách Beta Cluster. (Jakmile bude vaše rozšíření používáno v produkčních wiki odpovídajících Beta Clusteru, můžete pravděpodobně odstranit přepsání -labs.php.)

Beta Cluster spouští kód z hlavní větve v Gitu. Kód byste měli sloučit do hlavní větve brzy a často, abyste mohli tento kód co nejúplněji uplatnit v Beta Clusteru, než se dostane k široké veřejnosti. Pokud máte konkrétní dotazy ohledně používání Beta Clusteru, můžete poslat e-mail na Quality Assurance nebo se zeptat v #wikimedia-releng ^{připojit se} na IRC .

Vzhledy se řídí stejným procesem (ale v úložišti mediawiki/skins).

Po nasazení do provozu

• Aktualizujte svou Extension:My Extension stránku na mediawiki.org přidáním {{OnWikimedia}} šablony.

Související odkazy

Prezentace Roana Kattouwa o bezpečnosti.

• Projekt v pořadí k přezkoumání
• Requests for comment – místo pro diskusi o nápadech na velké projekty pro MediaWiki
• How to deploy code#Case 1d: new extension – podrobnosti o nasazení nového rozšíření na clusteru Wikimedie
• Žádost o změny konfigurace wiki a Omezení změn konfigurace