إرشادات المطورين وأسلوب البرمجة

اقرأ دليل المطورين الجدد أولاً.

الإرشادات الأساسية وأسلوب البرمجة

معظم ما يلي يجب أن يكون بديهيًا لأي شخص عمل على برمجيات مفتوحة المصدر أو في بيئة برمجة تجارية. ما يلي ينطبق في الغالب على فرع التطوير الرئيسي i2p.i2p. قد تختلف الإرشادات لفروع أخرى والإضافات والتطبيقات الخارجية بشكل كبير؛ تحقق مع المطور المناسب للحصول على التوجيه.

المجتمع

• من فضلك لا تكتفي بكتابة الكود فقط. إذا استطعت، شارك في أنشطة التطوير الأخرى، بما في ذلك: مناقشات التطوير والدعم على IRC وi2pforum.i2p؛ الاختبار؛ الإبلاغ عن الأخطاء والرد عليها؛ التوثيق؛ مراجعة الكود؛ إلخ.
• يجب أن يكون المطورون النشطون متاحين بشكل دوري على IRC #i2p-dev. كن على دراية بدورة الإصدار الحالية. التزم بمعالم الإصدار مثل تجميد الميزات، تجميد الوسوم، والموعد النهائي للتسجيل الخاص بالإصدار.

دورة الإصدار

دورة الإصدار العادية هي 10-16 أسبوعاً، أربعة إصدارات في السنة. فيما يلي المواعيد النهائية التقريبية ضمن دورة نموذجية مدتها 13 أسبوعاً. يتم تحديد المواعيد النهائية الفعلية لكل إصدار من قبل مدير الإصدار بعد التشاور مع الفريق بأكمله.

• بعد 1-2 يوم من الإصدار السابق: يُسمح بعمليات الإيداع (Check-ins) إلى الجذع (trunk).
• بعد 2-3 أسابيع من الإصدار السابق: الموعد النهائي لنشر التغييرات الرئيسية من الفروع الأخرى إلى الجذع.
• قبل 4-5 أسابيع من الإصدار: الموعد النهائي لطلب روابط جديدة للصفحة الرئيسية.
• قبل 3-4 أسابيع من الإصدار: تجميد الميزات (Feature freeze). الموعد النهائي للميزات الجديدة الرئيسية.
• قبل 2-3 أسابيع من الإصدار: عقد اجتماع المشروع لمراجعة طلبات روابط الصفحة الرئيسية الجديدة، إن وُجدت.
• قبل 10-14 يومًا من الإصدار: تجميد النصوص (String freeze). لا مزيد من التغييرات على النصوص المترجمة (الموسومة). دفع النصوص إلى Transifex، والإعلان عن الموعد النهائي للترجمة على Transifex.
• قبل 10-14 يومًا من الإصدار: الموعد النهائي للميزات. إصلاحات الأخطاء فقط بعد هذا الوقت. لا مزيد من الميزات أو إعادة الهيكلة أو التنظيف.
• قبل 3-4 أيام من الإصدار: الموعد النهائي للترجمة. سحب الترجمات من Transifex وإيداعها.
• قبل 3-4 أيام من الإصدار: الموعد النهائي للإيداع. لا يُسمح بالإيداعات بعد هذا الوقت دون إذن من منشئ الإصدار.
• قبل ساعات من الإصدار: الموعد النهائي لمراجعة الكود.

Git

