Această pagină a fost actualizată ultima dată în 2022-01 .

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

  • Please don't just "write code". If you can, participate in other development activities, including: development discussions and support on IRC, i2pforum.i2p; testing; bug reporting and responses; documentation; code reviews; 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

The normal release cycle is 6-12 weeks. Following are the approximate deadlines within a typical 8-week cycle. Actual deadlines for each release are set by the release manager after consultation with the full team.

  • 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ă.
  • 10-14 days before release: String freeze. No more changes to translated ("tagged") strings. Push strings to Transifex, announce translation deadline on Transifex.
  • 10-14 days before release: Feature deadline. Bug fixes only after this time. No more features, refactoring or cleanup.
  • 3-4 days before release: Translation deadline. Pull translations from Transifex and check in.
  • 3-4 days before release: Checkin deadline. No checkins after this time without the permission of the release builder.
  • Ore înainte de eliberare: termenul limită pentru revizuirea codului.

Git

  • Have a basic understanding of distributed source control systems, even if you haven't used git before. Ask for help if you need it. Once pushed, checkins are forever, there is no undo. Please be careful. If you have not used git before, start with baby steps. Check in some small changes and see how it goes.
  • Test your changes before checking them in. If you prefer the checkin-before-test development model, use your own development branch and propagate back to i2p.i2p once it is working well. Do not break the build. Do not cause regressions. In case you do (it happens), please do not vanish for a long period after you push your change.
  • 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.
  • Ensure that you 'git pull' to the latest revision before you check in and push. If you inadvertently diverge, merge and push as soon as possible. Don't routinely make others merge for you.
  • Do not check in major changes into the main i2p.i2p branch late in the release cycle. If a project will take you more than a couple days, create your own branch in git and do the development there so you do not block releases.

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).
  • Tag strings for translation where appropriate, which is true for all UI strings. Don't change existing tagged strings unless really necessary, as it will break existing translations. Do not add or change tagged strings after the "tag freeze" in the release cycle so that translators have a chance to update before the release.
  • 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.
  • Java 8 is required to build and run I2P as of release 0.9.47. Do not use Java 7 or 8 classes or methods in embedded subsystems: addressbook, core, i2ptunnel.jar (non-UI), mstreaming, router, routerconsole (news only), streaming. These subsystems are used by Android and embedded applications that require only Java 6. All classes must be available in Android API 14. Java 7 language features are acceptable in these subsystems if supported by the current version of the Android SDK and they compile to Java 6-compatible code.
  • 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).
  • Other than the above limitations, Java 8 classes, methods, and constructs may be used in the following subsystems only: BOB, desktopgui, i2psnark, i2ptunnel.war (UI), jetty-i2p.jar, jsonrpc, routerconsole (except news), SAM, susidns, susimail, systray.
  • 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.

Logging

The following guidelines apply to the router, webapps, and all plugins.
  • For any messages not displayed at the default log level (WARN, INFO, and DEBUG), unless the message is a static string (no concatenation), always use log.shouldWarn(), log.shouldInfo(), or log.shouldDebug() before the log call to avoid unnecessary Object churn.
  • Log messages that may be displayed at the default log level (ERROR, CRIT, and logAlways()) should be brief, clear, and understandable to a non-technical user. This includes exception reason text that may also be displayed. Consider translating if the error is likely to happen (for example, on form submission errors). Otherwise, translation is not necessary, but it may be helpful to search for and reuse a string that is already tagged for translation elsewhere.
  • Log messages not displayed at the default log level (WARN, INFO, and DEBUG) are intended for developer use, and do not have the above requirements. However, WARN messages are available in the Android log tab, and may be of assistance to users debugging issues, so use some care with WARN messages as well.
  • INFO and DEBUG log messages should be used sparingly, especially in hot code paths. While useful during development, consider removing them or commenting them out after testing is complete.
  • Do not log to stdout or stderr (wrapper log).

Licențe

  • Only check in code that you wrote yourself. Before checking in any code or library jars from other sources, justify why it is necessary, verify the license is compatible, and obtain approval from the release manager.
  • 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

  • Managing issues are everybody's job, please help. Monitor for issues you can help with. Comment on, fix, and close issues if you can.
  • New developers should start by fixing issues. When you have a fix, attach your patch to the issue and add the keyword 'review-needed'. Do not close the issue until it's been successfully reviewed and you've checked your changes in. Once you've done this smoothly for a couple of tickets, you may follow the normal procedure below.
  • Close an issue when you think you've fixed it. We don't have a test department to verify and close tickets. If you arent sure you fixed it, close it and add a note saying "I think I fixed it, please test and reopen if it's still broken". Add a comment with the dev build number or revision and set the milestone to the next release.