Antimatter

תרומה

דיווחים על תקלות, רעיונות, תרגומים, תיעוד וקוד – כולם מוזמנים. עמוד זה מסביר איפה לדבר, איך לשלוח שינוי, האמנות שהקוד נוקט, והכללים לבעיות אבטחה ולרישיונות.

איפה לדבר

הכול מתחיל במאגר קהילה, בין אם מדובר בחלק כלשהו של Antimatter:

  • תקלות ובקשות תכונות: פתחו בעיה ובחרו דיווח תקלה, בקשת תכונה או בקשת תוסף או אינטגרציה. חפשו קודם כל בבעיות הקיימות; אם הבעיה שלכם נמצאת שם, הוסיפו אצבע תומכת או פרטים שלכם.
  • שאלות ורעיונות: בדיונים, בקטגוריות שאלות ותשובות או רעיונות.
  • לפני שינוי גדול, פתחו בעיה או דיון כדי להסכים על הגישה מראש. זה חוסך בקשת משיכה שלא ניתן לשלב אותה כמות שהיא.

בעיות המסומנות בgood first issue ובhelp wanted הן מקומות טובים להתחיל. כתבו בתגובה שאתם עובדים על אחת מהן. בעיות חדשות מסומנות בstatus/triage, ואז בstatus/accepted, status/planned או status/wontfix. בעיות נשארות במאגר הקהילה בין אם הן על הקוד או לא: מאגרי הקוד לא מקבלים בעיות. העבודה המתוכננת מפורטת במפת הדרכים של Antimatter.

מאגרים וענפים

הקוד נמצא בארגון AntimatterChat; איפה נמצא הקוד מפרט את המאגרים. בכל מאגר:

  • main הוא הענף המוגדר כברירת מחדל ומכיל את קוד Antimatter. צרו ענף ממנו ושלחו בקשות משיכה אליו.
  • למאגרים שהועתקו (forked) מ-Mattermost יש גם ענף upstream, מראה של קוד Mattermost המשמש להבאת השינויים שלו. אל תבנו עליו עבודה.

קובע README של כל מאגר מסביר איך לבנות אותו ולבדוק אותו. עבור השרת והממשקים הווב, ראו בנייה מקוד המקור; עבור אפליקציות, בנייה, התקנה וניפוי תקלות.

בקשות משיכה

  1. עשו Fork למאגר וצרו ענף מ-main.
  2. הגבילו כל בקשת משיכה (Pull Request) לשינוי אחד. בקשות משיכה קטנות נבדקות מהר יותר.
  3. התאימו את הסגנון לקוד הסובב אתכם, והוסיפו או עדכנו בדיקות (Tests) שם שזה הגיוני.
  4. תיארו מה שיניתם ולמה, וקשרו את ה-Issue שאתם מתקנים: Fixes AntimatterChat/community#123.
  5. ודאו שהבדיקות עוברות. מנהל (Maintainer) יבדוק את בקשת המשיכה וייתכן שייבקש שינויים.

במאגר השרת, מלאו את תבנית בקשת המשיכה: סיכום, ובלוק הערה לגרסה, שחייב להיות תמיד. כתבו NONE שם כאשר השינוי לא נוגע ב-API, בהגדרות, במבנה בסיס הנתונים או בהתנהגות נראית לעין.

על ידי תרומה, אתם מסכימים שהתרומה שלכם מורשית תחת הרישיון של המאגר שאליו אתם תורמים.

Commits וסגנון קוד

Commits

הודעות commit בהיסטוריה הן משפט קצר אחד המתאר את השינויים, בכתב משפט (sentence case) וללא נקודה בסוף. שינויים בחלק אחד מתחילים עם שמו, למשל Fusion: a compact conversation header on phones או Server: community attributes, and admin-only user attributes. commit אחד לכל שינוי; הסבר את הסיבות בגוף ההודעה כשהן אינן ברורות.

שרת (Go)

  • הריצו make check-style ב-server/ לפני העלאה (Push).
  • אל תריצו go mod tidy ישירות; הריצו make modules-tidy.
  • בנתיבי בקשה (Request paths), לוגו עם הלוגר של הבקשה. בשכבת האחסון (Store layer), קחו request.CTX, ולא context.Context.
  • נקודות API חדשות נמצאות ב-server/channels/api4, עם סוגיהם (Types) ב-server/public/model ו, אידיאלית, מתודה ב-model.Client4 ובלקוח TypeScript.

ממשקי Web (TypeScript ו-React)

  • הריצו make check-style ו-make check-types ב-webapp/.
  • הממשק הקלאסי עוקב אחר webapp/STYLE_GUIDE.md: רכיבים פונקציונליים, Hooks ל-Redux, משתני נושא (Theme variables) לצבעים, ו-Markup נגיש.
  • רכיבי Fusion נמצאים ב-webapp/fusion/src/fusion, עם סגנונותיהם ב-webapp/fusion/src/fusion/styles. הם בונים שמות Class עם העזר am() ומשתמשים בטוקני העיצוב של Fusion; עקבו אחר הקבצים הסמוכים לכם.
  • אל תוסיפו גלובלים חדשים של 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. הריצו 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. השתמשו במזהה (ID) בקוד, למשל 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 requests.

בעיות אבטחה

אסור לדווח על בעיית אבטחה ב-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.

כל המשתתפים פועלים לפי קוד ההתנהגות.