डेवलपर दिशानिर्देश और कोडिंग शैली

पहले New Developers Guide पढ़ें।

बुनियादी दिशानिर्देश और कोडिंग शैली

निम्नलिखित में से अधिकांश बातें किसी भी व्यक्ति के लिए सामान्य ज्ञान होनी चाहिए जिसने open source पर काम किया है या व्यावसायिक programming environment में काम किया है। निम्नलिखित मुख्य रूप से main development branch i2p.i2p पर लागू होता है। अन्य branches, plugins, और external apps के लिए दिशानिर्देश काफी भिन्न हो सकते हैं; मार्गदर्शन के लिए उपयुक्त developer से संपर्क करें।

समुदाय

• कृपया केवल कोड न लिखें। यदि आप कर सकते हैं, तो अन्य विकास गतिविधियों में भाग लें, जिनमें शामिल हैं: IRC और i2pforum.i2p पर विकास चर्चा और समर्थन; परीक्षण; बग रिपोर्टिंग और प्रतिक्रियाएं; दस्तावेज़ीकरण; कोड समीक्षा; आदि।
• सक्रिय डेवलपर्स को समय-समय पर IRC #i2p-dev पर उपलब्ध रहना चाहिए। वर्तमान रिलीज़ साइकिल से अवगत रहें। रिलीज़ के लिए फीचर फ्रीज, टैग फ्रीज और चेक-इन डेडलाइन जैसे रिलीज़ मील के पत्थर का पालन करें।

रिलीज़ चक्र

सामान्य रिलीज़ चक्र 10–16 सप्ताह का होता है, वर्ष में चार रिलीज़। एक विशिष्ट 13-सप्ताह के चक्र में अनुमानित समय सीमाएँ निम्नलिखित हैं। प्रत्येक रिलीज़ के लिए वास्तविक समय सीमाएँ रिलीज़ प्रबंधक द्वारा पूरी टीम से परामर्श के बाद निर्धारित की जाती हैं।

• पिछली रिलीज़ के 1-2 दिन बाद: trunk में Check-ins की अनुमति है।
• पिछली रिलीज़ के 2-3 सप्ताह बाद: अन्य branches से trunk में बड़े बदलाव propagate करने की अंतिम तिथि।
• रिलीज़ से 4-5 सप्ताह पहले: नए home page links के अनुरोध की अंतिम तिथि।
• रिलीज़ से 3-4 सप्ताह पहले: Feature freeze। प्रमुख नई सुविधाओं की अंतिम तिथि।
• रिलीज़ से 2-3 सप्ताह पहले: नए home page link अनुरोधों की समीक्षा के लिए प्रोजेक्ट मीटिंग आयोजित करें, यदि कोई हो।
• रिलीज़ से 10-14 दिन पहले: String freeze। अनुवादित (tagged) strings में कोई और बदलाव नहीं। Transifex पर strings push करें, Transifex पर अनुवाद की अंतिम तिथि की घोषणा करें।
• रिलीज़ से 10-14 दिन पहले: Feature अंतिम तिथि। इस समय के बाद केवल bug fixes। अब और कोई features, refactoring या cleanup नहीं।
• रिलीज़ से 3-4 दिन पहले: अनुवाद की अंतिम तिथि। Transifex से अनुवाद pull करें और check in करें।
• रिलीज़ से 3-4 दिन पहले: Check-in अंतिम तिथि। इस समय के बाद release builder की अनुमति के बिना कोई check-ins नहीं।
• रिलीज़ से कुछ घंटे पहले: Code review अंतिम तिथि।

Git

