المساهمة

شكرًا لمساعدتك في تحسين هذا الكتاب. المساهمات بجميع أحجامها مرحَّب بها، من تصحيح خطأ مطبعي إلى كتابة موضوع جديد.

القواعد الأساسية

يتبع الكتاب أسلوبًا صارمًا. أهم ما فيه:

• لا شرطات طويلة (em-dash). استخدم فاصلة أو نقطتين رأسيتين أو أقواسًا أو جملتين.
• لا عبارات جاهزة (“ليس فقط … بل أيضًا”، “load-bearing”، وما شابهها).
• كتابة دافئة وبسيطة ومباشرة. خاطب القارئ بصيغة المخاطَب. جمل قصيرة.
• عرّف المصطلحات عند أول استخدام. اربط المفاهيم الأساسية بويكيبيديا عند أول ذكر.
• مراجع حقيقية فقط.
• كل موضوع عن عائلة مقاييس يسمّي مسار التلاعب به وحاجز الحماية.

القواعد الكاملة في spec/conventions.md في جذر المستودع، والنسخة المختصرة هي قواعد الأسلوب. وتفرض الاختبارات الأجزاء الآلية منها.

الإعداد

تحتاج إلى Python 3 وjust. يضم هذا المستودع محتوى الكتاب ومواصفاته، إضافة إلى موقع SvelteKit (software-engineering-metrics.github.io/) الذي يحوّله إلى الموقع المنشور.

just         # list tasks
just test    # run the validation suite
just nav     # regenerate the generated navigation files
just stats   # topic and word counts

إجراء تغيير

1. اقرأ الدليل المناسب: التأليف للمواضيع، والتنقل للملفات المولَّدة، والاختبار للاختبارات.
2. أجرِ أصغر تغيير يؤدي المهمة.
3. إذا أضفت موضوعًا أو أزلته أو أعدت تسميته أو ترقيمه، فحدّث spec/structure.md في جذر المستودع وشغّل just nav.
4. شغّل just test. يجب أن ينجح.
5. أضف سطرًا واحدًا إلى سجل التغييرات تحت Unreleased.

ما يمكن العمل عليه

• تصحيح الأخطاء أو المقاطع غير الواضحة أو المراجع القديمة.
• تحسين الأمثلة، وبخاصة الأمثلة المؤسسية والحكومية الملموسة.
• التحقق من الاستشهادات مقابل مصادر حقيقية.
• سد الفجوات في تغطية موضوع ما دون كسر القالب.

ما يجب تجنّبه

• لا تحرّر الملفات المولَّدة يدويًا (README.md وindex.md لكل لغة، وfront-matter/table-of-contents.md، وtopics/09-07-index.md). غيّر المواضيع وشغّل just nav بدلًا من ذلك.
• لا تحرّر en-001 أو en-gb أو en-us مباشرة؛ فهي مشتقة من en-gb-oxendict عبر tools/localize.py.
• لا تضف موضوعًا دون تحديث spec/structure.md أيضًا.
• لا تُدخل شرطات طويلة أو العبارات المحظورة؛ ستفشل الاختبارات.

الإبلاغ عن المشكلات

افتح بلاغًا يصف المشكلة والملف والموضوع، وعند اللزوم المصدر أو المرجع الصحيح. البلاغات الصغيرة المحددة هي الأسهل في التعامل معها.