تحتوي هذه الصفحة على تفاصيل مشروع كتابة تقنيّة تم قبوله في موسم المستندات من Google.
ملخص المشروع
- المؤسسة المفتوحة المصدر:
- موجا عالميًا
- الكاتب التقني:
- التلازيباندا
- اسم المشروع:
- مستندات حول دليل الإعداد الفني لاستخدام FLINT
- مدة المشروع:
- المدة العادية (3 أشهر)
وصف المشروع
تقديم مستندات عن دليل الإعداد الفني لاستخدام FLINT وذلك لتوجيه المساهمين الجُدد من خلال إعداد فني ليتمكّن المساهمون الجدد من البدء بسهولة من خلال الحصول على الحدّ الأدنى من الدعم من خبراء الصيانة
مشكلات المشروع
في ما يلي قائمة بأهم المشاكل المتعلقة بالمستندات الحالية: - أجزاء غير منظَّمة من تعليمات دليل الإعداد المحلي، ما يصعّب على المساهِم الجديد بدء عمله. - المستودعات المتعدّدة الخاصة بأداة FLINT تفتقر إلى المستندات المتعلّقة بالغرض منها وغير مرتبطة ببعضها، ما يجعل من الصعب على المستخدم الجديد تحديد المستودع الذي سيتم تثبيته. - يتم توثيق عملية تثبيت نظام التشغيل Windows جيدًا لكن هناك مجال للتحسين مع وثائق التثبيت القائمة على نظام Linux. - سير عمل Git ليس حاليًا جزءًا من الوثائق
الحل المقترح
ويقدم هذا الاقتراح حلاً لتوجيه المساهمين الجدد من خلال الإعداد التقني حتى يتمكن المساهمون الجدد من البدء بسهولة بأقل قدر من الدعم من عاملي الصيانة. يمكن تحقيق ذلك عن طريق إعادة هيكلة الوثائق الحالية لجعلها مناسبة للمبتدئين وكذلك الاحتفاظ بمستودع مركزي مستقل لجميع الوثائق المتاحة. ينقسم المشروع إلى ثلاث مراحل:- مراجعة الوثائق الحالية وإعادة البناء: تهدف هذه المرحلة إلى مراجعة الدليل الحالي وإعادة صياغته بطريقة تجعله موجزًا ويسهل فهمه من قبل المساهمين الجدد. ويجب أيضًا تعديل المستندات لتكون أكثر ملاءمةً للمبتدئين من خلال إضافة شارات ورموز تعبيرية ومعلومات حول المشاكل المصنّفة على أنّها علامات للمستخدمين الجدد فقط أو علامات جيدة للعدد الأول. - إنشاء مستودع مركزي مستقل للوثائق: الهدف من هذه المرحلة هو ربط جميع الوثائق المتوفرة بترتيب منطقي تسلسلي في مستودع مستقل. يتضمن ذلك طلب إرشادات المساهمة وتعليمات إعداد المشروع والأدلة خطوة بخطوة. - إضافة سير عمل مطوّر البرامج وموقع المنتدى الإلكتروني للمطوّرين الجدد: الهدف من هذه المرحلة هو إضافة سير عمل المطوِّر الذي يتضمّن إرشادات المساهمة عبر git والبنية التكنولوجية للمشروع مع إرشادات الاختبار وتأكيد الجودة. سيكون موقع المنتدى المُقترَح عبارة عن تطبيق من صفحة واحدة يعرض سير العمل والمشاكل التي تظهر لأول مرة ويمكن للمساهمين الجدد المطالبة بها، بالإضافة إلى قائمة بجميع المساهمين. المرحلة 1: مراجعة الوثائق الحالية وإعادة البناء:
يُرجى تعديل المستندات الحالية الخاصة بالمستودعات التالية: - FLINT: المستندات الحالية ليست مفصّلة بشكل كبير ولا تقدّم ترتيبًا تسلسليًا للمكتبات المطلوبة. تنقسم أدلة التعليمات المفصّلة إلى ملفات PDF مختلفة ولكن يمكن توحيدها في مكان واحد بطريقة أكثر إيجازًا. أيضًا، تتوافق أدلة التثبيت مع النوافذ، ولكن قد تكون إعادة توجيه تثبيت نظام التشغيل Linux إلى مستودع FLINT.docker مفيدة. - FLINT.docker: لا توفّر المستندات الحالية الغرض من إعداد هذا المستودع، وهو توفير تثبيت FLINT من خلال Docker على نظام التشغيل Linux. يقتصر الدعم من خلال Docker على Ubuntu 18.04 (Bionic Beaver) فقط، لكن يمكن توسيعه ليشمل توزيعات أخرى تستند إلى Linux. يجب أن تركِّز المستندات الحالية أيضًا على الطريقة التسلسلية لإعداد ملفات Dockerfiles بالإضافة إلى معلومات كافية حول كيفية الإنشاء من الملف الإنشاء. - FLINT.example: لا تشير المستندات الحالية إلى الغرض من إعداد هذا المستودع، وهو تقديم مثال حول كيفية استخدام FLINT. ويمكن الفصل بين عمليات تشغيل العينات المختلفة بشكل أفضل باستخدام تعليمات محددة لتشغيلها. نحتاج أيضًا إلى ربط هذا المستودع بمستودع FLINT الرئيسي لدينا، ما يوفّر للمستخدمين طريقة للانتقال هنا للاطّلاع على المثال عمليًا.
يجب إضافة المعلومات التالية إلى المستندات الحالية: - استخدام Git وGitHub: سيتضمّن ذلك تعليمات مفصّلة حول كيفية إجراء تفرع ونسخ ثم ضبط الإعداد الرئيسي للمستودع عن بُعد. وستوفّر أيضًا معلومات حول كيفية إعادة المقارنة مع أحدث إصدارات الدمج الرئيسية والتعامل مع تعارضات الدمج. - الشارات والرموز التعبيرية: تفتقر المستندات الحالية إلى الشارات والرموز التعبيرية، ما يساعد في الشعور بالترحيب للمساهمين الجدد وحلّ المشاكل الصعبة. - معلومات حول القضايا الملائمة للمبتدئين/للمبتدئين: سيساعد هذا على إعادة توجيه المساهمين الجدد إلى مسائل ملائمة للمبتدئين وإلى موقع المنتدى. - معلومات حول مستودع "Import-me" (استيراد ما): يعمل مستودع "Import-me" (استيرادي) كنموذج أساسي لبدء أي مستودع Moja Global على الفور. تفشل الوثائق الحالية في ذكر مدى أهمية ذلك. يجب تحديثه للإشارة إلى مستودع "Import-me" (استيراد ما) ويجب أيضًا إضافة خطوات اختيار هذا كنموذج لإنشاء مستودع جديد. وينبغي أيضًا أن تكون هناك عملية ثابتة للمبرمجين لاقتراح ميزات إضافية لمستودع "Import-me" (استيراد ما).
المرحلة 2: إنشاء مستودع مركزي مستقل للوثائق :
الأداة المستخدمة لمنصة الاستضافة:
الأدوات المقترَحة لمنصّة الاستضافة هذه هي "قراءة المستندات" للأسباب التالية:- - حصل موقعك الإلكتروني على ترتيب عالٍ بين منصات الاستضافة المختلفة. - التحديث التلقائي عند دفع الإتمام - يتوفّر دعم سهل الإعداد وتحديد المشاكل وحلّها بسهولة بسبب استخدامها من قِبل المجتمع الكبير - يتم تنسيق الوثائق باستخدام reOrganizationText (النص المنظَّم) ويتم تجميع المخرجات بواسطة Sphinx.
تنظيم كل المحتوى بطريقة تسلسلية منطقية:
والترتيب المقترَح للمحتوى على النحو التالي:- - مقدمة عن مستندات المطوِّرين: سيتناول هذا القسم مقدمة عن Moja Global وFLINT. - المساهمة: سيتكوّن هذا القسم من أقسام فرعية بعنوان "طرق المساهمة" (طرق تقديم التقارير للأخطاء البرمجية/إعداد التقارير/الترجمة/التوثيق/تنظيم الأحداث وغير ذلك) و"قواعد السلوك". - إعداد التطوير: سيتكوّن هذا القسم من أقسام فرعية بعنوان "Git & GitHub Workflow" و"تثبيت نظام التشغيل Windows" و"تثبيت نظام التشغيل Windows". - انضم إلينا: سيوفر هذا القسم المنتديات الاجتماعية المختلفة مثل قنوات Slack بهدف التواصل والعمل مع Moja Global.
المرحلة 3: إضافة سير عمل مطوّري البرامج والموقع الإلكتروني للمنتدى للمساهمين الجدد:
مستندات سير عمل المطوِّر:
ستتألف وثائق سير عمل المطوِّر من الأقسام الفرعية التالية:
- تم استخدام حزمة Tech Stack وبنية نظام التشغيل والوحدات المختلفة في الرمز البرمجي: مستند لتعريف المساهمين الجدد بحزمة Tech SDK التي تم تنفيذها، والمكتبات والوحدات المتنوعة في قاعدة الرموز.
- أدوات الاختبار والتغطية المتكاملة: التعريف بمساهمين جُدد في أدوات خطوط CI/CD المستخدمة في الاختبار، وبرامج تتبُّع التغطية، وعمليات فحص الجودة الآلية التي يتم تنفيذها مع رموزهم البرمجية. كما تزويدهم بالإرشادات حول الشخص الذي يجب التعامل معه في حالة فشل الاختبارات.
- برامج التتبُّع المستخدمة لتسهيل سير العمل، مثل Zulipbot: تصميم نماذج محتوى لبرامج التتبُّع ليتم عرضها وتوفير المستندات للسماح للمستخدمين بفهم برامج التتبُّع وتحسين إعداداتها من خلال المساهمة
- الاختبار اليدوي لطلب السحب وإرساله: الوثائق التي سيتم تقديمها حول كيفية اختبار طلبات السحب يدويًا وفقًا لمعايير معيّنة وتحميل النتائج من حيث لقطات الشاشة أو ملفات GIF عند إرسال طلبات السحب.
- سحب إرشادات طلب المراجعة ليتبعها المساهمين: إرشادات حول الإشارة إلى فِرق معيّنة للمراجعة وإضافة تصنيفات مثل "بحاجة إلى المراجعة" إلى طلب السحب للسماح للمسؤولين بالرد على الطلب.
موقع ويب المنتدى:
سيتضمن موقع المنتدى الميزات التالية:
- معلومات حول سير العمل: سيتكوّن سير العمل من سلسلة إجراءات يمكن أن يبدأ بها مساهم جديد، أي المطالبة بمشكلة في الموقّتات الأولى، يليها إنشاء مشكلة متعلّقة بالموقتات الأولى لشخص آخر ومساعدة الآخرين من خلال تقديم ملاحظات ومراجعة طلبات السحب.
- قائمة بمشاكل الموقّت الأول فقط: قائمة بالمشاكل المخصّصة للمستخدمين الجدد أو المساهمين الجدد
- قائمة بالمشاكل القديمة: هي قائمة بالمشاكل التي لم يتم العمل عليها منذ فترة طويلة، ويمكن للمساهمين اختيار هذه المشاكل من خلالها.
- قائمة المساهمين: قائمة بالمساهمين الذين ساهموا حتى الآن في مستودعات Moja العالمية.
- المساهمون الجدد: قائمة بالمساهمين الذين ساهموا مؤخرًا في مستودعات Moja العالمية.
- روابط للانضمام إلى منتديات المحادثة: معلومات وروابط للانضمام إلى منتدى Slack لحل استفساراتهم وإجراء مزيد من المناقشات حول المشاريع.