عن هذا المشروع

توثيق المشروع للكتاب: كيف رُكّب، وكيف يُبنى ويُفحص، وأين مصدر الحقيقة. وللكتاب نفسه، انظر جدول المحتويات.

خريطة المشروع

• الكتاب: منشور بأربع محليات تحت locales/؛ انظر spec/locales.md. هذه المحلية، en-gb-oxendict/topics/ (63 ملفًا)، وen-gb-oxendict/front-matter/، وملاحق الجزء 9 هي المصدر المكتوب يدويًا؛ أما en-001 وen-gb وen-us فمشتقة منها.
• مصدر الحقيقة: spec/ في جذر المستودع (غير منشور في الموقع). البنية معلنة في spec/structure.md، وقواعد الكتابة في spec/conventions.md، والإملاء في spec/oxford-spelling.md. وكل ما عداه يُبنى ليطابقها.
• الأدوات: يشتق tools/localize.py المحليات الثلاث الأخرى؛ ويولّد tools/gen_nav.py التنقل؛ ويفرض tests/validate.py المواصفات؛ ويربطها justfile معًا.
• إرشادات المساهمين: AGENTS.md في جذر المستودع، والأدلة في قسم المساهمة.

البناء والفحص

تعمل حزمة التحقق على Python 3 دون أي اعتمادات أخرى ودون شبكة. وتُشغَّل المهام عبر just.

just test    # validate structure, style, links, and spec-vs-disk
just nav     # regenerate the generated navigation files
just check   # nav, then test
just stats   # topic and word counts

يضم هذا المستودع محتوى الكتاب ومواصفاته. ويُعرض موقعًا إلكترونيًا بواسطة مستودع software-engineering-metrics.github.io المنفصل.

كيف يعمل التطوير القائم على المواصفات هنا

المواصفات أولًا. يحدد spec/structure.md أي المواضيع موجودة وكيف تُرقَّم. ويحدد spec/conventions.md كيف يجب أن تُكتب. وتُؤلَّف المواضيع لتلبّي الاثنين. ويشتق tools/gen_nav.py التنقل من المواضيع، ويفحص tests/validate.py النتيجة مقابل المواصفات. وإذا اختلفت المواضيع والمواصفات يومًا فشلت الاختبارات، وتلك إشارة لإعادتهما إلى الاتساق.

وهذا يمنع الانحراف: فلا يكون التغيير “منجزًا” إلا حين تتفق المواصفات والمواضيع والتنقل المولَّد والاختبارات جميعًا.

قرارات تصميم تستحق المعرفة

• مواضيع مسطّحة بترقيم عشري. الملفات هي locales/<locale>/topics/PP-CC-slug.md، وهي الأسماء المختصرة نفسها في كل محلية. الجزء عدد صحيح؛ والموضوع عدد عشري؛ وN.0 مقدمة الجزء. وهذا يحفظ معرّفات ثابتة ويتيح للأدوات الفرز والتجميع دون شجرة أدلة.
• محلية واحدة مكتوبة يدويًا وثلاث مشتقة. en-gb-oxendict هي الإملاء الأكسفوردي، الأسلوب المعتمد لدى معظم هيئات المعايير الدولية (انظر spec/oxford-spelling.md)؛ أما en-001 وen-gb وen-us فمشتقة منها آليًا، فلا ينحرف التوطين عن المصدر.
• تنقل مولَّد. جدول المحتويات وصفحة المحتويات والفهرس الموضوعي مولَّدة، فلا تنحرف عن المواضيع.
• اختبارات دون اتصال ودون اعتمادات. تستخدم الحزمة المكتبة القياسية فقط لتعمل في أي مكان، بما فيه التكامل المستمر وخطّافات ما قبل الإيداع.
• الإحالات المتبادلة تبقى نصًا عاديًا. يشير النثر إلى المواضيع بالرقم العشري (“انظر الموضوع 2.1”)، كما تشترط المواصفات؛ والموقع المنشور هو المسؤول عن تحويل هذه الإحالات إلى روابط.
• لا شرطات طويلة، بالقاعدة وبالاختبار. خيار أسلوبي مقصود، يُفرض ليبقى صحيحًا مع نمو الكتاب.
• كل عائلة مقاييس تسمّي مسار التلاعب الخاص بها. وهذه هي القاعدة الوحيدة في القالب التي لا مثيل لها في المشروع الشقيق software-engineering-guide: فهي موجودة لأن موضوع هذا الكتاب كله هو القياس، ولذلك يجب أن يكون خطر القياس نفسه من الدرجة الأولى لا ضمنيًا.

مزيد من القراءة

• التأليف : كتابة المواضيع وتحريرها.
• التنقل : كيف تعمل الملفات المولَّدة.
• الاختبار : ما الذي تفحصه الاختبارات وكيف تصلح الإخفاقات.
• أمثلة : أمثلة صغيرة وملموسة.
• سجل التغييرات : تاريخ التغييرات المهمة.