Antimatter

貢獻

歡迎提交錯誤報告、構想、翻譯、文件與程式碼。本頁說明討論的場所、如何提交變更、程式碼遵循的慣例，以及安全性問題與授權條款的規則。

討論場所

無論涉及 Antimatter 的哪個部分，一切都從社群儲存庫開始：

  • 錯誤與功能請求：開啟一個問題，並選擇錯誤報告、功能請求或外掛或整合請求。請先搜尋現有問題；如果您的問題已存在，請加上大拇指或補充您的詳細資訊。
  • 問題與構想：討論區，位於問答或構想分類中。
  • 進行較大變更之前，請先開啟一個問題或討論，以達成方法上的共識。這可以避免提交無法合併的拉取請求。

標記為 good first issue 和 help wanted 的議題是很好的入門選擇。請在留言中說明您正在處理該議題。新的議題會先標記為 status/triage，然後根據情況標記為 status/accepted、status/planned 或 status/wontfix。無論議題內容為何，都應保留在社群儲存庫中：程式碼儲存庫不接受議題。已規劃的工作可在 Antimatter 路線圖 上查看。

儲存庫與分支

程式碼位於 AntimatterChat 組織中；程式碼所在位置列出了各儲存庫。在每個儲存庫中：

  • main 是預設分支，包含 Antimatter 的程式碼。請從該分支建立分支，並向該分支發送拉取請求。
  • 從 Mattermost 分叉的儲存庫也有一個 upstream 分支，這是 Mattermost 程式碼的鏡像，用於引入其變更。請勿以此作為工作的基礎。

每個儲存庫的 README 說明了如何建置與測試。對於伺服器與網頁介面，請參閱從原始碼建置；對於應用程式，請參閱建置、安裝與除錯。

拉取請求

  1. 複製（fork）儲存庫，並從 main 建立分支。
  2. 每個拉取請求（pull request）只包含一項變更。較小的拉取請求能更快完成審查。
  3. 遵循周圍程式碼的風格，並在適當的地方新增或更新測試。
  4. 描述您變更的內容與原因，並連結所修復的議題：Fixes AntimatterChat/community#123。
  5. 確保所有檢查通過。維護者會審查拉取請求，並可能要求修改。

在伺服器儲存庫中，填寫拉取請求模板：摘要，以及Release Note區塊（此區塊必須存在）。若變更未涉及 API、設定、資料庫結構或可見的行為，請在此填入 NONE。

透過貢獻，您同意您的貢獻將採用您所貢獻之儲存庫的授權條款。

提交與程式碼風格

提交

歷史記錄中的提交訊息應為一句簡短的句子，說明變更內容，使用句子大小寫格式，且結尾不加句號。對特定部分的變更應以其名稱作為前綴，例如 Fusion: a compact conversation header on phones 或 Server: community attributes, and admin-only user attributes。每次變更對應一個提交；若原因不明顯，請在訊息主體中加以說明。

伺服器（Go）

  • 在 server/ 目錄中，推送前請執行 make check-style。
  • 切勿直接執行 go mod tidy；請執行 make modules-tidy。
  • 在請求路徑中，請使用該請求的記錄器（logger）進行記錄。在儲存層（store layer）中，請使用 request.CTX，而非 context.Context。
  • 新的 API 端點應放在 server/channels/api4，其型別放在 server/public/model，並理想上在 model.Client4 和 TypeScript 客戶端中新增對應的方法。

網頁介面（TypeScript 和 React）

  • 在 webapp/ 目錄中，執行 make check-style 和 make check-types。
  • 經典介面遵循 webapp/STYLE_GUIDE.md：使用函數式元件、用於 Redux 的 hooks、用於顏色的主題變數，以及無障礙標記。
  • Fusion 的元件位於 webapp/fusion/src/fusion，其樣式位於 webapp/fusion/src/fusion/styles。它們使用 am() 輔助函數建立類別名稱，並使用 Fusion 的設計令牌（design tokens）；請遵循您旁邊檔案的寫法。
  • 請勿為應用程式新增新的 window.* 全域變數。新的應用程式端工具應放在 window.WebappUtils 下，詳見 webapp/AGENTS.md 的說明。
  • 對應用程式登錄檔（plugins/registry.ts）的變更，通常應同時包含在兩個介面的副本中。

翻譯

Antimatter 及其內建應用程式已翻譯成 37 種語言。貢獻者負責新增英文字串；其他語言則以批次方式更新。

在網頁介面中新增字串

  1. 請使用 ID 和英文原文撰寫：formatMessage({id: 'fusion.channelMenu.settings', defaultMessage: 'Channel settings'}) 或 <FormattedMessage id='…' defaultMessage='…'/>。應用程式中顯示的英文來自 defaultMessage。
  2. 在 webapp/ 中執行 make i18n-extract（或在 webapp/fusion 或 webapp/channels 中執行 npm run i18n-extract）。這會更新該套件的 src/i18n/en.json。
  3. 在 en.json 中填寫新條目的 description：說明該字串出現的位置及其用途。這是翻譯者（人類或機器）工作的依據。

當 en.json 與程式碼不同步時，npm run i18n-extract:check 會失敗。

在伺服器端新增字串

  1. 在程式碼中使用 ID，例如 model.NewAppError(…, "app.community_attributes.invalid.app_error", …) 或 i18n.T("…")。
  2. 在 server/ 中執行 make i18n-extract。這會將 ID 依正確順序新增到 server/i18n/en.json。
  3. 撰寫新條目的英文 translation 和 description。

其他語言

每種語言都有位於 en.json 旁邊的獨立檔案（fr.json、pt-BR.json、zh-TW.json…）。若要回報錯誤的翻譯，請在社群儲存庫中開啟一個 issue，並附上語言、文字以及出現的位置。

內建應用程式將其字串保留在 webapp/i18n/ 中；請參閱應用程式頁面中的 翻譯。

文件與本網站

本網站及其文件位於 antimatter.chat 儲存庫中。頁面是 src/pages/ 中的 HTML 片段；python3 src/build.py 用於建置網站。歡迎透過 issue 或 pull request 提出更正或補充說明。

安全性問題

切勿在公開的 issue、討論串或 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. 無隸屬或背書關係。

所有參與者都必須遵守 行為準則。