Antimatter

Příspěvky do projektu

Vítejte s chybami, nápady, překlady, dokumentací i kódem. Tato stránka vysvětluje, kde se bavit, jak odeslat změnu, jaké konvence kód dodržuje a jaké pravidla platí pro bezpečnostní problémy a licence.

Kde se bavit

Všechno začíná v komunitním repozitáři, bez ohledu na to, jakou část Antimatter se týká:

  • Chyby a požadavky na funkce: vytvořte issue a vyberte Bug report, Feature request nebo Plugin or integration request. Nejprve prohledejte existující issues; pokud je vaše tam, přidejte palec nahoru nebo své podrobnosti.
  • Dotazy a nápady: v Diskuzích, v kategoriích Q&A nebo Ideas.
  • Před větším zásahem vytvořte issue nebo diskusi, abyste se nejprve dohodli na přístupu. Ušetříte tím pull request, který by se v daném stavu nedal sloučit.

Dobré místo pro začátek jsou problémy označené štítky good first issue a help wanted. V komentáři napište, že na jednom z nich pracujete. Nové problémy dostávají štítek status/triage, poté status/accepted, status/planned nebo status/wontfix. Problémy zůstávají v komunitním repozitáři bez ohledu na jejich obsah; repozitáře s kódem problémy nepřijímají. Naplánovaná práce je na Antimatter roadmap.

Repozitáře a větve

Kód je v organizaci AntimatterChat; Kde se kód nachází obsahuje seznam repozitářů. V každém repozitáři:

  • main je výchozí větev a obsahuje kód Antimatter. Vytvářejte od ní větve a odesílejte pull requesty do ní.
  • Repozitáře viděné z Mattermost mají také větev upstream, zrcadlo kódu Mattermost používané k přebírání jejich změn. Nezakládajte na ní svou práci.

README každého repozitáře vysvětluje, jak ho sestavit a testovat. Pro server a webové rozhraní viz Sestavení ze zdrojového kódu; pro aplikace viz Sestavení, instalace a ladění.

Pull requesty

  1. Vytvořte fork repozitáře a z větve main odvoďte novou větev.
  2. Každou pull request omezte na jednu změnu. Menší pull requesty se recenzují rychleji.
  3. Držte se stylu okolního kódu a tam, kde to dává smysl, přidejte nebo aktualizujte testy.
  4. Popište, co jste změnili a proč, a připojte odkaz na issue, kterou změna řeší: Fixes AntimatterChat/community#123.
  5. Ujistěte se, že všechny kontroly proběhly úspěšně. Údržbář repozitáře pull request zkontroluje a může požádat o úpravy.

V repozitáři serveru vyplňte šablonu pull request: Shrnutí a blok Poznámka k vydání, který musí být vždy přítomen. Pokud změna neovlivňuje API, konfiguraci, schéma databáze ani viditelné chování, vložte do něj NONE.

Přispěním souhlasíte s tím, že vaše příspěvky jsou licencovány pod licencí repozitáře, do kterého přispíváte.

Commits a styl kódu

Commits

Zprávy o změnách v historii jsou jednou krátkou větou popisující, co se změnilo, s velkým počátečním písmenem a bez tečky na konci. Změny v jedné části se označují jejím názvem, například Fusion: a compact conversation header on phones nebo Server: community attributes, and admin-only user attributes. Jedna změna na jeden commit; důvody vysvětlujte v těle zprávy, pokud nejsou zřejmé.

Server (Go)

  • Před pushem spusťte make check-style v adresáři server/.
  • Nikdy nespouštějte přímo go mod tidy; použijte make modules-tidy.
  • V request path logujte pomocí loggeru requestu. V vrstvě store přejímejte request.CTX, ne context.Context.
  • Nové API endpointy patří do server/channels/api4, jejich typy do server/public/model a ideálně metoda do model.Client4 a do TypeScript klienta.

Webové rozhraní (TypeScript a React)

  • V adresáři webapp/ spusťte make check-style a make check-types.
  • Klasické rozhraní se řídí podle webapp/STYLE_GUIDE.md: funkční komponenty, hooks pro Redux, proměnné tématu pro barvy, přístupné markup.
  • Komponenty Fusion se nacházejí v webapp/fusion/src/fusion, jejich styly v webapp/fusion/src/fusion/styles. Tvoří názvy tříd pomocí helperu am() a používají design tokens Fusion; držte se souborů, které jsou vedle vašich.
  • Pro aplikace nepřidávejte nové globální proměnné window.*. Nové utility pro aplikace patří pod window.WebappUtils, jak je vysvětleno v webapp/AGENTS.md.
  • Změna v registru aplikací (plugins/registry.ts) se obvykle týká kopií v obou rozhraní.

