إنتقل إلى المحتوى الرئيسي

سياسة RaR-IT لمراجعة الكود وطلبات السحب (Pull Request)

:::danger الحالة: مقترحة — بانتظار المراجعة والاعتماد والنشر الإصدار 1.0 · 28 أغسطس 2026. هذه الوثيقة غير ملزمة بعد — انظر القسم 8. :::

1. الغرض والنطاق​

تُحدد هذه السياسة المتطلبات الإلزامية لطلبات السحب (Pull Request) ومراجعة الكود في كل مستودع (repository) لدى RaR-IT — النواة المشتركة للمنصة (rarit-saas-kernel)، وجميع القطاعات الرأسية للمنتج (AMAAR وClinivio وEduSuite والشحن والنقل وTourism)، وكل تطبيق مستقل غير مبني على النواة (حاليًا Dw2ni وAdl وHajez وLasscar وRizq وBindoo وCashBlash وAxil، وأي تطبيق مستقل مستقبلي).

هذا النطاق أوسع عمدًا من نطاق سياسة عمارة SaaS (التي تقتصر على النواة والقطاعات الرأسية فقط) — تلك السياسة تحكم ما الذي يُبنى (المكدس التقني، الأنماط)؛ أما هذه السياسة فتحكم كيفية مراجعة التغيير ودمجه، بغض النظر عن المكدس التقني. حيثما كان المستودع مشمولًا أيضًا بسياسة العمارة، تُطبَّق كلتا السياستين؛ لا شيء هنا يُلغي المتطلبات التقنية لتلك السياسة.

2. متطلبات طلب السحب (Pull Request)​

  • يجب أن يستخدم كل PR قالب المستودع .github/PULL_REQUEST_TEMPLATE.md، مع تعبئة الأقسام التالية: Story، Acceptance Scenarios (Given-When-Then)، What changed، Notes for the reviewer.
  • يجب أن يحمل اسم الفرع (branch) مفتاح القصة (story key) بصيغة <PROJECT>-<number> (مثل EDS-118 أو SASK-42)، كجزء ضمن اسم الفرع. هذا متطلب صارم وليس تفضيلًا أسلوبيًا — فكل من مطابقة السيناريوهات في Claude Code Review (القسم 3) وأدوات أتمتة PR (القسم 5) تعتمد على إمكانية استخلاصه.
  • يُسمح بترك قسم Story/Acceptance Scenarios فارغًا (فليس كل تغيير مرتبطًا ببند في الـ backlog — كإصلاح عاجل أو تحديث تبعية) لكن Code Review يُشير إلى ذلك بدلًا من تجاهله بصمت؛ انظر القسم 3.

3. المراجعة الآلية — Claude Code Review​

  • مُفعّلة (عبر خطة Team) على كل مستودع ضمن النطاق. يُغلق هذا رسميًا البند ACT-005 — ونتيجته هي هذه السياسة نفسها.
  • المُشغِّل (Trigger): "Once after PR creation" على مستوى المنصة بأكملها، للحفاظ على الاتساق بين المستودعات. يطلب أحد أعضاء الفريق مراجعة جديدة عبر تعليق @claude review إذا تغيّر الـ PR بشكل جوهري بعد المراجعة الأولى.
  • ملفان لكل مستودع، بدرجتي تأثير مختلفتين — لا يجوز الخلط بينهما:
    • CLAUDE.md — سياق عام للمشروع. يقرأه Code Review، لكن مخالفاته تظهر كملاحظات طفيفة (nits) فقط.
    • REVIEW.md — الملف ذو الطابع التنفيذي. تقرأه مباشرة كل وكلاء الرصد والتحقق (finding/verification agents). القواعد المستمدة من السياسات تنتمي إلى هذا الملف، لا إلى CLAUDE.md. يحكمه القسم 4.
  • مفردات درجة الخطورة (Severity)، تُستخدم باتساق في كل ملفات REVIEW.md:
    • Important — تُصعَّد؛ مخالفة حقيقية للسياسة أو للصحة التقنية.
    • Report as-is — يستحق الإبراز، لكنه ليس خطيرًا بما يكفي للتصعيد.
    • Nit — تجميلي؛ بحد أقصى 5 ملاحظات لكل مراجعة، والباقي يُلخَّص كعدد وليس بالتفصيل.
    • Skip — خارج نطاق المراجعة صراحةً (التوثيق، الملفات المولَّدة آليًا).
  • النتائج استشارية فقط. لا يقوم Code Review باعتماد أو حظر دمج PR. هذا خيار متعمَّد يتماشى مع أسلوب عمل الفريق القائم على الثقة عند الدمج — وليس قيدًا يجب الالتفاف عليه. انظر القسم 6 لمعرفة ما يلزم تغييره ليصبح هذا ضابطًا (gate) فعليًا.