• वितरित स्रोत नियंत्रण प्रणालियों की बुनियादी समझ रखें, भले ही आपने पहले git का उपयोग न किया हो। यदि आपको आवश्यकता हो तो सहायता मांगें। एक बार push करने के बाद, check-in हमेशा के लिए होते हैं; कोई undo नहीं है। कृपया सावधान रहें। यदि आपने पहले git का उपयोग नहीं किया है, तो छोटे कदमों से शुरुआत करें। कुछ छोटे बदलाव check in करें और देखें कि यह कैसे चलता है।
• अपने बदलावों को check in करने से पहले परीक्षण करें। यदि आप check-in-before-test विकास मॉडल पसंद करते हैं, तो अपने खाते में अपनी स्वयं की development branch का उपयोग करें, और काम पूरा होने के बाद एक MR बनाएं। build को न तोड़ें। regressions न करें। यदि आप ऐसा करते हैं (यह होता है), तो कृपया अपने बदलाव को push करने के बाद लंबे समय तक गायब न हों।
• यदि आपका बदलाव गैर-तुच्छ है, या आप चाहते हैं कि लोग इसका परीक्षण करें और आपको यह जानने के लिए अच्छी test reports चाहिए कि आपके बदलाव का परीक्षण किया गया था या नहीं, तो history.txt में एक check-in comment जोड़ें और RouterVersion.java में build revision बढ़ाएं।
• release cycle के अंत में मुख्य i2p.i2p branch में बड़े बदलाव check in न करें। यदि किसी प्रोजेक्ट में आपको कुछ दिनों से अधिक समय लगेगा, तो git में अपने खाते में अपनी branch बनाएं, और वहां विकास करें ताकि आप releases को block न करें।
• बड़े बदलावों के लिए (आम तौर पर, 100 से अधिक पंक्तियां, या तीन से अधिक फाइलों को छूना), इसे अपने GitLab खाते पर एक नई branch में check in करें, एक MR बनाएं, और एक reviewer नियुक्त करें। MR को स्वयं को assign करें। एक बार reviewer इसे approve कर दे, तो MR को स्वयं merge करें।
• मुख्य I2P_Developers खाते में WIP branches न बनाएं (i2p.www के अलावा)। WIP आपके अपने खाते में होनी चाहिए। जब काम पूरा हो जाए, तो एक MR बनाएं। मुख्य खाते में केवल सच्चे forks के लिए branches होनी चाहिए, जैसे कि एक point release।
• पारदर्शी तरीके से और समुदाय को ध्यान में रखते हुए विकास करें। अक्सर check in करें। उपरोक्त दिशानिर्देशों को देखते हुए, जितनी बार संभव हो मुख्य branch में check in या merge करें। यदि आप अपनी branch/खाते में किसी बड़े प्रोजेक्ट पर काम कर रहे हैं, तो लोगों को बताएं ताकि वे साथ चल सकें और review/test/comment कर सकें।

कोडिंग शैली

