Antimatter

Вклад в проект

Мы приветствуем сообщения об ошибках, идеи, переводы, документацию и код. На этой странице описано, где обсуждать вопросы, как отправить изменения, какие соглашения соблюдаются в коде, а также правила сообщения о проблемах безопасности и лицензирования.

Где обсуждать

Всё начинается в репозитории сообщества, независимо от того, какая часть Antimatter вас интересует:

  • Ошибки и предложения функций: создайте issue и выберите Bug report, Feature request или Plugin or integration request. Сначала поищите среди существующих issue; если ваш вопрос уже есть, поставьте «палец вверх» или добавьте свои детали.
  • Вопросы и идеи: раздел Discussions, в категориях Q&A или Ideas.
  • Перед крупными изменениями создайте issue или обсуждение, чтобы сначала согласовать подход. Это поможет избежать pull request'а, который невозможно будет объединить в текущем виде.

Хорошей отправной точкой являются задачи с метками good first issue и help wanted. Сообщите в комментарии, что вы работаете над одной из них. Новые задачи получают метку status/triage, а затем status/accepted, status/planned или status/wontfix. Задачи хранятся в репозитории сообщества независимо от их содержания: репозитории с кодом не принимают задачи. Запланированные работы отражены в дорожной карте Antimatter.

Репозитории и ветки

Код находится в организации AntimatterChat; список репозиториев приведён в разделе Где находится код. В каждом репозитории:

  • main — ветка по умолчанию, содержащая код Antimatter. Создавайте ветки от неё и отправляйте pull request'ы в неё.
  • В репозиториях, форкнутых из Mattermost, также есть ветка upstream — зеркало кода Mattermost, используемое для получения их изменений. Не основывайте на ней свою работу.

README каждого репозитория объясняет, как его собирать и тестировать. Для сервера и веб-интерфейсов см. Сборка из исходников; для приложений — Сборка, установка и отладка.

Pull request'ы

  1. Сделайте форк репозитория и создайте ветку от main.
  2. В каждом pull request должен быть только один изменение. Небольшие pull request проверяются быстрее.
  3. Следуйте стилю кода, который вас окружает, и добавляйте или обновляйте тесты там, где это имеет смысл.
  4. Опишите, что вы изменили и почему, и укажите ссылку на issue, который вы исправляете: Fixes AntimatterChat/community#123.
  5. Убедитесь, что проверки проходят. Мейнтейнер проверит pull request и может запросить изменения.

В репозитории сервера заполните шаблон запроса на слияние: раздел Сводка и блок Release Note, который должен присутствовать всегда. Если изменения не затрагивают API, конфигурацию, схему базы данных или видимое поведение, укажите в этом блоке NONE.

Внося вклад, вы соглашаетесь, что ваш вклад лицензируется по лицензии репозитория, в который вы вносите вклад.

Коммиты и стиль кода

Коммиты

Сообщения коммитов в истории — это одно короткое предложение, описывающее, что изменилось, в sentence case и без точки в конце. Изменения в одной части предваряются её названием, например Fusion: a compact conversation header on phones или Server: community attributes, and admin-only user attributes. Один коммит на одно изменение; объясняйте причины в теле сообщения, если они не очевидны.

Сервер (Go)

  • Перед push-ом выполните make check-style в server/.
  • Никогда не запускайте go mod tidy напрямую; запускайте make modules-tidy.
  • В путях запросов логируйте с помощью логгера запроса. В слое хранилища принимайте request.CTX, а не context.Context.
  • Новые эндпоинты API размещаются в server/channels/api4, их типы — в server/public/model, а, по возможности, метод в model.Client4 и в клиенте на TypeScript.

Веб-интерфейсы (TypeScript и React)

  • Выполните make check-style и make check-types в webapp/.
  • Классический интерфейс следует webapp/STYLE_GUIDE.md: функциональные компоненты, хуки для Redux, переменные темы для цветов, доступная разметка.
  • Компоненты Fusion находятся в webapp/fusion/src/fusion, а их стили — в webapp/fusion/src/fusion/styles. Они формируют имена классов с помощью хелпера am() и используют дизайн-токены Fusion; следуйте файлам, расположенным рядом с вашими.
  • Не добавляйте новые глобальные переменные window.* для приложений. Новые утилиты для приложений размещаются под window.WebappUtils, как объясняется в webapp/AGENTS.md.
  • Изменения в реестре приложений (plugins/registry.ts) обычно должны вноситься в копии обоих интерфейсов.

