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