Il existe un certain nombre de principes de développement généraux à suivre :

• Toujours vérifier les changements avec repoman : utilisez repoman commit à la place de cvs commit.
• Si un paquet est soit cassé dans sa version actuelle, soit il suit un processus de construction/installation vraiment horrible, jetez un coup d'oeil sur ce que les autres distributions font pour ce paquet :
  • http://cvs.mandrakesoft.com/cgi-bin/cvsweb.cgi/SPECS/
  • http://www.debian.org/distrib/packages
• Votre paquet, une fois complet et démasqué, est supposé « simplement fonctionner » pour les utilisateurs finaux. Avoir à bidouiller un paquet installé pour qu'il marche devrait être optionnel. Du coup, vous devez installer le paquet en question avec une configuration par défaut raisonnable.
• N'ayez pas peur de consulter notre documentation en ligne et les ebuilds écrits et maintenus par plusieurs développeurs expérimentés. Vous pouvez aussi contacter les développeurs expérimentés directement pour poser des questions techniques ou concernant la politique générale.
• Faites attention à ce que vous soumettez. Souvenez-vous que vos soumissions peuvent potentiellement affecter des milliers d'utilisateurs. Si votre soumission entraîne des problèmes dans l'arbre de Portage, ils doivent être résolu dans un temps très court.
• Tous les paquets doivent être accompagnés d'un fichier metadata.xml qui liste entre autres à quel groupe de travail (ou/et quels mainteneurs individuels) est affecté la maintenance du paquet.

Le Copyright des ebuilds (et de la documentation) doit toujours être assigné à Gentoo Technologies. Les développeurs ne doivent jamais mettre leur propre nom dans les lignes de copyright. Pour plus d'information, lisez http://www.gentoo.org/proj/en/devrel/copyright/index.xml.

Sur certaines architectures, les bibliothèques partagées doivent être construites avec l'option -fPIC. Sur x86 et d'autres, les bibliothèques partagées se construiront sans -fPIC, mais cela impliquerait des pertes, et peut causer une perte de performance. Si vous rencontrez un paquet qui ne construit pas ses bibliothèques avec -fPIC, corrigez le Makefile pour construire uniquement ces bibliothèques avec -fPIC. Plus d'informations sur -fPIC sont disponibles sur http://www.gentoo.org/proj/en/hardened/pic-internals.xml.

Les nouveaux modules Perl doivent être ajoutés dans Portage uniquement si l'une des conditions suivantes est vérifiée :

• le module est nécessaire pour satisfaire une dépendance ;
• le module ne peut pas être récupéré avec g-cpan ;
• le module ajoute une fonctionnalité à un ebuild déjà existant ;
• le module fournit des outils, des applications ou autres fonctionnalités (c'est-à-dire plus que ce qu'offrent leurs .PM).

Merci de vous assurer qu'au moins une personne du groupe de travail sur Perl approuve votre ajout.

Le nom des fichiers ebuilds consiste en quatre sous-sections logiques :