4. حوكمة ملف REVIEW.md​

  • ملف REVIEW.md واحد لكل مستودع — يقرأ Code Review فقط الملف الموجود داخل المستودع الذي يراجعه؛ الإشارات بين المستودعات لا تعمل.
  • مستودعات النواة والقطاعات الرأسية: يحمل كل REVIEW.md قاعدة مشتركة (قواعد العمارة المشتركة بين كل مستودع يستهلك النواة — نمط الوصول المرفوض لقاعدة البيانات، حظر الاستيراد بين القطاعات الرأسية، شرط FORCE على RLS، تقسيم الطبقات (routing)، اقتران كتابة سجل التدقيق Audit) بالإضافة إلى قسم خاص بالمستودع (مثل ضوابط نطاق MVP الخاصة بـ EduSuite وفحوصات بيان Entitlements).
  • التطبيقات المستقلة (مكدس تقني منفصل — حاليًا التطبيقات المحمولة): يُبنى ملف REVIEW.md الخاص بها من أفضل الممارسات العامة لذلك المكدس، وليس من قاعدة النواة، لأن قواعد عمارة النواة لا تنطبق عليها. يجب تأكيد النقاط غير المحسومة الخاصة بالمكدس (إدارة الحالة، طبقة الشبكة، خيار التخزين المحلي) في كل ملف من هذا النوع قبل الاعتماد عليه — فالافتراض غير المؤكَّد هنا يُنتج نتائج كاذبة إيجابية (false positives) على كود صحيح.
  • ثغرة معروفة لم تُحل بعد: يُنسخ الجزء المشترك يدويًا إلى ملف REVIEW.md في كل مستودع من مستودعات النواة والقطاعات الرأسية. لا توجد آلية توليد أو مزامنة، لذا فإن أي تغيير في القواعد المشتركة يتطلب نشره يدويًا في كل مستودع، ومن الممكن أن يحدث تباعد (drift) بين المستودعات دون أن يلاحظه أحد. يُتابَع هذا الأمر كبند ACT-006 (القسم 7).

5. أدوات إنشاء PR​

  • ينبغي نقل نص Story/Scenario إلى وصف الـ PR عبر أدوات آلية، لا بإعادة كتابته يدويًا — لا تفرض هذه السياسة أداة بعينها، لكنها تفرض اتفاقية تسمية الفروع (القسم 2) التي تعتمد عليها أي أداة من هذا النوع.
  • يوجد تطبيق مرجعي (scripts/create_pr.py + مهمة VS Code + خطاف pre-push اختياري): يستخلص مفتاح القصة من اسم الفرع، ويسحب Story/Acceptance Scenario من ملف الـ backlog الخاص بالمستودع، ويملأ قالب PR، وينشئ الـ PR عبر gh pr create. أي خطاف (hook) يُشغِّل هذا تلقائيًا يجب أن يطلب تأكيدًا قبل إنشاء PR — فحدوث أثر جانبي صامت أثناء git push غير مقبول.

6. إنفاذ الدمج وحدوده الحالية​

  • في خطة GitHub Free، لا تتوفر حماية الفروع (branch protection) ولا فحوصات الحالة الإلزامية (required status checks) على المستودعات الخاصة (private) — وهذا يؤثر بالتساوي على نتائج Code Review في هذه السياسة وعلى فحوصات lint في CI ضمن A.9 من سياسة العمارة. تبقى كلتاهما استشارية (مرئية، لا حاجبة للدمج) في ظل خطة GitHub الحالية.
  • هذا قيد معروف ومقبول ضمن الخطة الحالية، وليس عيبًا يُتجاوَز بصمت. إعادة النظر في خطة GitHub تُتابَع بشكل منفصل — انظر البند ACT-004 (المرتبط بحماية الفروع) والملاحظة المرفقة بالخطوة 5 من A.9.
  • إذا تغيّرت الخطة، لا حاجة لتغيير أي محتوى في REVIEW.md — فقط إعدادات حماية الفروع. مفردات الخطورة في القسم 3 تستبق هذا الاحتمال أصلًا: نتائج Important هي المرشح الطبيعي لتصبح فحصًا إلزاميًا مستقبلًا، إن اعتُمد إنفاذ حاجب للدمج (merge-blocking) لـ Code Review تحديدًا.

7. البنود المفتوحة​

تُتابَع مركزيًا في actions.md جنبًا إلى جنب مع بنود سياسة العمارة، وليس في متتبِّع منفصل:

  • ACT-005 — تهيئة Claude Code Review. الحالة: مُغلَق. النتيجة: هذه السياسة.
  • ACT-006 (جديد) — منع تباعد (drift) ملف REVIEW.md عبر المستودعات (آلية توليد أو قوالب للجزء المشترك). النوع: تنفيذ (Implementation).
  • ACT-007 (جديد) — نشر PULL_REQUEST_TEMPLATE.md واتفاقية تسمية الفروع في كل المستودعات ضمن النطاق، بما فيها التطبيقات المحمولة المستقلة، غير المشمولة حاليًا بأي خطة نشر قائمة. النوع: تنفيذ (Implementation).

8. الحوكمة والاعتماد​

نفس الآلية المتبعة في سياسة العمارة: موافقة PR بوابة CODEOWNERS مع فحص حالة إلزامي عبر حماية الفروع على مصدر هذه الوثيقة نفسها، متى سمحت خطة GitHub بذلك (انظر القسم 6)؛ يُشترط اعتماد لجنة مراجعة العمارة (ARB) قبل خروج هذه الوثيقة من حالة "مقترحة". دورة مراجعة ربع سنوية، كما في القسم 9 من سياسة العمارة.