Překlady

Antimatter a jeho vestavěné aplikace jsou přeloženy do 37 jazyků. Přispěvatelé přidávají anglické řetězce; ostatní jazyky se aktualizují ve skupinách.

Přidání řetězce do webových rozhraní

  1. Napište ho s ID a doslovným anglickým textem: formatMessage({id: 'fusion.channelMenu.settings', defaultMessage: 'Channel settings'}) nebo <FormattedMessage id='…' defaultMessage='…'/>. Anglický text zobrazený v aplikaci pochází z defaultMessage.
  2. Spusťte make i18n-extract v webapp/ (nebo npm run i18n-extract v webapp/fusion nebo webapp/channels). Aktualizuje src/i18n/en.json daného balíčku.
  3. Vyplňte description nové položky v en.json: kde se řetězec objevuje a jak se používá. Je to kontext, na jehož základě pracují překladatelé, ať už lidské, nebo strojové.

npm run i18n-extract:check selže, pokud je en.json neaktuální vzhledem k kódu.

Přidání řetězce na serveru

  1. V kódu použijte ID, například model.NewAppError(…, "app.community_attributes.invalid.app_error", …) nebo i18n.T("…").
  2. Spusťte make i18n-extract v server/. Přidá ID do server/i18n/en.json ve správném pořadí.
  3. Napište anglický translation a description nové položky.

Ostatní jazyky

Každý jazyk má svůj soubor vedle en.json (fr.json, pt-BR.json, zh-TW.json…). Chcete-li nahlásit nesprávný překlad, otevřete issue v komunitním repozitáři s jazykem, textem a místem, kde se objevuje.

Vestavěné aplikace si své řetězce drží v webapp/i18n/; viz Překlady na stránce aplikací.

Dokumentace a tento web

Tento web a jeho dokumentace jsou v repozitáři antimatter.chat. Stránky jsou HTML fragmenty v src/pages/; python3 src/build.py sestaví web. Opravy a chybějící vysvětlení jsou vítány jako issues nebo pull requests.

Bezpečnostní problémy

Bezpečnostní problém nikdy nenahlázejte v veřejném issue, diskusi nebo pull requestu.

Nahlaste to soukromě pomocí funkce pro hlášení zranitelností na GitHubu: otevřete záložku Zabezpečení v dotčeném repozitáři (například serveru) a zvolte Nahlásit zranitelnost. Pokud nevíte, který repozitář je dotčen, nahlaste to v komunitním repozitáři. Uveďte komponentu a její verzi, co by útočník mohl udělat, jak se to dá reprodukovat a od jakého nastavení to závisí.

Údržbáři na to tam odpovídají, informují vás o průběhu opravy a po vydání verze s opravou zveřejní oznámení. Prosíme, dejte jim rozumný čas, než problém sami zveřejníte. Opravy se dostávají do nejnovější verze. Kompletní politika je v bezpečnostní politice.

Licence

  • Server je pod licencí GNU Affero General Public License v3.0 (AGPL v3). Ve stejném repozitáři jsou administrativní nástroje a konfigurační soubory (server/templates/, server/i18n/, server/public/ a webapp/) pod licencí Apache License 2.0. Viz LICENSE.txt a NOTICE.txt.
  • Aplikace: Vlastní aplikace Antimatter, jako je Hlasování, jsou pod licencí AGPL v3; aplikace odvozené z Mattermost si zachovávají původní licenci. Každý repozitář to uvádí v souboru LICENSE.
  • Desktopové a mobilní aplikace jsou pod licencí Apache License 2.0. Repozitář Docker je pod licencí Apache License 2.0, s výjimkou souboru Dockerfile, který je pod licencí AGPL v3.

Licence AGPL znamená, že pokud provozujete upravený server Antimatter pro jiné osoby přes síť, musíte jim nabídnout zdrojový kód vašich změn. Antimatter je založen na Mattermost; není s ním nijak spjat ani schválen společností Mattermost, Inc.

Všichni účastníci se řídí kodexem chování.