Veuillez lire le guide pour nouveaux développeurs d’abord.

Directives de base et style de programmation

La plupart des points suivants devraient être évident pour quelqu’un qui a travaillé sur du code source libre ou dans une environnement commercial de programmation. Les points suivants s’appliquent surtout à la branche de développement principale i2p.i2p. Les directives pour d’autres branches, greffons et applications externes peuvent être considérablement différentes, vérifiez avec le développeur approprié pour des conseils.

Communauté

• 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.
• Les dévs actif devrait être disponible périodiquement sur IRC #i2p-dev. Soyez au courant du cycle de sortie actuel. Adhérez pour relâcher - release - des jalons - milestones - tel que gel de caractéristiques, gel d’étiquette et le délai limite pour une sortie.

Cycle de sortie

The normal release cycle is 10-16 weeks, four releases a year. Following are the approximate deadlines within a typical 13-week cycle. Actual deadlines for each release are set by the release manager after consultation with the full team.

• 1 à 2 jours après la version sortie précédemment : les inclusions (checkins) vers le tronc (trunk) sont permises.
• 2–3 semaines après la version sortie précédemment  : délai limite pour propager les changements majeurs depuis d’autres branches vers le tronc.
• 4–5 semaines avant la sortie : délai limite concernant les demandes d’ajouts de liens sur la page d’accueil.
• 3 à 4 semaines avant la sortie : gel des caractéristiques. Échéance pour les nouvelles fonctions principales.
• 2 à 3 semaines avant la sortie : tenue d’une réunion de projet afin de passer en revue les requêtes de mise en page d’accueil, si il y en a.
• 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.
• Heures qui précèdent la sortie : délai limite d’examen du code.

Git

• Ayez une connaissance basique des systèmes de contrôle de source distribués, même si vous n'avez pas encore utilisé git. Demandez de l'aide si vous en avez besoin. Une fois pressé, les enregistrements sont finaux, il n'y a pas de moyen pour revenir en arrière. Veuillez faire attention. Si vous n'avez pas déjà utilisé git, commencez doucement. Vérifiez quelques petites modifications et voyez où cela vous mène.
• Test your changes before checking them in. If you prefer the checkin-before-test development model, use your own development branch in your own account, and create an MR once the work is done. 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.
• Si votre changement n’est pas insignifiant, ou que vous voulez que les gens le testent et avez besoin de bons rapports de test pour savoir si votre changement a été testé ou pas, ajoutez un commentaire de checkin dans history.txt et incrémentez la révision de build dans RouterVersion.java.
• 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, in your own account, and do the development there so you do not block releases.
• For big changes (generally speaking, more than 100 lines, or touching more than three files), check it into a new branch on your own gitlab account, create an MR, and assign a reviewer. Assign the MR to yourself. Merge the MR yourself once the reviewer approves it.
• Do not create WIP branches in the main i2p-hackers account (except for i2p.www). WIP belongs in your own account. When the work is done, create an MR. The only branches in the main account should be for true forks, like a point release.
• Do development in a transparent fashion and with the community in mind. Checkin often. Checkin or merge into the main branch as frequently as possible, given the guidelines above. If you are working on some big project in your own branch/account, let people know so they may follow along and review/test/comment.

Style de codage

