أوّل مساهمة (Walkthrough)

ماذا ستتعلّم: المسار الكامل لمساهمة صغيرة — من فرع معزول حتى PR إلى dev.

نأخذ مثالًا واقعيًّا: إضافة دالة مضمنة جديدة. الخطوات تعمّ على أي تغيير.

1) افهم الطبقة والتشابك

لا تغيير «معزول». دالة مضمنة تَمَسّ: language-truth/builtins/ (المصدر) + المُولَّد + تنفيذ المفسّر + codegen المترجم + اختبار. راجع الأنظمة المتشابكة.

2) أنشئ فرع عمل معزول (worktree من dev)

cd /c/s_lang/s-programming-language
git fetch origin
git worktree add /c/s_lang/temp-brunch/builtin-جذر -b agent/builtin-جذر origin/dev
cd /c/s_lang/temp-brunch/builtin-جذر

3) ابدأ من مصدر الحقيقة (لا من الكود المُولَّد)

أضف الدالة إلى language-truth/builtins/<domain>.yaml، ثم أعد التوليد:

python x.py gen   # أو مولِّدٌ بعينه: scripts/codegen/gen_all_builtins_yaml.py

4) نفّذ في الطبقة الصحيحة

• المفسّر: interpreter/src/builtins/builtin_*.cpp.
• المترجم: compiler/src/backend/llvm/builders/builtins/*.cpp.

5) اكتب اختبار .ص (إيجابيّ + سلبيّ)

ملف .ص تحت tests/behavior/ (لا تحت tests/ مباشرةً) بصيغة @expected الصحيحة — وtests_dir: tests/behavior في tests/config.yaml هو ما يجعل الـrunner يراه. راجع خريطة المستودع للحِزَم الستّ وأيُّها يناسب اختبارَك.

6) ابنِ وشغّل (تنفيذ مزدوج)

python x.py build                  # المحرّكان معًا في تهيئة واحدة
python tests/runner.py --level P1  # يجب أن يمرّ 100% بلا تراجع

7) أودِع (موقّع GPG) وافتح PR

git add -A
git commit -m "feat(builtins): دالة جذر(...)"     # موقّع تلقائيًّا
git push -u origin agent/builtin-جذر
gh pr create --base dev --title "إضافة جذر" --body "قائمة الملفات + نتائج runner"

8) نظّف بعد الدمج

cd /c/s_lang/s-programming-language
git worktree remove /c/s_lang/temp-brunch/builtin-جذر
git branch -D agent/builtin-جذر

✅ راجع معيار الإنجاز قبل إعلان الانتهاء.

اقرأ بعده: نظرة عامّة على الطبقات.