• امتلك فهمًا أساسيًا لأنظمة التحكم بالمصدر الموزعة، حتى لو لم تستخدم git من قبل. اطلب المساعدة إذا احتجت إليها. بمجرد الدفع، تصبح عمليات الإدخال دائمة؛ لا يوجد تراجع. يُرجى توخي الحذر. إذا لم تستخدم git من قبل، ابدأ بخطوات صغيرة. قم بإدخال بعض التغييرات الصغيرة وانظر كيف تسير الأمور.
• اختبر تغييراتك قبل إدخالها. إذا كنت تفضل نموذج التطوير القائم على الإدخال قبل الاختبار، استخدم فرع التطوير الخاص بك في حسابك الخاص، وأنشئ MR بمجرد الانتهاء من العمل. لا تعطل عملية البناء. لا تتسبب في تراجعات. في حالة حدوث ذلك (يحدث أحيانًا)، يُرجى عدم الاختفاء لفترة طويلة بعد دفع تغييرك.
• إذا كان تغييرك غير تافه، أو كنت تريد من الناس اختباره وتحتاج إلى تقارير اختبار جيدة لمعرفة ما إذا تم اختبار تغييرك أم لا، أضف تعليق إدخال إلى history.txt وقم بزيادة مراجعة البناء في RouterVersion.java.
• لا تُدخل تغييرات كبيرة في الفرع الرئيسي i2p.i2p في وقت متأخر من دورة الإصدار. إذا كان المشروع سيستغرق أكثر من يومين، أنشئ فرعك الخاص في git، في حسابك الخاص، وقم بالتطوير هناك حتى لا تعيق الإصدارات.
• بالنسبة للتغييرات الكبيرة (بشكل عام، أكثر من 100 سطر، أو تمس أكثر من ثلاثة ملفات)، قم بإدخالها في فرع جديد على حساب GitLab الخاص بك، وأنشئ MR، وعيّن مراجعًا. عيّن MR لنفسك. ادمج MR بنفسك بمجرد موافقة المراجع عليه.
• لا تنشئ فروع WIP في حساب I2P_Developers الرئيسي (باستثناء i2p.www). تنتمي WIP إلى حسابك الخاص. عند الانتهاء من العمل، أنشئ MR. يجب أن تكون الفروع الوحيدة في الحساب الرئيسي للفروع الحقيقية، مثل إصدار نقطي.
• قم بالتطوير بطريقة شفافة ومع وضع المجتمع في الاعتبار. أدخل التغييرات بشكل متكرر. أدخل أو ادمج في الفرع الرئيسي بأكبر قدر ممكن من التكرار، بالنظر إلى الإرشادات المذكورة أعلاه. إذا كنت تعمل على مشروع كبير في فرعك/حسابك الخاص، أخبر الناس حتى يتمكنوا من المتابعة والمراجعة/الاختبار/التعليق.

أسلوب البرمجة

