Antimatter

Współpraca

Zgłoszenia błędów, pomysły, tłumaczenia, dokumentacja i kod są zawsze mile widziane. Ta strona wyjaśnia, gdzie rozmawiać, jak wysłać zmianę, jakie konwencje stosuje kod oraz jakie zasady obowiązują w przypadku problemów bezpieczeństwa i licencji.

Gdzie rozmawiać

Wszystko zaczyna się w repozytorium społeczności, niezależnie od tego, która część Antimatter jest przedmiotem rozmowy:

  • Błędy i prośby o nowe funkcje: utwórz zgłoszenie i wybierz Bug report, Feature request lub Plugin or integration request. Najpierw wyszukaj istniejące zgłoszenia; jeśli Twoje już istnieje, dodaj do niego kciuk w górę lub swoje uwagi.
  • Pytania i pomysły: Dyskusje, w kategoriach Q&A lub Ideas.
  • Przed większą zmianą utwórz zgłoszenie lub dyskusję, aby najpierw ustalić podejście. Pozwoli to uniknąć wysłania pull requesta, który nie może zostać scalony w obecnej formie.

Dobrym punktem wyjścia są problemy oznaczone etykietami good first issue i help wanted. W komentarzu poinformuj, że pracujesz nad danym problemem. Nowe problemy otrzymują etykietę status/triage, a następnie status/accepted, status/planned lub status/wontfix. Problemy pozostają w repozytorium społeczności niezależnie od ich tematu: repozytoria kodu nie przyjmują zgłoszeń. Zaplanowane prace znajdują się w drodze rozwoju Antimatter.

Repozytoria i gałęzie

Kod znajduje się w organizacji AntimatterChat; lista repozytoriów znajduje się w sekcji Gdzie znajduje się kod. W każdym repozytorium:

  • main to gałąź domyślna, zawierająca kod Antimatter. Twórz od niej gałęzie i wysyłaj do niej pull requesty.
  • Repozytoria wywiedzione z Mattermost mają również gałąź upstream, która jest lustrem kodu Mattermosta, używanym do włączania jego zmian. Nie opieraj na niej swojej pracy.

Plik README każdego repozytorium wyjaśnia, jak je budować i testować. W przypadku serwera i interfejsów webowych zobacz Budowanie ze źródła; w przypadku aplikacji, Budowanie, instalacja i debugowanie.

Pull requesty

  1. Stwórz fork repozytorium i gałąź od main.
  2. Ogranicz każdą prośbę o połączenie (pull request) do jednej zmiany. Małe prośby o połączenie są recenzowane szybciej.
  3. Stosuj się do stylu kodu w otoczeniu i dodawaj lub aktualizuj testy, gdy ma to sens.
  4. Opisz, co zmieniłeś i dlaczego, oraz podaj link do problemu, który rozwiązujesz: Fixes AntimatterChat/community#123.
  5. Upewnij się, że kontrole przechodzą. Utrzymujący (maintainer) recenzuje prośbę o połączenie i może poprosić o zmiany.

W repozytorium serwera wypełnij szablon prośby o połączenie: Podsumowanie oraz blok Uwaga do wydania, który musi zawsze być obecny. Wpisz w nim NONE, gdy zmiana nie dotyczy API, konfiguracji, schematu bazy danych ani widocznego zachowania.

Przyczyniając się do projektu, wyrażasz zgodę na to, że Twój wkład jest licencjonowany na podstawie licencji repozytorium, do którego przyczyniasz się.

Zobowiązania i styl kodu

Zobowiązania

Komunikaty zobowiązań w historii to jedno krótkie zdanie mówiące, co się zmienia, pisane z małej litery i bez kropki na końcu. Zmiany dotyczące jednej części są poprzedzone jej nazwą, na przykład Fusion: a compact conversation header on phones lub Server: community attributes, and admin-only user attributes. Jedno zobowiązanie na zmianę; wyjaśnij powody w treści, gdy nie są oczywiste.

Serwer (Go)

  • Uruchom make check-style w server/ przed wysłaniem.
  • Nigdy nie uruchamiaj bezpośrednio go mod tidy; uruchom make modules-tidy.
  • W ścieżkach żądań loguj za pomocą loggera żądania. W warstwie magazynu (store) przyjmuj request.CTX, a nie context.Context.
  • Nowe punkty końcowe API umieszczaj w server/channels/api4, z ich typami w server/public/model oraz, idealnie, metodą w model.Client4 i w kliencie TypeScript.

Interfejsy webowe (TypeScript i React)

  • Uruchom make check-style i make check-types w webapp/.
  • Klasyczny interfejs stosuje się do webapp/STYLE_GUIDE.md: komponenty funkcjonalne, hooki dla Reduxa, zmienne motywu dla kolorów, dostępny znacznik (markup).
  • Komponenty Fusion znajdują się w webapp/fusion/src/fusion, a ich style w webapp/fusion/src/fusion/styles. Budują nazwy klas za pomocą pomocnika am() i używają tokenów projektowych Fusion; stosuj się do plików znajdujących się obok Twoich.
  • Nie dodawaj nowych globalnych zmiennych window.* dla aplikacji. Nowe narzędzia skierowane do aplikacji umieszczaj pod window.WebappUtils, jak wyjaśnia webapp/AGENTS.md.
  • Zmiana w rejestrze aplikacji (plugins/registry.ts) zwykle należy do kopii obu interfejsów.

