# المساهمة في مرصاد

[English](CONTRIBUTING.md) · [دليل المستخدم](Help/MIRSAD_Help_AR.html) · [مصفوفة الاختبارات](Documents/TESTING.md)

المشروع يضم ثلاثة صناديق أدوات ArcGIS وتطبيق Windows مستقلًا. نرحب بتحسين الدليل وإتاحة الاستخدام ومصادر البيانات والتحقق العددي وقراءة المخرجات الجغرافية. Desktop نسخة تطوير؛ لم يعتمد إصدار مستقر بعد.

## إعداد المطور

استخدم Python 3.12 أو 3.13 بمعمارية 64 بت لتطبيق Desktop، واحتفظ ببيئتي ArcMap 2.7 وPro المرخصة منفصلتين. أوامر إنشاء البيئة وتثبيت الاعتماديات وتوليد الأصول وتشغيل البرنامج موجودة كاملة في [الدليل الإنجليزي للمساهم](CONTRIBUTING.md#start-from-a-clean-checkout). نفذها من جذر المستودع. `requirements.txt` مدخل التثبيت للمساهم، و`requirements.lock` سجل بيئة البناء المستخدمة.

لقطة المحطات `data/stations.sqlite` والمرجع الخام ضمن المستودع. يتحقق تجهيز الأصول من سلامتها ثم ينسخها إلى التطبيق؛ لا يحتاج Desktop إلى مجلد التول بوكس وقت التشغيل. لا تستبدل الكتالوج أو مصدره ضمنيًا.

## التحقق قبل Pull Request

```powershell
& 'MIRSAD Desktop/.venv/Scripts/python.exe' scripts/run_checks.py
& 'MIRSAD Desktop/.venv/Scripts/python.exe' -m unittest discover -s 'MIRSAD Desktop/tests' -v
```

يشغل الأمر الأول مجموعات الاختبارات القديمة في عمليات مستقلة لمنع تداخل بدائل ArcPy. اختبارات ArcGIS الأصلية تحتاج المضيف والترخيص وتنفذ صراحة؛ لا تعادلها المحاكاة أو CI. التنزيل بحسابات شخصية أيضًا تحقق منفصل.

اجعل التعديل محدودًا ووضح المشكلة والسلوك النهائي والفحوص والحدود. حافظ على توافق Python 2.7 في التول بوكس والوحدات المشتركة، واجعل التطبيق المستقل داخل `MIRSAD Desktop/` فقط. لا تضف البيئات أو الكاش أو EXE أو المثبت أو الأسرار أو تغييرات مشروعات وبيانات المستخدم إلى Git. اتبع [AGENTS.md](AGENTS.md) وتعليمات Desktop.

## الدليل والمعادلات

عدل الموضوعات المتطابقة في `Documents/Help/ar/` و`en/` وسجل معرفاتها في `topics.json`. جداول المصادر من السجل المشترك، والمعاملات من لقطة Pro المراجعة، والمعادلات من `formulas.json` مع سجل الحقول الفعلي. لكل عنصر: المعادلة والرموز والمدخلات والأعمدة الناتجة والوحدات والفقد ومثال محسوب. يبقى عنوان الخريطة موجزًا مثل «متوسط هطول الأمطار»؛ شرح متوسط التراكميات في المنهجية.

يتحقق مولد الدليل من بصمات الدوال العلمية. لا تحدث `formula_review.json` لإسكات الخطأ؛ راجع تغير الحساب واختباراته أولًا. تغيير المعاملات يتطلب إعادة استخراج المرجع بواسطة `scripts/export_help_parameters.py` في Pro مرخص. توليد الدليل المعتاد لا يستورد ArcPy.

لملفات CHM استخدم أوامر `prepare_help_compiler.py --download` ثم `build_chm.py` الموضحة في الدليل الإنجليزي. يثبت التنزيل بالبصمة والتوقيع، ويفك المترجم محليًا دون تركيب DLL داخل Windows أو تسجيل COM عام. افحص العربية والبحث والروابط في قارئ Windows؛ لا ترفع المترجم إلى Git.

## التغييرات العلمية والبيانات

اقرأ دليلي المنهجية بالعربية والإنجليزية و[المراجعة الحالية](MIRSAD%20Desktop/docs/reports/METHODOLOGY_REVIEW.md). تحتاج إضافة المصدر أو العنصر إلى اعتماديات ووحدات وتغطية حقيقية وتتبع مصدر واختبارات عددية مستقلة. المطر المفقود ليس صفرًا. USAF وحده ليس مفتاح محطة؛ احفظ WBAN والموقع والمعرفات النصية بأصفارها. تصحيح الإحداثيات يحتاج دليلًا وترحيلًا قابلًا للتكرار، مع عدم تعديل GDB الأصلية أثناء التدقيق. لا تخفِ فشل FileGDB بنجاح GeoPackage.

## بناء التطبيق

يبني `scripts/build_development.ps1` الأصول والدليل، ويشغل الاختبارات ويفحص EXE ثم يستبدل قناة التطوير الثابتة فقط. نشر إصدار ثنائي أو ترقية stable يحتاج اعتماد المرشح بعينه من صاحب المشروع. لا تنشر CI إصدارًا تلقائيًا.