همکاری

گزارش باگ‌ها، ایده‌ها، ترجمه‌ها، مستندات و کد همگی خوش‌آمد هستند. این صفحه توضیح می‌دهد که کجا صحبت کنیم، چگونه تغییری ارسال کنیم، قراردادهایی که کد از آن‌ها پیروی می‌کند و قوانین مربوط به مشکلات امنیتی و مجوزها.

محل گفت‌وگو

همه چیز در مخزن جامعه شروع می‌شود، صرف‌نظر از اینکه درباره کدام بخش از Antimatter باشد:

• باگ‌ها و درخواست‌های ویژگی: یک مشکل (issue) باز کنید و گزینه گزارش باگ، درخواست ویژگی یا درخواست افزونه یا یکپارچه‌سازی را انتخاب کنید. ابتدا مشکلات موجود را جستجو کنید؛ اگر مشکل شما در آن‌ها هست، یک آبه بالا (thumbs-up) بگذارید یا جزئیات خود را اضافه کنید.
• سؤالات و ایده‌ها: بخش بحث‌ها (Discussions) در دسته‌های پرسش و پاسخ یا ایده‌ها.
• پیش از یک تغییر بزرگ، یک مشکل (issue) یا بحث (discussion) باز کنید تا ابتدا روی رویکرد توافق شود. این کار از ارسال درخواست ادغامی که به همان شکل قابل ادغام نیست جلوگیری می‌کند.

مسئله‌هایی که برچسب good first issue و help wanted دارند، مکان‌های خوبی برای شروع هستند. در یک کامنت ذکر کنید که روی یکی از آن‌ها کار می‌کنید. مسئله‌های جدید برچسب status/triage می‌گیرند، سپس status/accepted، status/planned یا status/wontfix. مسئله‌ها در هر موردی که باشند، در مخزن جامعه باقی می‌مانند: مخزن‌های کد مسئله‌ها را نمی‌پذیرند. کارهای برنامه‌ریزی‌شده در نقشه راه Antimatter قرار دارند.

مخازن و شاخه‌ها

کد در سازمان AntimatterChat قرار دارد؛ بخش محل قرارگیری کد مخازن را فهرست می‌کند. در هر مخزن:

• main شاخه پیش‌فرض است و کد Antimatter را در خود نگه می‌دارد. از آن شاخه بزنید و درخواست‌های ادغام (pull request) را به آن ارسال کنید.
• مخازنی که از Mattermost فورک شده‌اند، یک شاخه upstream نیز دارند که آینه‌ای از کد Mattermost است و برای آوردن تغییرات آن استفاده می‌شود. کار خود را بر پایه آن انجام ندهید.

README هر مخزن توضیح می‌دهد که چگونه آن را بسازید و تست کنید. برای سرور و رابط‌های کاربری وب، به ساخت از سورس مراجعه کنید؛ برای اپلیکیشن‌ها، ساخت، نصب و دیباگ.

درخواست‌های ادغام

1. مخزن را فورک کنید و از main یک شاخه ایجاد کنید.
2. هر درخواست ادغام را به یک تغییر محدود کنید. درخواست‌های ادغام کوچک سریع‌تر بررسی می‌شوند.
3. با سبک کد اطراف خود همخوانی داشته باشید و در صورت منطقی بودن، تست‌ها را اضافه یا به‌روزرسانی کنید.
4. توضیح دهید چه چیزی را تغییر داده‌اید و چرا، و به مسئله‌ای که رفع می‌شود لینک دهید: Fixes AntimatterChat/community#123.
5. مطمئن شوید که بررسی‌ها (checks) پاس می‌شوند. یک نگهدار (maintainer) درخواست ادغام را بررسی می‌کند و ممکن است تغییراتی را درخواست کند.

در مخزن سرور، قالب درخواست ادغام (pull request) را تکمیل کنید: یک خلاصه و بلوک یادداشت انتشار که همیشه باید وجود داشته باشد. اگر تغییری در API، پیکربندی، طرح پایگاه داده یا رفتار قابل مشاهده ایجاد نکند، در آن NONE بنویسید.

با مشارکت، شما توافق می‌کنید که مشارکت شما تحت مجوز (licence) مخزنی که به آن مشارکت می‌کنید، لایسنس‌دهی شود.

کامیت‌ها و سبک کد

کامیت‌ها