Переводы

Antimatter и входящие в его состав приложения переведены на 37 языков. Вкладчики добавляют английские строки; остальные языки обновляются партиями.

Добавление строки в веб-интерфейсы

  1. Запишите её с идентификатором и английским текстом по умолчанию: formatMessage({id: 'fusion.channelMenu.settings', defaultMessage: 'Channel settings'}) или <FormattedMessage id='…' defaultMessage='…'/>. Английский текст, отображаемый в приложении, берётся из defaultMessage.
  2. Выполните make i18n-extract в webapp/ (или npm run i18n-extract в webapp/fusion или webapp/channels). Это обновит файл src/i18n/en.json данного пакета.
  3. Заполните поле description для новой записи в en.json: укажите, где появляется строка и как она используется. Это контекст, от которого работают переводчики, будь то люди или машины.

npm run i18n-extract:check завершается с ошибкой, если en.json не соответствует коду.

Добавление строки на сервере

  1. Используйте идентификатор в коде, например model.NewAppError(…, "app.community_attributes.invalid.app_error", …) или i18n.T("…").
  2. Выполните make i18n-extract в server/. Это добавит идентификатор в server/i18n/en.json в правильном порядке.
  3. Запишите английский translation и description для новой записи.

Другие языки

Для каждого языка есть отдельный файл рядом с en.json (fr.json, pt-BR.json, zh-TW.json…). Чтобы сообщить об ошибке в переводе, создайте issue в репозитории сообщества, указав язык, текст и место его появления.

Входящие в состав приложения хранят свои строки в webapp/i18n/; см. раздел Переводы на странице приложений.

Документация и этот сайт

Этот сайт и его документация находятся в репозитории antimatter.chat. Страницы — это HTML-фрагменты в src/pages/; python3 src/build.py собирает сайт. Исправления и недостающие пояснения приветствуются в виде issues или pull request.

Проблемы безопасности

Никогда не сообщайте о проблемах безопасности в публичных issues, обсуждениях или pull request.

Сообщите о ней конфиденциально, используя функцию GitHub для сообщения об уязвимостях: откройте вкладку Безопасность в затронутом репозитории (например, сервера) и выберите Report a vulnerability. Если вы не знаете, какой репозиторий затронут, отправьте сообщение в репозиторий сообщества. Укажите компонент и его версию, что может сделать злоумышленник, как воспроизвести проблему и от какой конфигурации она зависит.

Разработчики отвечают там, держат вас в курсе процесса исправления и публикуют уведомление, как только выйдет исправленная версия. Пожалуйста, дайте им разумное время, прежде чем раскрывать проблему. Исправления включаются в последнюю версию. Полная политика изложена в политике безопасности.

Лицензии

  • Сервер распространяется под лицензией GNU Affero General Public License v3.0 (AGPL v3). В том же репозитории административные инструменты и файлы конфигурации (server/templates/, server/i18n/, server/public/ и webapp/) распространяются под лицензией Apache License 2.0. См. LICENSE.txt и NOTICE.txt.
  • Приложения: собственные приложения Antimatter, такие как Опросы, распространяются под AGPL v3; приложения, созданные на основе Mattermost, сохраняют свою исходную лицензию. В каждом репозитории это указано в файле LICENSE.
  • Десктопные и мобильные приложения распространяются под Apache License 2.0. Репозиторий Docker распространяется под Apache License 2.0, за исключением Dockerfile, который распространяется под AGPL v3.

Лицензия AGPL означает, что если вы запускаете модифицированный сервер Antimatter для других людей через сеть, вы обязаны предоставить им исходный код ваших изменений. Antimatter основан на Mattermost; он не связан с Mattermost, Inc. и не одобрен ею.

Все участники соблюдают правила поведения.