pkg-ver{_suf{#}}{-r#}.ebuild

La première sous-section, pkg, est le nom du paquet, qui doit toujours contenir des caractères choisis parmi les minuscules, les chiffres de 0 à 9, le tiret -, le soulignement _ ou le plus +. Par exemple, on a util-linux, sysklogd et gtk+. Nous avons quelques paquets dans Portage qui ne suivent pas cette règle, mais les vôtres devront la respecter.

La seconde sous-section ver est la version du paquet qui doit normalement être la même que la version de l'archive source principale. La version est en général constituée de deux ou trois (ou plus) nombres séparés par un point, comme 1.2 ou 4.5.2, et peuvent comporter une lettre seule suivant immédiatement le dernier chiffre. Par exemple, 1.4b ou 2.6h. La version du paquet est liée au nom du paquet par un tiret. Par exemple, vous aurez foo-1.0 ou bar-2.4.6.

La troisième sous-section, {_suf{#}}, est optionnelle, et peut contenir un suffixe pré-défini parmi ceux listés (du plus vieux au plus récent) ci-dessous :

Tous ces suffixes doivent être suivis immédiatement d'un entier positif non nul, comme par exemple linux-2.4.0_pre10. En supposant des versions identiques, les suffixes sont ordonnés ainsi (le premier étant le plus vieux) : _alpha < _beta < _pre < _rc < (aucun suffixe) < _p.

En comparant deux suffixes identiques avec les entiers qui les suivent, celui qui a le numéro le plus grand sera considéré comme plus récent. Par exemple, foo-1.0_alpha4 est plus récent que foo-1.0_alpha3.

La quatrième sous-section dans le nom du paquet est le numéro de révision spécifique à Gentoo Linux ({-r#}). Cette sous-section comme le suffixe est optionnelle. # est un entier positif non nul, ce qui donne par exemple paquet-4.5.3-r3.

Le numéro de révision est indépendant de la version de l'archive source et est utilisé pour informer les utilisateurs qu'une révision provenant de Gentoo Linux, pour un paquet particulier, est disponible. Les sorties initiales d'ebuilds ne doivent pas avoir de numéro de révision. Par exemple, paquet-4.5.3 est considéré par Portage comme ayant un numéro de révision de zéro. Cela signifie que le décompte se fait ainsi : 1.0 (version initiale), 1.0-r1, 1.0-r2, etc.

Le numéro de révision d'un paquet doit être augmenté par les développeurs Gentoo quand l'ebuild a changé à un point tel que les utilisateurs peuvent vouloir faire une mise à jour. Typiquement, c'est le cas quand des correctifs sont fait sur un ebuild, qui affectent les fichiers installés résultant, mais l'ebuild utilise la même archive source, comme pour l'ebuild précédent. Si vous faites un changement interne stylistique à un ebuild qui ne change aucun fichier installé alors il n'y a pas besoin de remonter le numéro de révision. D'ailleurs, si vous corrigez un problème de compilation sur un ebuild qui affecte des utilisateurs, il n'y a pas besoin de remonter le numéro de version, dans la mesure où ceux pour qui cela fonctionnait parfaitement ne verront aucune différence en installant la nouvelle révision, et ceux qui avaient un problème n'ont pas pu installer leur paquet (dans la mesure où la compilation avait échoué), et donc n'ont pas besoin d'avoir un nouveau numéro de révision pour les forcer à mettre à jour. Un remontage de révision n'est également pas nécessaire si une minorité d'utilisateurs sera affectée et que le paquet prend un temps de compilation conséquent : Faites appel à votre bon sens pour juger de la circonstance.

Les ebuilds devraient se calquer sur la version précédente pour s'assurer que des correctifs ne sont pas supprimés accidentellement. Les correctifs doivent inclure des commentaires appropriés dans l'ebuild pour expliquer ce qu'ils font et pourquoi ils sont nécessaires. Si vous n'êtes pas très familier avec les correctifs ou que vous n'arrivez pas à déterminer si ils sont toujours nécessaires, vous ne devez pas mettre à jour l'ebuild.

Portage supporte un concept appelé les paquets "virtuels" (virtual packages en anglais). En les utilisant, vous permettez d'avoir un nom catégorie/paquet particulier qui pointe vers un autre.

Voici un exemple d'utilisation des paquets virtuels. Imaginons que vous créez un nouveau paquet cron appelé foocron. Gentoo Linux est préparé actuellement pour que tout ce qui nécessite l'usage d'un paquet cron dépend du paquet virtual/cron. Cela permet aux ebuilds de s'assurer qu'il y a plusieurs paquets pour cron disponibles, et l'utilisateur peut de manière arbitraire choisir l'un ou l'autre, selon ses préférences. Pour ajouter foocron-1.0.ebuild dans le système, vous devrez ajouter une ligne dans l'ebuild comme suit :

PROVIDE="virtual/cron"

Maintenant, dès que foocron-1.0 sera installé, le paquet virtual/cron sera enregistré. Si vous n'aviez aucun paquet cron installé auparavant, cela signifiera que tous les paquets dépendant de virtual/cron auront cette dépendance satisfaite de manière complète. Remarquez qu'il est possible de spécifier une valeur PROVIDE à tous les types de paquets. Il faut juste ne pas commencer par virtual. Cela dit, vous devez utiliser la catégorie virtual/, sauf dans le cas où vous utilisez la fonctionnalité proposée par PROVIDE pour pointer des paquets qui ont été renommés.

Il y a une seconde composante dans l'implémentation des paquets virtuels dans Gentoo. Qu'arrive-t-il si aucun paquet n'est installé, qui fournisse virtual/cron ? Comment Portage choisira-t-il le « bon » cron à installer pour satisfaire une dépendance à virtual/cron ? Portage s'en charge en utilisant un fichier de correspondance de profile spécifique de paquets virtuels, nommé virtuals, qui est présent dans /etc/make.profile. Si vous jetez un coup d'oeil dans le votre, vous verrez que le contenu ressemble un peu à ceci :

virtual/lpr             net-print/cups
virtual/python          dev-lang/python
virtual/mta             net-mail/ssmtp

La première ligne de ce fichier indique à Portage que si un paquet dépend de virtual/lpr et qu'aucun paquet fournissant cette dépendance n'est installé et que le paquet virtual/lpr n'est pas disponible dans l'arbre de Portage, alors net-print/cups devra être installé pour satisfaire cette dépendance. net-print/cups contient une ligne PROVIDE="virtual/lpr" pour que les prochaines dépendances sur virtual/lpr puissent être satisfaites.

Parlons désormais de la conduite à suivre pour les développeurs. Si vous devez ajouter un paquet foocron, vous devrez évidemment vous assurez que tous les programmes qui dépendent de virtual/cron peuvent fonctionner correctement avec votre paquet. Et si vous voulez ajouter un paquet foobarosité qui dépend de virtual/cron, vous devrez probablement vous assurer que tous les paquets proposant virtual/cron pourront faire fonctionner correctement votre paquet.

Avant de créer des nouveaux paquets virtuels, merci de commencer à en parler sur la liste de diffusion interne pour les développeurs. Maintenir informés les développeurs de nouveaux paquets virtuels est essentiel pour s'assurer de leur utilisation uniforme.

Il y a deux moyens de construire un ebuild basé sur des sources à partir de l'arbre de développement CVS. Le premier moyen (traditionnel) est de créer un ebuild « instantané CVS » en créant votre propre instantané archivé de l'arbre CVS récupéré, en mettant les sources en miroir avec les dépôts officiels de fichiers distribués, puis vous écrivez un ebuild qui utilise spécifiquement cette archive. Nous appellerons désormais ce type d'ebuilds « ebuilds d'instantané CVS ».

L'autre méthode pour créer un ebuild utilisant le CVS consiste à utiliser cvs.eclass pour créer un ebuild CVS « live ». Un tel ebuild récupérera de manière dynamique la dernière archive sur le dépôt CVS mise sur le CVS, assurant ainsi que les sources sont les plus à jour possible. Nous les nommerons les « ebuilds 'live' ».

Les paragraphes suivants détaillent la politique relative à l'utilisation des ebuilds basés sur CVS. Remarquez qu'elle définit des règles strictes à propos de l'ajout de ce type d'ebuilds dans l'arbre de Portage.

Les ebuilds d'instantané CVS sont largement préférés aux ebuilds « live » utilisant cvs.eclass.

Les ebuilds d'instantané CVS sont autorisés si un instantané du CVS contient les correctifs connus qui sont nécessaires au bon fonctionnement su paquet logiciel, ou si la version CVS d'un paquet logiciel particulier est connue pour, ou a été prouvée comme fonctionnant mieux que les versions de sortie normales.

Les ebuilds « live » sont généralement utilisés uniquement pour les commodités des développeurs et devraient toujours être masqués avec un mot-clef de type ~[arch]. Il est impossible de garantir le bon fonctionnement d'un ebuild « live » dans la mesure où l'arbre cvs du serveur peut changer à tout moment, ce qui explique le masquage systématique.

Que ce soit pour un ebuild « live » ou un ebuild d'instantané CVS, vous, développeur serez responsable du bon fonctionnement de l'ebuild. Il est particulièrement difficile de s'en assurer pour les ebuilds « live » pour des raisons évidentes.

Si les ebuilds (quelque soit le type) ne fonctionnent pas correctement, ils doivent être corrigés ou supprimés de l'arbre de Portage. Si ce sont des ebuilds « live », ils doivent être marqués en ~[arch] à vie. Cette exception est expliquée plus bas.

Si un ou plusieurs utilisateurs demandent un ebuild « live », vous pouvez en ajouter un pour eux. Il doit avoir des mots-clef en ~[arch] afin que les autres utilisateurs ne puissent l'installer inconsciemment.

De cette manière, les utilisateurs le nécessitant peuvent l'installer, mais les autres utilisateurs seront protégés de son installation accidentelle. Encore une fois, cela ne s'applique que dans les situations où les utilisateurs demandent de manière spécifique un ebuild « live ». Les ebuilds d'instantanés CVS ne doivent être ajoutés à l'arbre de Portage que dans l'intention de les mettre en stable ou pour proposer des fonctionnalités améliorées par rapport aux versions habituelles de sortie d'un même logiciel.

Les ebuilds soumis par les utilisateurs ne doivent jamais être considérés comme sûr, et doivent toujours être audités et testé de manière suffisante, avant de les soumettre au CVS. Si un ebuild soumis par un utilisateur a des problèmes vous en serez tenu pour responsable direct. En l'incorporant au CVS, vous affirmez que cet ebuild suit tous les standards de développement de Gentoo Linux.

Assurez-vous que l'ebuild soumis par l'utilisateur ne contient pas d'en-tête personnalisées comme celle-ci :

# Ebuild updated by: me <me@me.com>

Ces informations doivent être ajoutées au ChangeLog en utilisant la syntaxe correcte des commentaires de ChangeLog. Toujours s'assurer que le ChangeLog attribue les crédits à l'utilisateur qui a proposé l'ebuild. Ces informations doivent apparaître dans la première entrée du ChangeLog.

Assurez-vous également que tous les nouveaux ebuilds que vous soumettez au CVS contiennent la ligne suivante :

# $Header: $

Un certain nombre d'ebuilds soumis par les utilisateurs sont basés sur des fichiers utilisant rsync, qui peuvent contenir des lignes d'en-tête incorrectes.

Encouragez les utilisateurs à proposer des « diffs » sur les ebuilds existants s'ils proposent une mise à jour. En faisant cela, nous pouvons aider à éviter d'avoir à réintroduire des correctifs de bogues déjà identifiés et corrigés auparavant dans les nouveaux ebuilds. Si vous ne travaillez pas à partir d'un diff soumis par un utilisateur, alors utilisez la commande diff pour voir les changements, en gardant un oeil sur tout ce qui devrait apparaître dans le nouveau ebuild et qui était présent dans l'actuel, ou sur tout ce qui dans le nouvel ebuild devrait être corrigé ou supprimé.

En général, laissez l'utilisateur faire ce travail pour qu'il obtienne de lui-même un ebuild correct, sauf si vous voulez nettoyer l'ebuild sans le consulter. Même alors, il est toujours meilleur de laisser l'utilisateur faire ce travail, pour qu'il puisse apprendre de ses erreurs et soumettre des ebuilds plus propres dans le futur. N'oubliez pas de toujours remercier pour toute soumission, même si elle n'est pas vraiment bonne. Soyez polis mais honnête. Si un ebuild n'est pas utilisable, on peut dire à l'utilisateur d'une manière non insultante que leur ebuild ne convient pas, sans porter atteinte à leur capacité actuelle à écrire un ebuild. Souvenez-vous que les utilisateurs qui proposent des ebuilds cassés peuvent être dans le futur des membres productifs et expérimentés pour notre projet dans le futur, c'est à dire s'ils reçoivent suffisamment d'encouragement et de support et continuent à améliorer leurs capacités.

Seul le mainteneur de Portage peut proposer des sorties de Portage à destination des utilisateurs, que ce soient les versions masquées ou non. Personne d'autre n'est autorisé à sortie de nouvelle version de Portage.

La seule exception à cette règle est pour les situations dans lesquelles le mainteneur de Portage est indisponible pour des durées suffisamment longues et qu'il y a un bogue majeur dans Portage. Dans cette situation d'urgence, la tâche sera allouée à un développeur expérimenté, qui devra alors tester le correctif puis proposer la nouvelle sortie.

Avant d'utiliser cette « clause d'échappatoire », demandez-vous : est-ce que le mainteneur de Portage est vraiment indisponible ? Est-ce que le correctif est vraiment tellement important qu'il doit être mis sur l'arbre de Portage sur l'heure ? Avez-vous testé tout ce qui concerne votre nouveau code pour vous assurer qu'il fonctionne bien ? C'est très important ;! Souvenez-vous que si votre version de Portage est cassée, cela créera des problèmes majeurs pour tous les utilisateurs surtout si elle est non masquée. Merci de n'utiliser cette porte de sortie que en cas d'absolue nécessité c'est-à-dire quand les conséquences de ne pas l'utiliser sont trop lourdes.

Et si vous le faites, le correctif d'urgence doit être le produit d'un effort coordonné entre tous les développeurs disponibles sur le moment et en ligne (pour tester la nouvelle version, etc.) et ne doit pas être une soumission d'un « homme solitaire ». Un message doit être envoyé sur la liste de diffusion gentoo-core à propos de la nouvelle version d'urgence pour que tout le monde soit vite au courant et pour expliquer pourquoi il était nécessaire, et pourquoi attendre le mainteneur de Portage n'était pas une bonne option.

Le mainteneur de Portage permet effectivement à certaines personnes de soumettre dans l'arbre cvs de développement de Portage. Cependant, même si vous faites partie de ces personnes, ce privilège ne vous donne pas le droit de libérer des nouvelles versions de Portage. C'est le travail du mainteneur de Portage. Cette personne vérifiera et testera en profondeur vos changements avant de proposer une nouvelle version de Portage. Merci de laisser ce travail au mainteneur de Portage seul. Ne dérogez pas à cette règle. Nous espérons que cette politique, claire, aidera a éviter les futurs problèmes avec Portage.

/usr/portage/profiles/package.mask contient une liste des paquets qui ne doivent pas être installés par les utilisateurs, et des commentaires détaillant la raison du masquage. Package.mask est utilisé pour empêcher d'installer des paquets qui sont cassés, qui cassent d'autres éléments, ou qui ont mal été testés avant d'avoir un mot-clef en ~ARCH dans l'arbre. Quand vous ajoutez un ebuild ) package.mask, toujours soumettre package.mask avant de soumettre l'ebuild masqué. Cela empêche l'ebuild d'être récupéré par des utilisateurs avant que la mise à jour de package.mask ait été faite.

Une attention particulière doit être apportée quand un paquet est enlevé de package.mask. Gardez à l'esprit que si un ebuild est dans package.mask, c'est pour une bonne raison. Si vous n'avez pas masqué vous-même l'ebuild, toujours contacter le développeur cité dans les commentaires de package.mask avant de prendre une initiative. De plus, si le paquet masqué est un paquet core, une dépendance d'un paquet core, ou si démasquer le paquet peut avoir des effets secondaires, le changement doit être fait après discussion interne sur la liste de diffusion des développeurs.

L'objectif de ~arch est de permettre de tester des nouveaux paquets ajoutés dans Portage.

Il y a une différence entre utiliser package.mask et ~arch pour les ebuilds. L'utilisation de ~arch dénote que l'ebuild a besoin d'être testé. L'utilisation de package.mask dénote que l'application ou la bibliothèque est clairement instable. Par exemple si gimp-1.2.0 est une version stable des développeurs de Gimp, et qu'un nouveau correctif est disponible en tant que 1.2.1, alors le développeur doit marquer l'ebuild comme ~arch pour qu'il soit testé dans Portage parce que la version est considérée comme table par Gimp. Un autre exemple, si Gimp décide de proposer une série de versions de développement/instable, marqué 1.3.0, alors les ebuilds résultant doivent être mis dans package.mask car le logiciel lui-même est qualifié de logiciel en développement, et qu'il n'est pas recommandé par les développeurs à la distribution.

Tous les nouveaux paquets qui entrent dans Portage doivent être marqués d'un ~arch pour les architectures sur lesquelles cette version est connue comme fonctionnant. Le développeur qui soumet l'ebuild doit vérifier qu'il est en état de fonctionnement et que la variable KEYWORDS est correcte.

Quand une version de paquet a été testé pendant une période de temps suffisante et considérée comme stable, et quand le mainteneur Gentoo de ce paquet est sûr que la mise à jour n'entraînera pas de problèmes sur une machine d'utilisateur normal, alors cette version peut passer de ~ARCH à ARCH. Une indication pour savoir si un paquet est stable peut être de constater qu'aucun rapport de bogue sur un mois après l'introduction du nouveau paquet n'a été effectué pour cette version.

C'est au mainteneur du paquet de décider quelles versions sont stables ou si les versions de développement doivent être mises dans package.mask ou laissés en ~arch.

Vous devez également vous assurer que toutes les dépendances pour cette version de paquet sont également en ARCH.

La politique de Gentoo Linux requiert que tous les ebuilds contiennent les variables KEYWORDS, LICENSE, et SLOT. HOMEPAGE, SRC_URI et DESCRIPTION doivent être ajoutés sauf dans certains cas très spéciaux. DEPEND (et si besoin est, RDEPEND) doivent être inclus si votre paquet a respectivement des dépendances de compilation ou de lancement.

Utilisez DEPEND pour définir les dépendances nécessaires à la compilation d'un paquet particulier, et RDEPEND pour les dépendances nécessaires au lancement d'un paquet particulier. Vous n'avez besoin de spécifier explicitement RDEPEND que si les dépendances de lancement de l'ebuild sont différentes de celles spécifiées dans DEPEND ; Si RDEPEND n'est pas spécifié, la valeur par défaut sera celle de DEPEND. Ne jamais initialiser RDEPEND à DEPEND par vous-même dans un ebuild.

# Acceptable :
RDEPEND="${DEPEND}
         net-ftp/curl
         virtual/glibc"
# Non acceptable :
RDEPEND="${DEPEND}"

Il est également important de remarquer que seules les dépendances de RDEPEND sont satisfaites quand on installe un paquet binaire .tbz2 ; Utilisez ces informations pour vous aider à choisir les bonnes dépendances RDEPEND. Sinon, RDEPEND aura les dépendances de DEPEND.

Un paquet doit dépendre de la plus ancienne version qui satisfait la dépendance. Si le paquet fonctionne avec libfoo-1.2.x, ne le faites pas dépendre de libfoo-2.x juste parce que c'est la version que vous avez d'installée.

En général, les paquets doivent dépendre de =libfoo-1.2* à la place de >=libfoo-1.2. Sinon, votre paquet va commencer à créer des problèmes quand le paquet libfoo-2.0 sera disponible.

Dépendre d'un paquet virtuel comme virtual/foo ne fonctionne que si les différents paquets proposant de valider la dépendance virtual/foo ont des interfaces identiques. Considérons par exemple virtual/jdk-1.3. Certains paquets ne fonctionnent pas avec ibm-jdk-1.3 alors qu'ils fonctionneront bien avec sun-jdk-1.3. Pour cette raison, assurez-vous que votre paquet a été testé avec tous les paquets ayant une correspondance virtuelle avant de le démasquer. Il est peut arriver que la dépendance soit correcte seulement pour un certain nombre d'entre eux, mais qu'elle ne soit pas correcte pour le paquet virtuel lui-même.