Antimatter

المساهمة

نرحب بتقارير الأخطاء والأفكار والترجمات والوثائق والكود. توضح هذه الصفحة أين تجري المحادثات، وكيف ترسل تغييراً، والمواثيق التي يتبعها الكود، والقواعد المتعلقة بمشاكل الأمان والرخص.

أين تجري المحادثات

تبدأ كل الأمور في مستودع المجتمع، بغض النظر عن الجزء الذي يتعلق به الأمر في Antimatter:

  • الأخطاء وطلبات الميزات: افتح مشكلة واختر تقرير خطأ، طلب ميزة، أو طلب إضافة أو تكامل. ابحث أولاً في المشكلات الموجودة؛ إذا كانت مشكلتك موجودة، أضف إبهاماً مرفوعاً أو تفاصيلك.
  • الأسئلة والأفكار: المناقشات، في فئتي الأسئلة والأجوبة والأفكار.
  • قبل إجراء تغيير كبير، افتح مشكلة أو نقاشاً للاتفاق على النهج أولاً. هذا يوفر طلب دمج لا يمكن دمجه كما هو.

تُعدّ المشكلات المُصنَّفة بـ good first issue و help wanted نقطة بداية جيدة. اذكر في تعليق أنك تعمل على إحداها. تُصنَّف المشكلات الجديدة بـ status/triage، ثم status/accepted أو status/planned أو status/wontfix. تبقى المشكلات في مستودع المجتمع بغض النظر عن موضوعها: فلا تقبل مستودعات الشفرات المشكلات. الأعمال المخطط لها موجودة في خارطة طريق Antimatter.

المستودعات والفروع

الكود موجود في منظمة AntimatterChat؛ أين يوجد الكود يحدد المستودعات. في كل مستودع:

  • main هو الفرع الافتراضي ويحتوي على كود Antimatter. أنشئ فرعاً منه وأرسل طلبات الدمج إليه.
  • المستودعات المنشقة من Mattermost لديها أيضاً فرع upstream، وهو مرآة لكود Mattermost تُستخدم لجلب تغييراته. لا تبني عملك عليه.

يشرح ملف README الخاص بكل مستودع كيفية البناء واختباره. للخادم والواجهات الويب، راجع البناء من المصدر؛ للتطبيقات، البناء والتثبيت والتشخيص.

طلبات الدمج

  1. انسخ المستودع وأنشئ فرعًا من main.
  2. اجعل كل طلب سحب يتضمن تغييرًا واحدًا فقط. تُراجع طلبات السحب الصغيرة بشكل أسرع.
  3. اتبع نمط الكود المحيط بك، وأضف أو حدّث الاختبارات حيث يكون ذلك منطقيًا.
  4. اشرح ما قمت بتغييره ولماذا، واربط المشكلة التي يعالجها التغيير: Fixes AntimatterChat/community#123.
  5. تأكد من نجاح الفحوصات. سيقوم أحد المشرفين بمراجعة طلب السحب وقد يطلب إجراء تغييرات.

في مستودع الخادم، املأ قالب طلب السحب: ملخص، وقسم ملاحظة الإصدار، الذي يجب أن يكون موجودًا دائمًا. اكتب NONE فيه عندما لا يمس التغيير واجهة برمجة التطبيقات، أو الإعدادات، أو مخطط قاعدة البيانات، أو السلوك المرئي.

بمساهمتك، أنت توافق على أن مساهمتك مرخصة بموجب ترخيص المستودع الذي تساهم فيه.

الالتزامات ونمط الكود

الالتزامات

رسائل الالتزامات في السجل عبارة عن جملة قصيرة واحدة توضح التغيير، وتُكتب بحالة الجملة (أول حرف كبير) وبدون نقطة في النهاية. تُسبق التغييرات في جزء معين باسم ذلك الجزء، على سبيل المثال Fusion: a compact conversation header on phones أو Server: community attributes, and admin-only user attributes. التزام واحد لكل تغيير؛ اشرح الأسباب في نص الرسالة عندما لا تكون واضحة.

الخادم (Go)

  • شغّل make check-style في server/ قبل الدفع.
  • لا تشغّل go mod tidy مباشرةً؛ شغّل make modules-tidy بدلاً من ذلك.
  • في مسارات الطلبات، سجّل الأحداث باستخدام مسجّل الطلب. في طبقة التخزين، استخدم request.CTX بدلاً من context.Context.
  • توضع نقاط نهاية واجهة برمجة التطبيقات الجديدة في server/channels/api4، مع أنواعها في server/public/model، ومن الأفضل وجود طريقة في model.Client4 وفي عميل TypeScript.

واجهات الويب (TypeScript و React)

  • شغّل make check-style و make check-types في webapp/.
  • تتبع الواجهة الكلاسيكية webapp/STYLE_GUIDE.md: مكونات وظيفية، خطافات (hooks) لـ Redux، متغيرات موضوع (theme) للألوان، وعلامات HTML ميسّرة الوصول.
  • تقع مكونات 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 يبني الموقع. التصحيحات والتفسيرات الناقصة مرحّب بها كمشكلات أو طلبات سحب (pull requests).

مشاكل الأمان

لا تُبلّغ أبداً عن مشكلة أمنية في مشكلة عامة، نقاش، أو طلب سحب.

أبلغوا عن ذلك بشكل خاص عبر خاصية الإبلاغ عن الثغرات الأمنية الخاصة في GitHub: افتحوا تبويب الأمان في المستودع المتأثر (على سبيل المثال الخادم) واختر الإبلاغ عن ثغرة أمنية. إذا لم تكن على دراية بالمستودع المتأثر، فأبلغوا عنه في مستودع المجتمع. اذكروا المكوّن وإصداره، وما يمكن للمهاجم فعله، وكيفية إعادة إنتاج المشكلة، وأي إعدادات تعتمد عليها.

يجيب المسؤولون هناك، ويُبقيونك على اطلاع أثناء إصلاحهم، وينشرون تنبيهاً أمنيًا بمجرد إصدار الإصدار المُصلَح. يُرجى منحهم وقتًا معقولاً قبل الكشف عن المشكلة. تُدمج الإصلاحات في أحدث إصدار. السياسة الكاملة متوفرة في سياسة الأمان.

التراخيص

  • الخادم مرخّص بموجب رخصة جنو العمومية العامة Affero v3.0 (AGPL v3). في نفس المستودع، أدوات الإدارة وملفات الإعداد (server/templates/، server/i18n/، server/public/ و webapp/) مرخّصة بموجب رخصة Apache 2.0. راجعوا LICENSE.txt و NOTICE.txt.
  • التطبيقات: تطبيقات Antimatter الخاصة، مثل الاستطلاعات، مرخّصة بموجب AGPL v3؛ أما التطبيقات المشتقة من Mattermost فتحتفظ برخصتها الأصلية. يوضح كل مستودع ذلك في ملف LICENSE الخاص به.
  • تطبيقات سطح المكتب والجوال مرخّصة بموجب رخصة Apache 2.0. مستودع Docker مرخّص بموجب رخصة Apache 2.0، باستثناء Dockerfile الذي هو مرخّص بموجب AGPL v3.

تعني رخصة AGPL أنه إذا قمت بتشغيل خادم Antimatter معدّل لأشخاص آخرين عبر شبكة، فيجب أن توفر لهم كود المصدر لتغييراتك. Antimatter مبني على Mattermost؛ وهو غير تابع لشركة Mattermost, Inc. ولا تحظى بدعمها.

يتبع جميع المشاركين مدونة السلوك.