طلبات الدمج
يصل كل تغيير إلى main عبر طلب دمج على
GitHub ينجح في ci-success.
1. الفرع
ابدأ من main محدَّث، وأنشئ فرعًا يحمل اسم التغيير:
git fetch origin
git switch -c fix/waiting-banner-state origin/main
البادئات مثل feat/ وfix/ وdocs/ وtest/ وchore/ تطابق أنواع الإيداعات في
الأعراف. ويعمل المساهمون الذين لا يملكون صلاحية الكتابة من نسخة متفرّعة.
اجعل كل طلب دمج لمسألة واحدة. ويمكن أن يصل جهد كبير في طلب دمج واحد مبني من عدة إيداعات، بدلًا من طلبات صغيرة كثيرة يعتمد بعضها على بعض.
2. أجرِ التغيير مع اختباراته
- حدّث الاختبارات في التغيير نفسه (تشغيل الاختبارات).
- اشحن كل نص يراه المستخدم بالإنجليزية والعربية.
- افرض أي قاعدة أدوار في الواجهة البرمجية، مع اختبار للدور.
- إذا غيّر التغيير سلوكًا يراه المستخدمون، فحدّث دليل المستخدم في
web/src/help/.
3. تحقّق محليًّا
make lint
make test-unit
make test-integration # if you touched integration boundaries (database, gRPC, queue)
make test-e2e # if you touched user-visible flows
مع تثبيت خطّاف ما قبل الدفع، يشغّل git push أيضًا بوابة الاختبارات المتأثرة والاختبارات
المتأثرة الآمنة للتشغيل محليًّا.
4. افتح طلب الدمج
git push -u origin fix/waiting-banner-state
gh pr create --base main
يتبع المتن القالب .github/PULL_REQUEST_TEMPLATE.md:
## Summary
- What changed and why, in 1 to 3 bullets. Link the story or issue.
## Test plan
- [ ] `make lint`
- [ ] `make test-unit`
- [ ] `make test-integration` (if changes touch integration boundaries)
- [ ] `make test-e2e` (if changes touch user-visible flows)
## Force-merge override (delete if N/A)
force-merge: <one-sentence reason; at least 10 characters>
- املأ خطة الاختبار بما شغّلته فعلًا، مع أي فحوص يدوية (مثل الشاشة التي فحصتها بالعربية، أو التطبيق الذي جرّبته على محاكٍ).
- احذف قسم الدمج القسري ما لم يكن الوسم
force-mergeموضوعًا على طلب الدمج؛ فمهمةpr-body-checkتقرأ ذلك السطر بوصفه سجل التدقيق. - أضف لقطات شاشة لتغييرات الواجهة، باللغتين حيث يختلف التخطيط.
5. التكامل المستمر
يشغّل التكامل المستمر المهام التي تختارها ملفاتك المتغيّرة (التكامل المستمر). أما مهام الشيفرة غير المرتبطة فلا تُشغَّل ولا تمنع الدمج. أصلح أي فشل في الفرع نفسه؛ فالمهمة الحمراء التي سببها التغيير لا يُلتفّ عليها بالدمج أبدًا.
6. المراجعة
- يحصل كل طلب دمج على مراجعة للشيفرة قبل الدمج. يبحث المراجعون في الصحة، وفي اختبارات تغطي التغيير، وفي الأعراف المذكورة أعلاه، وفي الأمان (قواعد الأمان).
- أجب عن كل تعليق بإصلاح أو بسبب. ادفع الإصلاحات إيداعاتٍ جديدة ليبقى سجل المراجعة مقروءًا.
- أعد تشغيل الفحوص المرتبطة بعد الإصلاحات.
7. الدمج
حين يكون ci-success أخضر وتكتمل المراجعة، ادمج في main. واحذف الفرع بعد ذلك.
تُقطع الإصدارات بوضع وسوم على الإيداعات الخضراء في main.
تغييرات الوثائق والمواصفات
التغييرات المقتصرة على specs/ أو docs/ أو ملفات Markdown لا تشغّل إلا المهام التي تشمل
مرشّحاتها تلك الملفات، لذا تنتهي عادةً بسرعة. لكنها ما زالت تحتاج إلى ملخص واضح
ومراجعة.
العربية والإنجليزية
يحمل maktaba.dev كل صفحة بالإنجليزية والعربية، ويفشل بناؤه حين تختلف اللغتان، لذا يصل كل تغيير فيما ينشره باللغتين معًا في طلب الدمج نفسه:
- الدليل في
docs/developers/له توأمه العربي بجانبه (name.mdوname.ar.md). غيّر الاثنين معًا، أو أضف الاثنين لدليل جديد. - مُدخل سجل التغييرات يُكتب في
CHANGELOG.md، ويُكتب بالعربية فيCHANGELOG.ar.md: في الإصدار نفسه، والقسم نفسه، والموضع نفسه من القائمة. - وصف الواجهة البرمجية: كل ملخص أو وصف جديد أو معدَّل في
shared/api/openapi.jsonتُكتب ترجمته العربية فيshared/api/openapi.ar.json(مفتاحها مؤشّر JSON الخاص به، ومعها النص الإنجليزي الذي تترجمه).
اكتب بعربية فصحى معاصرة سليمة. أما الشيفرة والأوامر وأسماء الملفات والمعرّفات فتبقى كما هي.
إصلاحات الأمان
لا تفتح طلب دمج عامًّا أو مسألة عامة تصف ثغرة لم تُصلَح. أبلغ عنها أولًا عبر security@maktaba.dev؛ وراجع سياسة الإبلاغ.