Această pagină a fost actualizată ultima dată în 2019-11 .

Citiți mai întâi ghid pentru dezvoltatori noi.

Orientări de bază și stil de codare

Cele mai multe dintre următoarele ar trebui să fie de bun simț pentru oricine a lucrat la open source sau într-o reclamă programarea invriziunii. Următoarea se aplică în special ramurii de dezvoltare principală i2p.i2p. Liniile directoare pentru alte sucursale, pluginuri și aplicații externe pot fi substanțial diferite; consultați dezvoltatorul corespunzător pentru îndrumare.

Community

  • Vă rugăm să nu doar „scrieți codul”. Dacă puteți, participați la alte activități de dezvoltare, inclusiv: discuții de dezvoltare și suport pentru IRC, zzz.i2p și forum.i2p; testare; raportarea erorilor și răspunsuri; documentație; recenzii de coduri; etc.
  • Dev-urile active ar trebui să fie disponibile periodic pe IRC #i2p-dev. Fiți conștienți de ciclul de lansare curent. Aderați la lansarea reperelor, cum ar fi înghețarea caracteristicilor, înghețarea etichetelor și termenul limită pentru checkin pentru o eliberare.

Ciclul de eliberare

Ciclul nostru normal de eliberare este de 6-10 săptămâni. Următoarele sunt termene aproximative într-un ciclu tipic de 8 săptămâni. Termenele reale pentru fiecare versiune sunt stabilite de dezvoltatorul principal.

  • La 1-2 zile de la lansarea anterioară: sunt permise verificările în portbagaj.
  • La 2-3 săptămâni de la lansarea anterioară: Termenul limită de propagare a modificărilor majore de la alte ramuri la trunchi.
  • Cu 4-5 săptămâni înainte de lansare: Termenul limită pentru a solicita noi link-uri la pagina principală
  • Cu 3-4 săptămâni înainte de eliberare: înghețarea caracteristicilor. Data limită pentru noile funcții majore.
  • Cu 2-3 săptămâni înainte de lansare: Țineți ședința proiectului pentru a revizui cererile de link-uri de pe pagina principală, dacă există.
  • Cu 7-10 zile înainte de eliberare: înghețarea șirurilor. Nu mai există modificări la șirurile traduse („etichetate”). Apăsați șiruri către Transifex, anunțați termenul limită de traducere pe Transifex.
  • Cu 7-10 zile înainte de lansare: termenul limită. Bug-ul se rezolvă abia după acest timp. Nu mai există funcții, refactorizare sau curățare.
  • Cu 3-4 zile înainte de lansare: termenul de traducere. Trageți traducerile de la Transifex și faceți check-in.
  • Cu 2-3 zile înainte de eliberare: termenul limită pentru checkin. Nu există verificări după această dată fără permisiunea constructorului de versiuni.
  • Ore înainte de eliberare: termenul limită pentru revizuirea codului.

Monotone

  • Înțelegeți de bază sistemele de control distribuit ale surselor, chiar dacă nu ați făcut-o a folosit monoton înainte. Cereți ajutor dacă aveți nevoie. Odată împinsă, check-urile sunt pentru totdeauna, nu există nul. Vă rugăm să fiți atent. Dacă nu ai mai folosit monoton, începeți cu pașii pentru copii. Verificați câteva mici modificări și vedeți cum merge.
  • Testați-vă modificările înainte de a le verifica. Dacă preferi modelul de dezvoltare înainte de testare, folosiți-vă propria ramură de dezvoltare (de exemplu, i2p.i2p.yourname.test) și propagă înapoi la i2p.i2p odată ce funcționează bine. Nu rupeți construcția. Nu provoca regresii. În cazul în care o faceți (se întâmplă), vă rugăm să nu dispăreați pentru o perioadă lungă după îți împingi schimbarea.
  • Dacă modificarea dvs. nu este banală sau doriți ca oamenii să o testeze și au nevoie de rapoarte de testare bune pentru a ști dacă modificarea dvs. a fost testată sau nu, adăugați un comentariu de checkin la history.txt și creșteți revizia de construire în RouterVersion.java.
  • Asigurați-vă că aveți cel mai recent fișier monotonerc în _MTN. Nu faceți check-in-ul deasupra reviziilor de încredere.
  • Asigurați-vă că „mtn pull” și „mtn update” la cea mai recentă revizuire înainte de a vă înregistra și de a împinge. Dacă eșuează din greșeală, fuzionează și împinge cât mai curând posibil. Nu-i face pe alții să se alăture pentru tine. Da, știm că monotonul spune că ar trebui să împingeți apoi să fuzionați, dar, din experiența noastră, fuziunea în spațiul de lucru funcționează la fel ca și îmbinarea în baza de date, fără a crea o revizuire de îmbinare.
  • Nu verificați modificările majore ale ramurii principale i2p.i2p târziu în ciclul de lansare. Dacă un proiect vă va lua mai mult de câteva zile, creați-vă propria ramură în monoton și faceți dezvoltarea acolo pentru a nu bloca lansările.

