Prispievanie do modulov Weblate¶
Okrem hlavného repozitára sa Weblate skladá z niekoľkých Python modulov. Všetky tieto dodržiavajú rovnakú štruktúru a táto dokumentácia ich všetky pokrýva.
Napríklad toto pokrýva:
wlc, klientska knižnica Python, pozri Klient Weblate
translation-finder, používa sa na objavovanie preložiteľných súborov v repozitári
language-data, definície jazykov pre Weblate, pozri Definície jazykov
translate-toolkit, knižnica na manipuláciu s prekladovými súbormi, pôvodne knižnica tretej strany, teraz ju udržiava Weblate.
Rozširovanie vstavaných definícií jazykov¶
Definície jazykov sú v repozitári language-data.
Radi privítame, ak pridáte chýbajúce definície jazykov do languages.csv, ostatné súbory sú generované z tohto súboru. Stĺpce v súbore CSV zodpovedajú Definície jazykov.
Licencia a autorské práva¶
Pri prispievaní kódom projektu súhlasíte s tým, že vaše zmeny a nový kód budú pod licenciou repozitára, GPL-3.0-or-later, pokiaľ nie je uvedené a dohodnuté inak. Nové zdrojové súbory by mali nasledovať existujúci štýl hlavičky autorských práv a licencie SPDX.
Použite inú licenciu iba vtedy, ak na to existuje zámerný dôvod, napríklad súbory zdieľané s repozitármi používajúcimi permisívnejšie licencie.
Viď aj
Licencia Weblate vysvetľuje licencovanie podrobnejšie.
Písanie dobrej záplaty¶
Píšte oddelené zmeny¶
Je otravné, keď dostanete masívnu záplatu, ktorá má vraj opraviť 11 rôznych problémov, ale diskusie a názory nesúhlasia s 10 z nich alebo 9 z nich už bolo opravených inak. Potom osoba, ktorá zlúči túto zmenu, musí extrahovať jedinú zaujímavú záplatu niekde z masívnej kopy zdrojov, a to vytvára veľa extra práce.
V ideálnom prípade by každá oprava, ktorá rieši problém, mala byť vo vlastnej záplate/zápisre s vlastným popisom/správou zápisu, ktorá presne uvádza, čo opravujú, aby všetky zmeny mohli byť selektívne aplikované správcom alebo inými zainteresovanými stranami.
Okrem toho, oddelené zmeny umožňujú oveľa lepšie bisectovanie na sledovanie problémov a regresie v budúcnosti.
Dokumentácia¶
Dokumentácia môže byť únavná úloha; je však potrebné, aby ju niekto dokončil. Veci to veľmi uľahčí, ak predložíte dokumentáciu spolu so zmenami kódu. Nezabudnite zdokumentovať metódy, komplexné bloky kódu alebo funkcie viditeľné pre používateľa.
Testovacie prípady¶
Testy nám umožňujú rýchlo overiť, že funkcie pracujú tak, ako majú. Na udržanie tejto situácie a jej zlepšenie musia byť všetky nové funkcie a funkcie, ktoré sa pridávajú, testované v testovacej sade. Každá pridaná funkcia by mala dostať aspoň jeden platný testovací prípad, ktorý overí, že funguje podľa dokumentácie.
Správy zápisov¶
Zápisy Git by mali dodržiavať špecifikáciu Conventional Commits.
Kontrola typov¶
Akýkoľvek nový kód by mal využívať typové nápovedy PEP 484. Na ich kontrolu používame mypy, pretože má plugin pre Django, ktorý robí kontrolu typov aplikácií Django praktickou.
Nový a zmenený kód by nemal zavádzať nové zlyhania mypy, kde to súčasná podpora typovania Django umožňuje. Kódová základňa ešte nie je úplne pokrytá typovými anotáciami a niektoré konštrukcie Django je ťažké presne anotovať. CI preto vynucuje mypy iba pre vybrané moduly a ostatné zistenia hlási samostatne.
Štandard kódovania a linting kódu¶
Kód by mal dodržiavať smernice kódovania PEP 8 a mal by byť formátovaný pomocou formátovača kódu ruff.
Na kontrolu kvality kódu môžete použiť ruff, jeho konfigurácia je uložená v pyproject.toml.
Pri potláčaní diagnostiky ruff uprednostnite # ruff: ignore[rule-name] s ľudsky čitateľným názvom pravidla. Umiestnite komentár na riadok nad logický príkaz alebo blok, ak to nerozširuje rozsah potlačenia. Komentár nechajte inline, ak by jeho presun zmenil rozsah, ovplyvnil triedenie importov alebo by sa dostal medzi komentár disable-next iného nástroja a kód, na ktorý cieli.
Najjednoduchší prístup na vynútenie všetkého tohto je nainštalovať prek. Toto je reimplementácia nástroja pre-commit tretej strany, ktorý používa Weblate. Je zahrnutý vo vývojových závislostiach deklarovaných v pyproject.toml, takže inštalácia týchto závislostí sprístupní prek.
Na manuálnu kontrolu všetkých súborov spustite:
uv run prek run --all-files
Ak preferujete pôvodného klienta pre-commit, používa rovnakú konfiguráciu z .pre-commit-config.yaml.
Bezpečné kódovanie¶
Každý kód pre Weblate by mal byť písaný s ohľadom na Princípy bezpečnosti v dizajne.
Smernice pre AI¶
Keď prispievate obsahom do projektu, dávate nám povolenie používať ho tak, ako je, a musíte sa uistiť, že máte povolenie ho nám distribuovať. Odovzdaním zmeny nám súhlasíte s tým, že zmeny môžu a mali by byť prijaté projektom a redistribuované pod licenciou projektu. Autori by si mali byť explicitne vedomí, že bremeno je na nich, aby zabezpečili, že do projektu nebude odovzdaný žiadny nelicencovaný kód.
Toto je nezávislé od toho, či sa používa AI alebo nie.
Keď prispievate pull requestom, mali by ste sa samozrejme vždy uistiť, že návrh je dobrej kvality a vynaložili ste maximálne úsilie v súlade s našimi smernicami. Základné pravidlo je, že ak niekto zistí, že príspevok bol vytvorený s pomocou AI, máte viac práce.
Môžeme prijať kód napísaný s pomocou AI do projektu, ale kód musí stále dodržiavať štandardy kódovania, byť jasne napísaný, zdokumentovaný, obsahovať testovacie prípady a dodržiavať všetky bežné požiadavky, ktoré máme.