• أسلوب البرمجة في معظم أنحاء الكود هو 4 مسافات للمسافة البادئة. لا تستخدم علامات التبويب. لا تعد تنسيق الكود. إذا كان محرر IDE أو المحرر الخاص بك يريد إعادة تنسيق كل شيء، فتحكم فيه. في بعض الأماكن، يختلف أسلوب البرمجة. استخدم الحس السليم. قلّد الأسلوب الموجود في الملف الذي تقوم بتعديله.
• جميع الفئات والطرق العامة والخاصة بالحزمة الجديدة تتطلب Javadocs. أضف @since رقم-الإصدار. يُفضل وجود Javadocs للطرق الخاصة الجديدة.
• بالنسبة لأي Javadocs مضافة، يجب ألا تكون هناك أي أخطاء أو تحذيرات doclint. قم بتشغيل ant javadoc مع Oracle Java 14 أو أعلى للتحقق. يجب أن تحتوي جميع المعاملات على أسطر @param، ويجب أن تحتوي جميع الطرق غير الفارغة على أسطر @return، ويجب أن تحتوي جميع الاستثناءات المعلنة على أسطر @throws، وعدم وجود أخطاء HTML.
• الفئات الموجودة في core/ (i2p.jar) وأجزاء من i2ptunnel هي جزء من API الرسمي الخاص بنا. هناك العديد من الإضافات والتطبيقات الأخرى خارج الشجرة التي تعتمد على هذا API. كن حذرًا حتى لا تقوم بإجراء أي تغييرات تكسر التوافق. لا تضف طرقًا إلى API ما لم تكن ذات فائدة عامة. يجب أن تكون Javadocs لطرق API واضحة وكاملة. إذا أضفت أو غيرت API، قم أيضًا بتحديث الوثائق على الموقع الإلكتروني (فرع i2p.www).
• ضع علامة على السلاسل النصية للترجمة عند الاقتضاء، وهو ما ينطبق على جميع سلاسل واجهة المستخدم. لا تغير السلاسل النصية المميزة الموجودة ما لم يكن ذلك ضروريًا حقًا، لأنه سيكسر الترجمات الموجودة. لا تضف أو تغير السلاسل النصية المميزة بعد تجميد العلامات في دورة الإصدار حتى تتاح للمترجمين فرصة التحديث قبل الإصدار.
• استخدم الأنواع العامة والفئات المتزامنة حيثما أمكن. I2P هو تطبيق متعدد الخيوط بشكل كبير.
• كن على دراية بالمزالق الشائعة في Java التي يتم اكتشافها بواسطة FindBugs/SpotBugs. قم بتشغيل ant findbugs لمعرفة المزيد.
• يُطلب Java 8 لبناء وتشغيل I2P اعتبارًا من الإصدار 0.9.47. لا تستخدم فئات أو طرق Java 7 أو 8 في الأنظمة الفرعية المضمنة: addressbook، core، i2ptunnel.jar (غير UI)، mstreaming، router، routerconsole (الأخبار فقط)، streaming. تُستخدم هذه الأنظمة الفرعية بواسطة Android والتطبيقات المضمنة التي تتطلب Java 6 فقط. يجب أن تكون جميع الفئات متاحة في Android API 14. ميزات لغة Java 7 مقبولة في هذه الأنظمة الفرعية إذا كانت مدعومة من الإصدار الحالي من Android SDK وتم تجميعها إلى كود متوافق مع Java 6.
• لا يمكن استخدام Try‑with‑resources في الأنظمة الفرعية المضمنة لأنها تتطلب java.lang.AutoCloseable في وقت التشغيل، وهذا غير متاح حتى Android API 19 (KitKat 4.4).
• لا يمكن استخدام حزمة java.nio.file في الأنظمة الفرعية المضمنة لأنها غير متاحة حتى Android API 26 (Oreo 8).
• بخلاف القيود المذكورة أعلاه، يمكن استخدام فئات وطرق وتراكيب Java 8 في الأنظمة الفرعية التالية فقط: BOB، desktopgui، i2psnark، i2ptunnel.war (UI)، jetty‑i2p.jar، jsonrpc، routerconsole (باستثناء الأخبار)، SAM، susidns، susimail، systray.
• يمكن لمؤلفي الإضافات طلب أي إصدار Java كحد أدنى عبر ملف plugin.config.
• قم بالتحويل صراحةً بين الأنواع البدائية والفئات؛ لا تعتمد على autoboxing/unboxing.
• لا تستخدم URL. استخدم URI.
• لا تلتقط Exception. التقط RuntimeException والاستثناءات المفحوصة بشكل فردي.
• لا تستخدم String.getBytes() بدون معامل مجموعة أحرف UTF‑8. يمكنك أيضًا استخدام DataHelper.getUTF8() أو DataHelper.getASCII().
• حدد دائمًا مجموعة أحرف UTF‑8 عند قراءة أو كتابة الملفات. قد تكون أدوات DataHelper مفيدة.
• حدد دائمًا لغة (على سبيل المثال Locale.US) عند استخدام String.toLowerCase() أو String.toUpperCase(). لا تستخدم String.equalsIgnoreCase()، حيث لا يمكن تحديد لغة.
• لا تستخدم String.split(). استخدم DataHelper.split().
• لا تضف كودًا لتنسيق التواريخ والأوقات. استخدم DataHelper.formatDate() و DataHelper.formatTime().
• تأكد من إغلاق InputStreams و OutputStreams في كتل finally.
• استخدم {} لجميع كتل for و while، حتى لو كان سطرًا واحدًا فقط. إذا استخدمت {} لأي من كتل if أو else أو if-else، استخدمها لجميع الكتل. ضع } else { على سطر واحد.
• حدد الحقول كـ final حيثما أمكن.
• لا تخزن I2PAppContext أو RouterContext أو Log أو أي مراجع أخرى لعناصر router أو السياق في حقول ثابتة.
• لا تبدأ الخيوط في المُنشئات. استخدم I2PAppThread بدلاً من Thread.

السجلات

تنطبق الإرشادات التالية على الموجه (router)، وتطبيقات الويب، وجميع الإضافات.

• بالنسبة لأي رسائل لا تُعرض في مستوى السجل الافتراضي (WARN، INFO، وDEBUG)، ما لم تكن الرسالة نصاً ثابتاً (بدون دمج نصوص)، استخدم دائماً log.shouldWarn()، log.shouldInfo()، أو log.shouldDebug() قبل استدعاء السجل لتجنب الحمل غير الضروري على الكائنات.
• يجب أن تكون رسائل السجل التي قد تُعرض في مستوى السجل الافتراضي (ERROR، CRIT، وlogAlways()) مختصرة وواضحة ومفهومة للمستخدم غير التقني. يشمل ذلك نص سبب الاستثناء الذي قد يُعرض أيضاً. فكر في الترجمة إذا كان من المحتمل حدوث الخطأ (على سبيل المثال، عند أخطاء إرسال النماذج). خلاف ذلك، الترجمة ليست ضرورية، لكن قد يكون من المفيد البحث عن سلسلة نصية موجودة بالفعل ومُعلّمة للترجمة في مكان آخر وإعادة استخدامها.
• رسائل السجل التي لا تُعرض في مستوى السجل الافتراضي (WARN، INFO، وDEBUG) مخصصة لاستخدام المطورين، ولا تخضع للمتطلبات المذكورة أعلاه. ومع ذلك، رسائل WARN متاحة في تبويب سجل Android، وقد تكون مفيدة للمستخدمين في تصحيح المشكلات، لذا استخدم بعض الحذر مع رسائل WARN أيضاً.
• يجب استخدام رسائل سجل INFO وDEBUG بشكل مقتصد، خاصة في مسارات الكود الحرجة (hot code paths). على الرغم من فائدتها أثناء التطوير، فكر في إزالتها أو تعطيلها بالتعليقات بعد اكتمال الاختبار.
• لا تسجل في stdout أو stderr (سجل wrapper).

التراخيص

• قم فقط بإيداع الكود الذي كتبته بنفسك. قبل إيداع أي كود أو ملفات JAR من مكتبات من مصادر أخرى، قدم مبرراً لضرورة ذلك، وتحقق من توافق الترخيص، واحصل على موافقة من مدير الإصدار.
• إذا حصلت على موافقة لإضافة كود خارجي أو ملفات JAR، وكانت الملفات الثنائية متاحة في أي حزمة Debian أو Ubuntu، يجب عليك تنفيذ خيارات البناء والتعبئة لاستخدام الحزمة الخارجية بدلاً من ذلك. قائمة الملفات التي يجب تعديلها: build.properties، build.xml، debian/control، debian/i2p-router.install، debian/i2p-router.links، debian/rules، sub-build.xml.
• بالنسبة لأي صور يتم إيداعها من مصادر خارجية، تقع على عاتقك مسؤولية التحقق أولاً من توافق الترخيص. قم بتضمين معلومات الترخيص والمصدر في تعليق الإيداع.

الأخطاء

• إدارة المشكلات هي مسؤولية الجميع؛ يرجى المساعدة. راقب GitLab للعثور على المشكلات التي يمكنك المساعدة فيها. قم بالتعليق على المشكلات وإصلاحها وإغلاقها إذا استطعت.
• يجب على المطورين الجدد البدء بإصلاح المشكلات. عندما يكون لديك إصلاح، قم بإرفاق الرقعة الخاصة بك بالمشكلة وأضف الكلمة المفتاحية review-needed. لا تغلق المشكلة حتى تتم مراجعتها بنجاح وتتحقق من تغييراتك. بمجرد القيام بذلك بسلاسة لزوجين من التذاكر، يمكنك اتباع الإجراء العادي أعلاه.
• أغلق المشكلة عندما تعتقد أنك أصلحتها. ليس لدينا قسم اختبار للتحقق من التذاكر وإغلاقها. إذا لم تكن متأكداً من أنك أصلحتها، أغلقها وأضف ملاحظة تقول “أعتقد أنني أصلحتها، يرجى الاختبار وإعادة الفتح إذا كانت لا تزال معطلة”. أضف تعليقاً برقم بناء التطوير أو المراجعة وحدد المرحلة للإصدار التالي.