Tłumaczenia

Antimatter i jego wbudowane aplikacje są tłumaczone na 37 języków. Współtwórcy dodają angielskie łańcuchy znaków, a pozostałe języki są aktualizowane partiami.

Dodawanie łańcucha znaków do interfejsów webowych

  1. Napisz go z identyfikatorem i dosłownym tekstem angielskim: formatMessage({id: 'fusion.channelMenu.settings', defaultMessage: 'Channel settings'}) lub <FormattedMessage id='…' defaultMessage='…'/>. Angielski tekst wyświetlany w aplikacji pochodzi z defaultMessage.
  2. Uruchom make i18n-extract w webapp/ (lub npm run i18n-extract w webapp/fusion lub webapp/channels). Aktualizuje to src/i18n/en.json danego pakietu.
  3. Wypełnij description nowego wpisu w en.json: gdzie łańcuch znaków się pojawia i jak jest używany. Stanowi on kontekst, z którego korzystają tłumacze, zarówno ludzcy, jak i maszynowi.

npm run i18n-extract:check kończy się błędem, gdy en.json jest nieaktualny w stosunku do kodu.

Dodawanie łańcucha znaków do serwera

  1. Użyj identyfikatora w kodzie, na przykład model.NewAppError(…, "app.community_attributes.invalid.app_error", …) lub i18n.T("…").
  2. Uruchom make i18n-extract w server/. Dodaje to identyfikator do server/i18n/en.json w odpowiedniej kolejności.
  3. Napisz angielskie translation oraz description nowego wpisu.

Inne języki

Każdy język ma własny plik obok en.json (fr.json, pt-BR.json, zh-TW.json…). Aby zgłosić błędny tłumaczenie, otwórz problem (issue) w repozytorium społecznościowym, podając język, tekst i miejsce, w którym się pojawia.

Wbudowane aplikacje przechowują swoje łańcuchy znaków w webapp/i18n/; zobacz Tłumaczenia na stronie aplikacji.

Dokumentacja i ta witryna

Ta witryna i jej dokumentacja znajdują się w repozytorium antimatter.chat. Strony to fragmenty HTML w src/pages/; python3 src/build.py buduje witrynę. Poprawki i brakujące wyjaśnienia są mile widziane jako problemy (issues) lub żądania połączenia (pull requests).

Problemy bezpieczeństwa

Nigdy nie zgłaszaj problemu bezpieczeństwa w publicznym problemie (issue), dyskusji ani żądaniu połączenia (pull request).

Zgłoś to prywatnie za pomocą mechanizmu zgłaszania podatności GitHuba: otwórz zakładkę Bezpieczeństwo w odpowiednim repozytorium (na przykład serwera) i wybierz Zgłoś podatność. Jeśli nie wiesz, które repozytorium jest dotknięte podatnością, zgłoś ją w repozytorium społeczności. Podaj komponent i jego wersję, to, co może zrobić napastnik, sposób odtworzenia problemu oraz wszelkie zależności od konfiguracji.

Utrzymujący odpowiedzą tam, będą informować Cię o postępach podczas naprawy i opublikują komunikat o podatności, gdy tylko wyjdzie poprawiona wersja. Prosimy o udzielenie im rozsądnego czasu przed publicznym ujawnieniem problemu. Poprawki trafiają do najnowszej wersji. Pełna polityka bezpieczeństwa znajduje się w polityce bezpieczeństwa.

Licencje

  • Serwer jest objęty licencją GNU Affero General Public License v3.0 (AGPL v3). W tym samym repozytorium narzędzia administracyjne i pliki konfiguracyjne (server/templates/, server/i18n/, server/public/ oraz webapp/) są objęte licencją Apache License 2.0. Zobacz LICENSE.txt i NOTICE.txt.
  • Aplikacje: własne aplikacje Antimatter, takie jak Ankiety, są objęte licencją AGPL v3; aplikacje rozwinięte z Mattermost zachowują swoją oryginalną licencję. Każde repozytorium wskazuje to w swoim pliku LICENSE.
  • Aplikacje na komputery stacjonarne i urządzenia mobilne są objęte licencją Apache License 2.0. Repozytorium Docker jest objęte licencją Apache License 2.0, z wyjątkiem pliku Dockerfile, który jest objęty licencją AGPL v3.

Licencja AGPL oznacza, że jeśli uruchamiasz zmodyfikowany serwer Antimatter dla innych osób przez sieć, musisz udostępnić im kod źródłowy swoich zmian. Antimatter jest oparty na Mattermost; nie jest powiązany ani wspierany przez Mattermost, Inc.

Wszyscy uczestnicy przestrzegają kodeksu postępowania.