• Le style de codage partout dans la plupart du code est de 4 espaces pour l’indentation. N’utilisez pas de tabulations. Ne re-formatez pas le code. Si votre IDE ou éditeur veulent tout re-formater, prenez-en le contrôle. Oui, nous savons que 4 espaces est pénible, mais peut-être que vous pouvez configurer votre éditeur convenablement. En quelques endroits, le style de codage est différent. Utilisez le bon sens. Imitez le style dans le fichier que vous modifiez.
• Toutes les nouvelles classes et méthodes publiques ou privées des paquets requièrent Javadocs. Ajoutez @since release-number. Javadocs pour les nouvelles méthodes privées est préférable.
• Pour tout Javadocs ajouté, il ne doit y avoir aucune erreur doclint ni d’avertissement. Pour le vérifier, exécuter « ant javadoc » avec Oracle Java 8 ou ultérieure. Tous les paramètres doivent avoir des lignes @param, toutes les méthodes non nulles doivent avoir des lignes @return, toutes les exceptions déclarées comme jetées doivent avoir des lignes @throws et aucune erreur HTML.
• Les classes dans core/ (i2p.jar) et les portions d’i2ptunnel font partie de notre API officielle. Il y a plusieurs greffons out-of-tree et d’autres applications qui comptent sur cette API. Soyez prudent de ne pas faire quelconque changement qui casserait cette compatibilité. N’ajoutez pas de méthodes à l’API à moins qu’elles ne soient d’utilité générale. Les Javadocs pour les méthodes d’API devraient être claires et complètes. Si vous ajoutez ou changez l’API, mettez aussi à jour la documentation sur le site Web (branche i2p.www).
• Marquez les chaînes de traduction où il y a besoin, ce qui est vrai pour toutes les chaînes d'IU. Ne changez pas des chaînes marquées existantes sauf si c'est absolument nécessaire vu que cela cassera les traductions existantes. N'ajoutez pas et ne changez pas les chaînes marquées après le "tag freeze" dans le cycle de sortie pour que les traducteurs aient une chance de le mettre à jour avant la sortie de la nouvelle version.
• Utilisez de classes génériques et concurrentes quand cela est possible. I2P est une application grandement multiple.
• Etre habitué des pièges Java communs qui sont attrapés par findbugs. Exécutez 'ant findbugs' pour apprendre davantage.
• 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.
• Convertissez explicitement entre types primitifs et classes; ne comptez pas sur l’autoboxing/unboxing.
• N’utilisez pas URL. Utilisez URI.
• N’interceptez pas Exception. Interceptez RuntimeException et vérifiez les exceptions individuellement.
• N’utilisez pas String.getBytes() sans un argument jeu de caractères UTF-8. Vous pouvez aussi utiliser DataHelper.getUTF8() ou DataHelper.getASCII().
• Indiquez toujours un jeu de caractères UTF-8 lors de la lecture ou de l’écriture de fichiers. Les utilitaires DataHelper pourraient être utiles.
• Indiquez toujours les paramètres régionaux (p. ex. Locale.FR) en utilisant String.toLowerCase() ou String.toUpperCase(). N’utilisez pas String.equalsIgnoreCase(), car les paramètres régionaux ne peuvent pas précisés.
• N’utilisez pas String.split(). Utilisez DataHelper.split().
• Don't add code to format dates and times. Use DataHelper.formatDate() and formatTime().
• Assurez-vous que InputStreams et OutputStreams sont fermés en blocs finaux (finally blocks).
• Utilisez {} pour tous les blocs for et while, même pour une seule ligne. Si vous utilisez {} soit pour un bloc if, else ou if-else, faites-le pour tous les blocs. Placez "} else {" sur une seule ligne.
• Spécifiez les champs en tant que finaux chaque fois que possible.
• Ne pas stocker dans des champs statiques I2PAppContext, RouterContext, Log ni autres références au routeur ou aux éléments contextuels.
• Ne commencez pas de fils (threads) dans des constructeurs (contructors). Utilisez I2PAppThread au lieu de fil.

Journalisation

• 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).

Licences

• 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.
• Si vous obtenez vraiment l’approbation d’ajouter du code externe ou des jars, et que les fichiers binaires sont disponibles dans n’importe quelle paquet Debian ou Ubuntu, vous devez mettre en œuvre des options de construction et d’empaquetage afin d’utiliser le paquet externe à la place. Liste de contrôle des fichiers à modifier : build.properties, build.xml, debian/control, debian/i2p-router.install, debian/i2p-router.links, debian/rules, sub-build.xml
• Pour n’importe quelles image enregistrée depuis des sources externes c’est votre responsabilité de d’abord vérifier que la licence est compatible. Incluez la licence et sourcez l’information dans le commentaire de checkin.

Bogues

• 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.