دليل الإسهام

يقبل DispatchAtlas التغييرات التي تحفظ حدود الحزم، والأدلّة الحتمية، والادّعاءات العامة المُبوَّبة-بالإصدار. وتُكتَب الإسهامات من عقود المستودع — لا تُنسَخ من أشجار مصدر خارجية، أو تقارير مُولَّدة، أو مُنتَجات تجارب غير منشورة. وCONTRIBUTING.md الجذري هو قائمة التحقّق المرجعية؛ وتُطابِق هذه الصفحة بينه وبين قاعدة الكود.

🧭 اختر مسارك

تعيش قواعد حدود كل مجلد في AGENTS.md الجذري؛ ويحمل كل مجلد حزمة أيضًا README.md الخاص به.

النيّة	المسار	أين
إصلاح خطأ حلّال	سجلّ الحلّالات، أو المُشغِّلات، أو الميتاهيوريستيك، إضافةً إلى اختبارات السلوك.	`packages/dispatchatlas-solve/` (راجِع README الخاص به) و`tests/solve/`.
إضافة عائلة نسخ مرجعية	مولِّد، ومُدخَل تصنيف، وصفّ مصفوفة استشهاد، وتوصيل كتالوج.	`packages/dispatchatlas-bench/` (راجِع README الخاص به) و`tests/bench/`.
توسيع عقود المجال	نموذج الجدولة، والتحقّق، والمنشأ، أو التسلسل في الحدّ الداخلي.	`packages/dispatchatlas-core/` (راجِع README الخاص به) و`tests/core/`.
تحسين تنفيذ الحملات	التهيئة، والميزانيات، ونقاط التفتيش، وإعادة المحاولات، والتقاط البيئة.	`packages/dispatchatlas-lab/` (راجِع README الخاص به) و`tests/lab/`.
توسيع صادرات التحليل	الإحصاء، وترشيح الإفصاح، وحِزَم الأدلّة، ومجموعات بيانات البوابة، وCLI.	`packages/dispatchatlas-analytica/` (راجِع README الخاص به) و`tests/analytica/`.
تحسين التوثيق	صفحات الموقع على حزمة توثيق Next.js.	`site/content/docs/` (راجِع `site/README.md`).
إضافة مثال قابل للتنفيذ	أمثلة بمقياس دخاني، قابلة للتهيئة، آمنة-للعموم.	`examples/` (يَسرد README الخاص به سِلال الأمثلة والقواعد).
تحسين أدوات الجودة	بوّابات build، وprose-register، وcode-first، وlicense-header.	`tools/` (راجِع README الخاص به) و`tests/tools/`.
الإبلاغ عن خطأ أو طرح سؤال	نماذج issue منظَّمة وقنوات الدعم.	نماذج Issue و`SUPPORT.md`.

⚙️ الإعداد المحلي

ثبّت Python 3.12 أو أحدث.
ثبّت uv.
شغّل uv sync --all-extras --group dev.
شغّل uv run pre-commit install إن أردت خطّافات commit محلية.

✅ الفحوص المحلية

شغّل هذه قبل فتح pull request — يُشغِّل CI المُستضاف مجموعة البوّابات نفسها عبر مصفوفة نظام التشغيل وPython:

uv run ruff format --check .
uv run ruff check .
uv run mypy packages tests tools examples
uv run coverage run -m pytest
uv run coverage report
uv run python tools/check_prose_register.py
uv run python tools/check_code_first.py
uv run python tools/check_root_outputs.py
uv run python tools/check_solver_metaphors.py
uv run python tools/license_header.py check
uv run reuse lint
gitleaks detect --source . --redact --config .gitleaks.toml
npm --prefix site run build
npm --prefix site run check
npm --prefix site audit --audit-level=moderate
uv run pip-audit --path .\.venv\Lib\site-packages --progress-spinner off

لفحوص دخان بناء الحزم:

uv run python tools/build_packages.py
uv venv .package-smoke
uv pip install --python .\.package-smoke\Scripts\python.exe (Get-ChildItem .\packages\*\dist\*.whl)
.\.package-smoke\Scripts\python.exe -c "import dispatchatlas, dispatchatlas.core, dispatchatlas.bench, dispatchatlas.solve, dispatchatlas.lab, dispatchatlas.analytica"

📦 الحدود

أبقِ عمليات الاستيراد داخل اتجاه الاعتماد المُوثَّق — راجِع نظرة عامة على البنية للمخطّط وجدول الاستيراد لكل حزمة. الصيغة المختصرة:

dispatchatlas.core هو الحدّ الداخلي للمجال ولا يستورد أي حزمة DispatchAtlas.
dispatchatlas.bench وdispatchatlas.solve يعتمدان على core فقط.
dispatchatlas.lab يُركّب حزم core وbenchmark وsolver.
dispatchatlas.analytica يستهلك عقود core والبيانات المستقرّة.
site/ يستهلك الصادرات المعتمَدة؛ ويَفحَص tools/ وCI كل حزمة لكنهما ليسا اعتماديّ زمن تشغيل للمنتَج.

يُفرَض الحدّ عبر tests/architecture/test_import_boundaries.py، فيُفشِل استيرادٌ عابرٌ حزمةَ الاختبارات قبل المراجعة.

📋 توقّعات pull request

المجال	التوقّع
الكود	أبقِ عمليات الاستيراد داخل اتجاه الاعتماد المُوثَّق.
البيانات	عامِل مخرجات الحملات كدليل مُولَّد، لا ملفات مصدر.
التوثيق	استخدم لغة DispatchAtlas للإصدار-الأول، وأبقِ دليل الدخان مُعنونًا، وحدِّث الصفحات حين يتغيّر السلوك المُوجَّه-للمستخدم.
الاختبارات	أضِف تأكيدات سلوك للعقود العامة الجديدة؛ صِف السلوك المتوقَّع بدلًا من إعادة إنتاج البنية الخارجية.
الأمان	لا تُودِع بيانات اعتماد، أو أدلّة خاصة، أو أسرار نشر.
المُنتَجات المُولَّدة	أبقِ الذواكر المؤقّتة، ومخرجات البناء، وتقارير التغطية، ومخرجات التجارب، ونقاط التفتيش خارج Git ما لم تُسمِّها سياسةُ مستودع مصدرًا متعقَّبًا.

🤝 المجتمع والدعم

تُلخَّص قنوات المجتمع، ونماذج issue، وفئات النقاش في صفحة المجتمع. ودورة حياة الإسهام — اقترح، واءِم، نفّذ، راجِع، ادمج — مُسجَّلة في GOVERNANCE.md.