پیام‌های کامیت در تاریخچه یک جمله کوتاه هستند که تغییرات را بیان می‌کنند، با حروف بزرگ در ابتدای جمله (sentence case) و بدون نقطه پایانی. تغییرات در یک بخش با نام آن پیشوند می‌گیرند، برای مثال Fusion: a compact conversation header on phones یا Server: community attributes, and admin-only user attributes. یک کامیت برای هر تغییر؛ اگر دلایل آشکار نباشند، آن‌ها را در بدنه (body) کامیت توضیح دهید.

سرور (Go)

• قبل از push کردن، در server/ دستور make check-style را اجرا کنید.
• هرگز مستقیماً go mod tidy را اجرا نکنید؛ make modules-tidy را اجرا کنید.
• در مسیرهای درخواست (request paths)، با لاگر (logger) درخواست لاگ کنید. در لایه ذخیره‌سازی (store layer)، یک request.CTX دریافت کنید، نه context.Context.
• نقطه‌های پایانی (endpoints) API جدید در server/channels/api4 قرار می‌گیرند، با انواع (types) آن‌ها در server/public/model و، ایده‌آل‌تر، یک متد در model.Client4 و در کلاینت TypeScript.

رابط‌های وب (TypeScript و React)

• در webapp/، make check-style و make check-types را اجرا کنید.
• رابط کلاسیک webapp/STYLE_GUIDE.md را دنبال می‌کند: کامپوننت‌های تابعی، هوک‌ها برای Redux، متغیرهای تم برای رنگ‌ها، و مارک‌آپ قابل دسترس (accessible).
• کامپوننت‌های Fusion در webapp/fusion/src/fusion قرار دارند، با سبک‌های (styles) آن‌ها در webapp/fusion/src/fusion/styles. آن‌ها نام‌های کلاس را با کمکی (helper) am() می‌سازند و از توکن‌های طراحی Fusion استفاده می‌کنند؛ فایل‌های کنار فایل خود را دنبال کنید.
• برای اپلیکیشن‌ها، گلوبال‌های (globals) جدید window.* اضافه نکنید. ابزارهای جدید رو به اپلیکیشن (app-facing) زیر window.WebappUtils قرار می‌گیرند، همان‌طور که در webapp/AGENTS.md توضیح داده شده است.
• تغییر در ثبت برنامه‌ها (plugins/registry.ts) معمولاً باید در کپی‌های هر دو رابط کاربری اعمال شود.

ترجمه‌ها

Antimatter و برنامه‌های همراه آن به ۳۷ زبان ترجمه شده‌اند. مشارکت‌کنندگان رشته‌های انگلیسی را اضافه می‌کنند و سایر زبان‌ها به صورت دسته‌ای به‌روزرسانی می‌شوند.

افزودن یک رشته به رابط‌های کاربری وب

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 سایت را می‌سازد. اصلاحات و توضیحات ناقص به صورت مشکل (issue) یا درخواست کشش (pull request) خوش‌آمد هستند.

مشکلات امنیتی

از طریق گزارش‌دهی آسیب‌پذیری خصوصی GitHub به صورت خصوصی گزارش دهید: تب امنیت مخزن مورد تأثیر (برای مثال سرور) را باز کنید و گزینه گزارش آسیب‌پذیری را انتخاب کنید. اگر نمی‌دانید کدام مخزن تحت تأثیر قرار دارد، آن را در مخزن جامعه گزارش دهید. مؤلفه و نسخه آن، آنچه مهاجم می‌تواند انجام دهد، نحوه بازتولید مشکل و هرگونه پیکربندی وابسته به آن را ذکر کنید.

نگهدارندگان در همان محل پاسخ می‌دهند، در حین رفع مشکل شما را از وضعیت مطلع می‌کنند و پس از انتشار نسخه اصلاح‌شده، یک اعلان (advisory) منتشر می‌کنند. لطفاً قبل از افشای عمومی مشکل، به آن‌ها زمان معقولی بدهید. اصلاحات در آخرین نسخه اعمال می‌شوند. سیاست کامل در سیاست امنیتی آمده است.

مجوزها

• سرور تحت مجوز GNU Affero General Public License v3.0 (AGPL v3) است. در همان مخزن، ابزارهای مدیریت و فایل‌های پیکربندی (server/templates/, server/i18n/, server/public/ and 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. نیست و تأیید رسمی آن شرکت را ندارد.

همه شرکت‌کنندگان قوانین اخلاق را رعایت می‌کنند.