• अधिकांश कोड में coding style इंडेंटेशन के लिए 4 spaces है। tabs का उपयोग न करें। कोड को reformat न करें। यदि आपका IDE या editor सब कुछ reformat करना चाहता है, तो इसे नियंत्रित करें। कुछ जगहों पर, coding style अलग है। सामान्य समझ का उपयोग करें। जिस फ़ाइल को आप संशोधित कर रहे हैं उसमें style का अनुकरण करें।
• सभी नए public और package-private classes और methods के लिए Javadocs की आवश्यकता है। @since release-number जोड़ें। नए private methods के लिए Javadocs वांछनीय हैं।
• जोड़े गए किसी भी Javadocs के लिए, कोई doclint errors या warnings नहीं होनी चाहिए। जांच करने के लिए Oracle Java 14 या उच्चतर के साथ ant javadoc चलाएं। सभी params में @param lines होनी चाहिए, सभी non-void methods में @return lines होनी चाहिए, सभी declared thrown exceptions में @throws lines होनी चाहिए, और कोई HTML errors नहीं होनी चाहिए।
• core/ (i2p.jar) में classes और i2ptunnel के हिस्से हमारे आधिकारिक API का हिस्सा हैं। कई out-of-tree plugins और अन्य applications हैं जो इस API पर निर्भर हैं। compatibility को तोड़ने वाले कोई भी परिवर्तन न करने में सावधानी बरतें। API में methods तब तक न जोड़ें जब तक कि वे सामान्य उपयोगिता के न हों। API methods के लिए Javadocs स्पष्ट और पूर्ण होने चाहिए। यदि आप API जोड़ते या बदलते हैं, तो website पर documentation को भी अपडेट करें (i2p.www branch)।
• translation के लिए strings को उपयुक्त रूप से tag करें, जो सभी UI strings के लिए सही है। मौजूदा tagged strings को तब तक न बदलें जब तक वास्तव में आवश्यक न हो, क्योंकि यह मौजूदा translations को तोड़ देगा। release cycle में tag freeze के बाद tagged strings को add या change न करें ताकि translators को release से पहले अपडेट करने का मौका मिल सके।
• जहां संभव हो generics और concurrent classes का उपयोग करें। I2P एक अत्यधिक multi-threaded application है।
• सामान्य Java pitfalls से परिचित रहें जो FindBugs/SpotBugs द्वारा पकड़े जाते हैं। अधिक जानने के लिए ant findbugs चलाएं।
• release 0.9.47 के अनुसार I2P को build और run करने के लिए Java 8 आवश्यक है। embedded subsystems में Java 7 या 8 classes या methods का उपयोग न करें: addressbook, core, i2ptunnel.jar (non‑UI), mstreaming, router, routerconsole (केवल news), streaming। ये subsystems Android और embedded applications द्वारा उपयोग किए जाते हैं जिन्हें केवल Java 6 की आवश्यकता होती है। सभी classes Android API 14 में उपलब्ध होनी चाहिए। इन subsystems में Java 7 language features स्वीकार्य हैं यदि Android SDK के वर्तमान संस्करण द्वारा समर्थित हैं और वे Java 6‑compatible code में compile होते हैं।
• Try‑with‑resources का उपयोग embedded subsystems में नहीं किया जा सकता क्योंकि इसके लिए runtime में java.lang.AutoCloseable की आवश्यकता होती है, और यह Android API 19 (KitKat 4.4) तक उपलब्ध नहीं है।
• java.nio.file package का उपयोग embedded subsystems में नहीं किया जा सकता क्योंकि यह Android API 26 (Oreo 8) तक उपलब्ध नहीं है।
• उपरोक्त सीमाओं के अलावा, Java 8 classes, methods, और constructs का उपयोग केवल निम्नलिखित subsystems में किया जा सकता है: BOB, desktopgui, i2psnark, i2ptunnel.war (UI), jetty‑i2p.jar, jsonrpc, routerconsole (news को छोड़कर), SAM, susidns, susimail, systray।
• Plugin authors plugin.config फ़ाइल के माध्यम से कोई भी minimum Java version की आवश्यकता कर सकते हैं।
• Primitive types और classes के बीच स्पष्ट रूप से convert करें; autoboxing/unboxing पर निर्भर न रहें।
• URL का उपयोग न करें। URI का उपयोग करें।
• Exception को catch न करें। RuntimeException और checked exceptions को व्यक्तिगत रूप से catch करें।
• UTF‑8 charset argument के बिना String.getBytes() का उपयोग न करें। आप DataHelper.getUTF8() या DataHelper.getASCII() का भी उपयोग कर सकते हैं।
• फ़ाइलें read या write करते समय हमेशा UTF‑8 charset निर्दिष्ट करें। DataHelper utilities सहायक हो सकती हैं।
• String.toLowerCase() या String.toUpperCase() का उपयोग करते समय हमेशा locale (उदाहरण के लिए Locale.US) निर्दिष्ट करें। String.equalsIgnoreCase() का उपयोग न करें, क्योंकि locale निर्दिष्ट नहीं किया जा सकता।
• String.split() का उपयोग न करें। DataHelper.split() का उपयोग करें।
• तारीखों और समय को format करने के लिए code न जोड़ें। DataHelper.formatDate() और DataHelper.formatTime() का उपयोग करें।
• सुनिश्चित करें कि InputStreams और OutputStreams को finally blocks में बंद किया गया है।
• सभी for और while blocks के लिए {} का उपयोग करें, भले ही केवल एक line हो। यदि आप if, else, या if-else block में से किसी के लिए {} का उपयोग करते हैं, तो सभी blocks के लिए इसका उपयोग करें। } else { को एक single line पर रखें।
• जहां भी संभव हो fields को final के रूप में निर्दिष्ट करें।
• I2PAppContext, RouterContext, Log, या router या context items के किसी अन्य references को static fields में store न करें।
• Constructors में threads start न करें। Thread के बजाय I2PAppThread का उपयोग करें।

लॉगिंग

निम्नलिखित दिशानिर्देश router, webapps और सभी plugins पर लागू होते हैं।

• जो भी संदेश डिफ़ॉल्ट लॉग स्तर (WARN, INFO, और DEBUG) पर प्रदर्शित नहीं होते हैं, उनके लिए, जब तक कि संदेश एक स्थिर स्ट्रिंग न हो (बिना concatenation के), हमेशा लॉग कॉल से पहले log.shouldWarn(), log.shouldInfo(), या log.shouldDebug() का उपयोग करें ताकि अनावश्यक ऑब्जेक्ट churn से बचा जा सके।
• लॉग संदेश जो डिफ़ॉल्ट लॉग स्तर (ERROR, CRIT, और logAlways()) पर प्रदर्शित हो सकते हैं, वे संक्षिप्त, स्पष्ट और एक गैर-तकनीकी उपयोगकर्ता के लिए समझने योग्य होने चाहिए। इसमें exception कारण टेक्स्ट भी शामिल है जो प्रदर्शित हो सकता है। यदि त्रुटि होने की संभावना है (उदाहरण के लिए, फ़ॉर्म सबमिशन त्रुटियों पर) तो अनुवाद पर विचार करें। अन्यथा, अनुवाद आवश्यक नहीं है, लेकिन कहीं और पहले से अनुवाद के लिए टैग की गई स्ट्रिंग को खोजना और पुन: उपयोग करना सहायक हो सकता है।
• लॉग संदेश जो डिफ़ॉल्ट लॉग स्तर (WARN, INFO, और DEBUG) पर प्रदर्शित नहीं होते हैं, वे डेवलपर उपयोग के लिए अभिप्रेत हैं, और उनमें उपरोक्त आवश्यकताएं नहीं हैं। हालांकि, WARN संदेश Android लॉग टैब में उपलब्ध हैं, और समस्याओं को डिबग करने वाले उपयोगकर्ताओं के लिए सहायक हो सकते हैं, इसलिए WARN संदेशों के साथ भी कुछ सावधानी बरतें।
• INFO और DEBUG लॉग संदेशों का उपयोग संयम से किया जाना चाहिए, विशेष रूप से hot code paths में। विकास के दौरान उपयोगी होने के बावजूद, परीक्षण पूर्ण होने के बाद उन्हें हटाने या comment out करने पर विचार करें।
• stdout या stderr (wrapper log) पर लॉग न करें।

लाइसेंस

• केवल वह कोड चेक इन करें जो आपने स्वयं लिखा है। अन्य स्रोतों से किसी भी कोड या लाइब्रेरी JARs को चेक इन करने से पहले, यह औचित्य सिद्ध करें कि यह क्यों आवश्यक है, लाइसेंस की संगतता को सत्यापित करें, और रिलीज़ मैनेजर से अनुमोदन प्राप्त करें।
• यदि आप बाहरी कोड या JARs जोड़ने के लिए अनुमोदन प्राप्त करते हैं, और बाइनरीज़ किसी भी Debian या Ubuntu पैकेज में उपलब्ध हैं, तो आपको बाहरी पैकेज का उपयोग करने के लिए बिल्ड और पैकेजिंग विकल्प लागू करने होंगे। संशोधित करने के लिए फ़ाइलों की चेकलिस्ट: build.properties, build.xml, debian/control, debian/i2p-router.install, debian/i2p-router.links, debian/rules, sub-build.xml।
• बाहरी स्रोतों से चेक इन की गई किसी भी इमेज के लिए, लाइसेंस की संगतता को पहले सत्यापित करना आपकी जिम्मेदारी है। चेक-इन टिप्पणी में लाइसेंस और स्रोत जानकारी शामिल करें।

बग्स

• समस्याओं का प्रबंधन सभी की जिम्मेदारी है; कृपया मदद करें। GitLab पर उन समस्याओं की निगरानी करें जिनमें आप मदद कर सकते हैं। यदि संभव हो तो समस्याओं पर टिप्पणी करें, उन्हें ठीक करें और बंद करें।
• नए डेवलपर्स को समस्याओं को ठीक करने से शुरुआत करनी चाहिए। जब आपके पास कोई समाधान हो, तो अपना patch समस्या से संलग्न करें और review-needed keyword जोड़ें। समस्या को तब तक बंद न करें जब तक इसकी सफलतापूर्वक समीक्षा न हो जाए और आप अपने परिवर्तनों की जांच न कर लें। एक बार जब आप कुछ tickets के लिए यह सुचारू रूप से कर लें, तो आप ऊपर दी गई सामान्य प्रक्रिया का पालन कर सकते हैं।
• जब आपको लगे कि आपने समस्या को ठीक कर दिया है तो उसे बंद कर दें। हमारे पास tickets को सत्यापित और बंद करने के लिए कोई परीक्षण विभाग नहीं है। यदि आप सुनिश्चित नहीं हैं कि आपने इसे ठीक किया है, तो इसे बंद कर दें और एक नोट जोड़ें जिसमें लिखा हो “मुझे लगता है कि मैंने इसे ठीक कर दिया है, कृपया परीक्षण करें और यदि यह अभी भी खराब है तो फिर से खोलें”। dev build नंबर या revision के साथ एक टिप्पणी जोड़ें और milestone को अगली रिलीज़ पर सेट करें।