La dernière mise à jour de cette page été effectuée en Janvier 2017.

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, plug-ins et applications externes peuvent être considérablement différentes, vérifiez avec le développeur approprié pour des conseils.

Communauté

  • Veuillez ne pas « juste écrire du code ». Si vous le pouvez, participez aux activités de développement, incluant : discussions de développement et assistance sur IRC, zzz.i2p, forum.i2p ; faire des tests ; signaler des bogues et répondre aux rapports de bogues ; documentation ; revues de code ; 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

Notre cycle de sortie normal est 6-10 semaines. Ce qui suit sont les délais approximatifs dans un cycle typique de 8 semaines. Les délais réels pour chaque sortie sont définis par le développeur principal.

  • 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 fonctionnalités. Délai limite pour les nouvelles fonctionnalités majeures.
  • 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.
  • 7-10 jours avant la sortie : gel des chaînes de texte. Il n’y a plus de modification des chaînes de texte ("étiquettées") à traduire. Les chaînes de texte sont poussées vers Transifex, l’annonce de la date limite de traduction est annoncée sur Transifex.
  • 7 à 10 jours avant la parution : date limite pour les fonctions. Passé cette date, il n’y aura que des correctifs de bogues, plus de nouvelles fonctions, de réusinage ou de nettoyage.
  • 3-4 jours avant la sortie : délai limite de traduction. Tirez les traductions depuis Transifex puis enregistrez les.
  • 2-3 jours avant la sortie : délai limite des vérifications. Aucune vérification après cette date sans la permission du constructeur de sortie.
  • Heures qui précèdent la sortie : délai limite d’examen du code.

Monotone

  • Avoir une compréhension de base des systèmes distribués de contrôle de source, même si vous n’avez pas utilisé Monotone auparavant. Demandez de l’aide si vous en avez besoin. Une fois poussé, les checkins sont pour toujours, il n’y a pas d’annulation. Veuillez être prudent. Si vous n’avez pas utilisé Monotone auparavant, commencez pas à pas. Vérifiez quelques petits changements et voyez comment cela marche.
  • Testez vos changements avant de les envoyer. Si vous préférez le modèle de développement envoyer-avant-de-tester, utilisez votre propre branche de développement (par exemple i2p.i2p.yourname.test) et une fois que cela marche bien propagez en retour vers i2p.i2p. Ne cassez pas la build. Ne causez pas de régressions. Dans le cas où vous le feriez (cela arrive), veuillez ne pas disparaitre pendant une longue période après avoir poussé vos changements.
  • 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.
  • Assurez que vous avez le dernier fichier monotonerc dans _MTN. N’envoyez pas par dessus des révisions non éprouvées.
  • Veillez à 'mtn pull' et 'mtn update' à la dernière version avant d’envoyer et de pousser. Si par erreur c’est différent, fusionnez et poussez dès que possible. Ne faites pas régulièrement d’autres fusions pour vous. Oui, nous savons que Monotone dit de pousser puis de fusionner, mais dans l’espace de travail fusionner fonctionne aussi bien que dans une fusion en database, sans créer de révision de fusion.
  • N’envoyez pas de changements majeurs dans la branche principale i2p.i2p tardivement dans le cycle de sortie. Si un projet va vous prendre davantage que quelques jours, créez votre propre branche dans Monotone et faites le développement là afin de ne pas bloquer les sorties.

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 plug-ins 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).
  • Étiquetez des chaînes pour traduction quand c’est nécessaire. Ne changez pas de chaînes étiquetées existantes à moins que ce soit vraiment nécessaire, car cela cassera les traductions existantes. N’ajoutez pas ni ne changez les chaînes étiquetées après le "gel d’étiquette" dans le cycle de sortie afin que les traducteurs aient une chance de mettre à jour avant la sortie.
  • Utilisez de classes génériques et concourantes lorsque c’est possible. I2P est une application fortement multi-threaded.
  • Etre habitué des pièges Java communs qui sont attrapés par findbugs. Exécutez 'ant findbugs' pour apprendre davantage.
  • Nous exigeons Java 7 pour construire et exécuter I2P. N’utilisez pas les classes Java 8, ni les méthodes à aucun endroit. N’utilisez pas les classes Java 7 ou 8 ou les méthodes dans les sous-systèmes 'embedded' (core, routeer, mstreaming, streaming, i2ptunnel), car Android et les applications 'embedded' requièrent Java 6. Toutes les classes doivent être disponibles dans Android API 9. Les possibilités du langage Java 7 sont acceptées dans ces sous-systèmes si supportées par la version actuelle du SDK Android et sont compilables en code compatible Java 6.
  • 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().
  • Spécifiez toujours un jeu de caractères UTF-8 lors de la lecture ou de l’écriture de fichiers. Les utilitaires DataHelper peuvent être utiles.
  • Toujours spécifier un local (e.g. Locale.US) avec String.toLowerCase() ou String.toUpperCase(). N’utilisez pas String.equalsIgnoreCase() car on ne peut pas spécifier de local.
  • N’utilisez pas String.split(). Utilisez DataHelper.split().
  • 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 stockez pas dans des champs statiques : I2PAppContext, RouterContext, Log, ni d’autres références au routeur ou aux articles de contexte.
  • Ne commencez pas de fils (threads) dans des constructeurs (contructors). Utilisez I2PAppThread au lieu de fil.

Licences

  • Vérifiez seulement le code que vous avez écrit vous-même. Avant de vérifier n’importe quel code ou bibliothèque issu d’autres sources, justifiez pourquoi c’est nécessaire, vérifiez que la licence est compatible, et obtenez l’approbation du développeur principal.
  • 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

  • Gérer les tickets Trac est le travail de tout le monde, veuillez aider. Surveillez dans trac.i2p2.de les tickets auxquels vous avez été assigné ou auxquels pouvez aider. Assignez, catégorisez, commentez, réparez, ou fermez des tickets si vous le pouvez.
  • Les nouveaux développeurs devraient commencer en corrigeant un bogue. Recherche des bogues dans trac avec le mot-clé 'easy'. Quand vous avez une correction, attachez votre patch au ticket et ajoutez le mot-clé 'review-needed'. Ne fermez pas le ticket avant qu’il n’ait été passé en revue et que vous avez enregistré vos changements avec succès. Une fois que vous ceci avez fait sans à-coups pour deux ou trois tickets, vous pouvez suivre la procédure normale ci-dessous.
  • Fermez un ticket quand vous pensez que vous l’avez réparé. Nous n’avons pas de département de test pour vérifier et fermer des tickets. Si vous n’êtes pas sûr vous l’avez réparé, fermez le et ajouter une note disant "Je pense que je l’ai réparé, veuillez tester et réouvrir si c’est toujours cassé". Ajoutez un commentaire avec le numéro de build dev ou la révision et mettez le jalon à la prochaine sortie.