Stil de codare

  • Stilul de codare în cea mai mare parte a codului este de 4 spații pentru indentare. Nu folosiți file. Nu reformatați codul. Dacă IDE-ul sau editorul dvs. dorește să reformateze totul, obțineți controlul asupra acestuia. Da, știm că 4 spații reprezintă o durere, dar poate că puteți configura editorul în mod corespunzător. În unele locuri, stilul de codare este diferit. Foloseste bunul simt. Emulați stilul din fișierul pe care îl modificați.
  • Toate clasele și metodele noi publice și de pachete private necesită Javadocs. Adăugați numărul de versiune @since. Javadocs pentru noi metode private sunt de dorit.
  • Pentru niciun Javadocs adăugat, nu trebuie să existe erori sau avertismente de documentare. Rulați „ant javadoc” cu Oracle Java 8 sau o versiune superioară pentru a verifica. Toate paramele trebuie să aibă linii @param, toate metodele care nu sunt nule trebuie să aibă linii @return, toate excepțiile declarate aruncate trebuie să aibă linii @throws și fără erori HTML.
  • Clasele în core / (i2p.jar) și porțiuni de i2ptunnel fac parte din API-ul nostru oficial. Există mai multe pluginuri din afara arborilor și alte aplicații care se bazează pe această API. Aveți grijă să nu faceți modificări care să încalce compatibilitatea. Nu adăugați metode la API decât dacă sunt de utilitate generală. Javadocs-urile pentru metodele API trebuie să fie clare și complete. Dacă adăugați sau modificați API-ul, actualizați și documentația de pe site-ul web (sucursala i2p.www).
  • Dacă este cazul, introduceți șiruri pentru traducere. Nu schimbați șirurile cu etichete existente decât dacă este cu adevărat necesar, deoarece acestea vor rupe traducerile existente. Nu adăugați și nu modificați șirurile etichetate după „înghețarea etichetelor” din ciclul de lansare, astfel încât traducătorii au șansa să se actualizeze înainte de lansare.
  • Utilizați generice și clase simultane când este posibil. I2P este o aplicație extrem de multi-thread.
  • Familiarizați-vă cu capcanele Java obișnuite care sunt surprinse de găsitori. Rulați „ant findbugs” pentru a afla mai multe.
  • Avem nevoie de Java 7 pentru a construi și rula I2P. Nu utilizați clase sau metode Java 8 nicăieri. Nu utilizați clase sau metode Java 7 sau 8 în subsisteme încorporate (core, router, mstreaming, streaming, i2ptunnel), deoarece aplicațiile Android și încorporate necesită doar Java 6. Toate clasele trebuie să fie disponibile în API-ul Android 14. Caracteristicile limbajului Java 7 sunt acceptabile în aceste subsisteme dacă sunt acceptate de versiunea curentă din SDK Android și se compilează la codul compatibil Java 6.
  • Try-with-resources cannot be used in embedded subsystems as it requires java.lang.AutoCloseable in the runtime, and this is not available until Android API 19 (KitKat 4.4).
  • The java.nio.file package cannot be used in embedded subsystems as it is not available until Android API 26 (Oreo 8).
  • Plugin authors may require any minimum Java version via the plugin.config file.
  • Convertiți explicit între tipuri și clase primitive; nu te baza pe autoboxing / unboxing.
  • Nu utilizați adresa URL. Utilizați URI.
  • Nu prinde excepție. Prinde RuntimeException și verifică excepțiile individual.
  • Nu utilizați String.getBytes() fără un argument de caractere UTF-8. Puteți utiliza, de asemenea, DataHelper.getUTF8() sau DataHelper.getASCII().
  • Specificați întotdeauna un set de caractere UTF-8 la citirea sau scrierea fișierelor. Utilitățile DataHelper pot fi utile.
  • Specificați întotdeauna o localizare (de exemplu Locale.US) atunci când utilizați String.toLowerCase () sau String.toUpperCase (). Nu folosiți String.equalsIgnoreCase (), deoarece nu poate fi specificată o regiune locală.
  • Nu folosiți String.split (). Utilizați DataHelper.split ().
  • Don't add code to format dates and times. Use DataHelper.formatDate() and formatTime().
  • Asigurați-vă că InputStreams și OutputStreams sunt închise în cele din urmă blocuri.
  • Utilizați {} pentru toate blocurile pentru și în timp, chiar dacă o singură linie. Dacă utilizați {} pentru blocul if, else sau if-else, folosiți-l pentru toate blocurile. Puneți „} else {” pe o singură linie.
  • Specificați câmpurile ca fiind finale, acolo unde este posibil.
  • Nu stocați I2PAppContext, RouterContext, Log sau orice alte referințe la router sau la elemente de context în câmpuri statice.
  • Nu începeți firele în constructori. Utilizați I2PAppThread în loc de Thread.

Licențe

  • Verificați numai codul pe care l-ați scris. Înainte de a verifica orice cod sau bibliotecă din alte surse justificați de ce este necesar, verificați că licența este compatibilă, și obțineți aprobarea de la dezvoltatorul principal.
  • Dacă obțineți aprobare pentru a adăuga cod extern sau jars, și binarele sunt disponibile în orice pachet Debian sau Ubuntu, trebuie să implementați opțiuni de construire și de ambalare pentru a utiliza pachetul extern. Lista de verificare a fișierelor de modificat: build.properties, build.xml, debian/control, debian/i2p-router.install, debian/i2p-router.links, debian/rules, sub-build.xml
  • Pentru orice imagine înregistrată din surse externe, este responsabilitatea dvs. să verificați mai întâi că licența este compatibilă. Includeți informațiile despre licență și sursă în comentariul de înregistrare.

Bugs

  • Gestionarea biletelor Trac este treaba tuturor, vă rugăm să ajutați. Monitorizațitrac.i2p2.de biletele la care v-ați atribuit sau vă puteți ajuta. Alocați, categorizați, comentați, reparați sau închideți bilete dacă puteți.
  • Noii dezvoltatori ar trebui să înceapă prin remedierea unei erori. Căutați buguri cu cuvântul cheie „ușor” pe trac. Când aveți o rezolvare, atașați-vă patch-ul la bilet și adăugați cuvântul cheie „review-necesare”. Nu închideți biletul până nu a fost revizuit cu succes și ați verificat modificările. După ce ați făcut acest lucru fără probleme pentru câteva bilete, puteți urma procedura normală de mai jos.
  • Închideți un bilet când credeți că l-ați rezolvat. Nu avem un departament de testare pentru verificarea și închiderea biletelor. Dacă nu sunteți sigur că l-ați rezolvat, închideți-l și adăugați o notă „Cred că l-am remediat, vă rugăm să testați și să redeschideți dacă este încă rupt”. Adăugați un comentariu cu numărul de revizuire sau revizuirea și setați reperul pentru următoarea versiune.