الأعراف

تنطبق هذه القواعد على كل تغيير، في كل خدمة وتطبيق. يتحقق منها المراجعون، ويفرض التكامل المستمر عددًا منها.

الإنجليزية والعربية تُشحنان معًا

كل نص يراه المستخدم يُشحن بالإنجليزية والعربية في التغيير نفسه، وعلى كل واجهة: تطبيق الويب وتطبيقات Android وتطبيقات Apple. النص المكتوب بلغة واحدة فقط تغيير لم يكتمل.

يجب أن يعمل الاتجاه من اليمين إلى اليسار:

• استخدم التخطيط المنطقي (البداية والنهاية، وstart وend، وخصائص CSS المنطقية مثل margin-inline-start) بدلًا من اليسار واليمين.
• اعكس الأيقونات الاتجاهية، وأبقِ أزرار التحكم بالوسائط والخطوط الزمنية في اتجاهها الطبيعي، واختبر الشاشات بالعربية.
• النص الذي يمزج العربية بالحروف اللاتينية (العناوين، وأسماء الملفات، والأرقام) يجب أن يُعرض باتجاه ثنائي صحيح؛ ولا تبنِ الجمل بوصل أجزاء متفرقة.

الاختبارات تُشحن مع الشيفرة

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

الأدوار تفرضها الواجهة البرمجية

كل قاعدة أدوار (من يحق له إدارة المكتبات والمستخدمين والإعدادات والأجهزة وغيرها) تُفرض في الخادم داخل الواجهة البرمجية، ولكل قاعدة اختبار يستدعي نقطة الوصول بدور يجب رفضه ويتحقق من الرفض. إخفاء زر في واجهة الويب أو التطبيقات الأصلية ليس قاعدة؛ إنه تسهيل فوق القاعدة. نقطة الوصول الجديدة التي لا تتحقق من الدور ولا تملك اختبار دور غير مكتملة.

لا أسرار في الشيفرة

• لا تودِع أبدًا أسرارًا أو بيانات اعتماد أو رموزًا (tokens) أو مفاتيح خاصة أو مواد توقيع، في الشيفرة أو الاختبارات أو بيانات الاختبار أو الوثائق أو ملفات التكامل المستمر.
• تأتي الإعدادات من البيئة أو من ملفات خارج المستودع؛ ولا يعرض .env.example إلا الأسماء والقيم الافتراضية الآمنة.
• تولّد الاختبارات مفاتيحها المؤقتة بنفسها وتستخدم قيمًا وهمية واضحة.
• تستخدم الوثائق أمثلة عامة: لا مسارات منزلية شخصية، ولا عناوين شبكات خاصة، ولا أسماء أجهزة.

المزيد في قواعد الأمان للإضافات والمساهمين.

أسلوب الشيفرة

• Go: gofmt وgo vet وgolangci-lint. وحدة واحدة لكل خدمة (api/ وstreaming/ وcloud/ وكل ملف تنفيذي في cmd/).
• بايثون: ruff وruff format، وmypy --strict (بما في ذلك الاختبارات).
• الويب: eslint دون أي تحذير، وtsc --noEmit، وprettier.
• السجلات: تسجيل منظَّم؛ لا تصِل أبدًا بيانات وقت التشغيل داخل نص رسالة السجل (يتحقق make lint-log من ذلك).
• الترحيلات: إضافة فقط، وقابلة للتكرار دون أثر، مع نسختَي PostgreSQL وSQLite معًا (make lint-migrations).
• رموز التصميم: الألوان والمسافات والخطوط تأتي من web/design-system/tokens/؛ ويبقى Tokens.swift وTokens.kt المولَّدان متزامنين (make test-tokens).

يُنسّق make format كل شيء؛ ويشغّل make lint كل أدوات الفحص كما يفعل التكامل المستمر.

الإيداعات

تتبع عناوين الإيداعات أسلوبًا اصطلاحيًّا: نوع، ونطاق اختياري، وملخص قصير بكلمات بسيطة.

feat(apps): sign-in request banner and notification
fix(android): the waiting banner keeps the screens' state
test(tvos): the code screen names the approve step
docs(spec): Epic 50 home broadcasting
chore(devportal): format, and the changelog line

الأنواع الشائعة: feat وfix وtest وdocs وchore وrefactor وperf وci. والنطاقات الشائعة هي الخدمة أو التطبيق (api وstreaming وpipeline وweb وandroid وapple وtvos وcloud وdevportal وspec).

• اجعل كل إيداع مركّزًا؛ واشرح السبب في متن الرسالة حين لا يكون واضحًا.
• حين لا يحتاج التغيير فعلًا إلى تغيير في الاختبارات، أضف التذييل No-Test-Change: <why>.
• أشِر إلى القصة (مثل Story 22.8) أو المسألة التي ينتمي إليها التغيير.

راجع طلبات الدمج لطلب الدمج نفسه.

اعرض مصدر هذه الصفحة على GitHub