diff options
Diffstat (limited to 'doc/contributing.fr.texi')
| -rw-r--r-- | doc/contributing.fr.texi | 1007 |
1 files changed, 0 insertions, 1007 deletions
diff --git a/doc/contributing.fr.texi b/doc/contributing.fr.texi deleted file mode 100644 index ab9c17e373..0000000000 --- a/doc/contributing.fr.texi +++ /dev/null @@ -1,1007 +0,0 @@ -@node Contribuer -@chapter Contribuer - -Ce projet est un effort coopératif et nous avons besoin de votre aide pour -le faire grandir ! Contactez-nous sur @email{guix-devel@@gnu.org} et -@code{#guix} sur le réseau IRC Freenode. Nous accueillons les idées, les -rapports de bogues, les correctifs et tout ce qui pourrait aider le projet. -Nous apprécions particulièrement toute aide sur la création de paquets -(@pxref{Consignes d'empaquetage}). - -@cindex code de conduite, des contributeurs -@cindex convention de contribution -Nous souhaitons fournir un environnement chaleureux, amical et sans -harcèlement pour que tout le monde puisse contribuer au mieux de ses -capacités. Pour cela notre projet a une « Convention de contribution » -adaptée de @url{http://contributor-covenant.org/}. Vous pouvez trouver une -version locale dans le fichier @file{CODE-OF-CONDUCT} dans l'arborescence -des sources. - -Les contributeurs n'ont pas besoin d'utiliser leur nom légal dans leurs -correctifs et leurs communications en ligne ; ils peuvent utiliser n'importe -quel nom ou pseudonyme de leur choix. - -@menu -* Construire depuis Git:: Toujours le plus récent. -* Lancer Guix avant qu'il ne soit installé:: Astuces pour les hackers. -* La configuration parfaite:: Les bons outils. -* Consignes d'empaquetage:: Faire grandir la distribution. -* Style de code:: Hygiène du contributeur. -* Envoyer des correctifs:: Partager votre travail. -@end menu - -@node Construire depuis Git -@section Construire depuis Git - -Si vous souhaitez travailler sur Guix lui-même, il est recommandé d'utiliser -la dernière version du dépôt Git : - -@example -git clone https://git.savannah.gnu.org/git/guix.git -@end example - -Lors de la construction de Guix depuis un extrait, les paquets suivants sont -requis en plus de ceux mentionnés dans les instructions d'installation -(@pxref{Prérequis}). - -@itemize -@item @url{http://gnu.org/software/autoconf/, GNU Autoconf}; -@item @url{http://gnu.org/software/automake/, GNU Automake}; -@item @url{http://gnu.org/software/gettext/, GNU Gettext}; -@item @url{http://gnu.org/software/texinfo/, GNU Texinfo}; -@item @url{http://www.graphviz.org/, Graphviz}; -@item @url{http://www.gnu.org/software/help2man/, GNU Help2man (facultatif)}. -@end itemize - -La manière la plus simple de configurer un environnement de développement -pour Guix est, bien sûr, d'utiliser Guix ! La commande suivante démarre un -nouveau shell où toutes les dépendances et les variables d'environnements -appropriées sont configurés pour travailler sur Guix : - -@example -guix environment guix -@end example - -@xref{Invoquer guix environment}, pour plus d'information sur cette -commande. On peut ajouter des dépendances supplémentaires avec -@option{--ad-hoc} : - -@example -guix environment guix --ad-hoc help2man git strace -@end example - -Lancez @command{./bootstrap} pour générer l'infrastructure du système de -construction avec Autoconf et Automake. Si vous avez une erreur comme : - -@example -configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES -@end example - -@noindent -cela signifie probablement qu'Autoconf n'a pas pu trouver @file{pkg.m4} qui -est fournit par pkg-config. Assurez-vous que @file{pkg.m4} est disponible. -C'est aussi vrai pour l'ensemble de macros de @file{guile.m4} fournies par -Guile. Par exemple, si vous avez installé Automake dans @file{/usr/local}, -il ne cherchera pas les fichiers @file{.m4} dans @file{/usr/share}. Dans ce -case vous devez invoquer la commande suivante : - -@example -export ACLOCAL_PATH=/usr/share/aclocal -@end example - -@xref{Macro Search Path,,, automake, The GNU Automake Manual}, pour plus -d'information. - -Ensuite, lancez @command{./configure} comme d'habitude. Assurez-vous de -passer @code{--localstatedir=@var{directory}} où @var{directory} est la -valeur @code{localstatedir} utilisée par votre installation actuelle -(@pxref{Le dépôt} pour plus d'informations à ce propos). - -Finalement, vous devez invoquer @code{make check} pour lancer les tests -(@pxref{Lancer la suite de tests}). Si quelque chose échoue, jetez un œil -aux instructions d'installation (@pxref{Installation}) ou envoyez un message -à la liste @email{guix-devel@@gnu.org}. - - -@node Lancer Guix avant qu'il ne soit installé -@section Lancer Guix avant qu'il ne soit installé - -Pour garder un environnement de travail sain, il est utile de tester les -changement localement sans les installer pour de vrai. Pour pouvoir -distinguer votre rôle « d'utilisateur final » de celui parfois haut en -couleur de « développeur ». - -Pour cela, tous les outils en ligne de commande sont utilisables même sans -avoir lancé @code{make install}. Pour cela, vous devez d'abord avoir un -environnement avec toutes les dépendances disponibles (@pxref{Construire depuis Git}), puis préfixer chaque commande par @command{./pre-inst-env} (le script -@file{pre-inst-env} se trouve dans le répertoire de plus haut niveau de -l'arborescence des sources de Guix ; il est généré par -@command{./configure}) comme cela@footnote{L'option @option{-E} de -@command{sudo} garantie que @code{GUILE_LOAD_PATH} est bien paramétré pour -@command{guix-daemon} et pour que les outils qu'il utilise puissent trouver -les modules Guile dont ils ont besoin.} : - -@example -$ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild -$ ./pre-inst-env guix build hello -@end example - -@noindent -De même, pour une session Guile qui utilise les modules Guix : - -@example -$ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))' - -;;; ("x86_64-linux") -@end example - -@noindent -@cindex REPL -@cindex read-eval-print loop -@dots{} et pour un REPL (@pxref{Using Guile Interactively,,, guile, Guile -Reference Manual}) - -@example -$ ./pre-inst-env guile -scheme@@(guile-user)> ,use(guix) -scheme@@(guile-user)> ,use(gnu) -scheme@@(guile-user)> (define snakes - (fold-packages - (lambda (package lst) - (if (string-prefix? "python" - (package-name package)) - (cons package lst) - lst)) - '())) -scheme@@(guile-user)> (length snakes) -$1 = 361 -@end example - -Le script @command{pre-inst-env} paramètre toutes les variables -d'environnement nécessaires, dont @env{PATH} et @env{GUILE_LOAD_PATH}. - -Remarquez que @command{./pre-inst-env guix pull} ne met @emph{pas} à jour -l'arborescence des sources locale ; cela met seulement à jour le lien -symbolique de @file{~/.config/guix/current} (@pxref{Invoquer guix pull}). -Lancez @command{git pull} à la place si vous voulez mettre à jour votre -arborescence des source locale. - - -@node La configuration parfaite -@section La configuration parfaite - -La configuration parfaite pour travailler sur Guix est simplement la -configuration parfaite pour travailler en Guile (@pxref{Using Guile in -Emacs,,, guile, Guile Reference Manual}). Tout d'abord, vous avez besoin de -mieux qu'un éditeur de texte, vous avez besoin de -@url{http://www.gnu.org/software/emacs, Emacs}, amélioré par le superbe -@url{http://nongnu.org/geiser/, Geiser}. Pour paramétrer cela, lancez : - -@example -guix package -i emacs guile emacs-geiser -@end example - -Geiser permet le développement interactif et incrémental depuis Emacs : la -compilation du code et son évaluation depuis les buffers, l'accès à la -documentation en ligne (docstrings), la complétion sensible au contexte, -@kbd{M-.} pour sauter à la définition d'un objet, un REPL pour tester votre -code, et bien plus (@pxref{Introduction,,, geiser, Geiser User Manual}). -Pour travailler confortablement sur Guix, assurez-vous de modifier le chemin -de chargement de Guile pour qu'il trouve les fichiers source de votre dépôt -: - -@lisp -;; @r{Si l'extrait est dans ~/src/guix.} -(with-eval-after-load 'geiser-guile - (add-to-list 'geiser-guile-load-path "~/src/guix")) -@end lisp - -Pour effectivement éditer le code, Emacs a déjà un très bon mode Scheme. -Mais en plus de ça, vous ne devez pas rater -@url{http://www.emacswiki.org/emacs/ParEdit, Paredit}. Il fournit des -fonctionnalités pour opérer directement sur l'arbre de syntaxe, comme -relever une s-expression ou l'envelopper, absorber ou rejeter la -s-expression suivante, etc. - -@cindex extraits de code -@cindex modèles -@cindex réduire la quantité de code commun -Nous fournissons aussi des modèles pour les messages de commit git communs -et les définitions de paquets dans le répertoire @file{etc/snippets}. Ces -modèles s'utilisent avec @url{http://joaotavora.github.io/yasnippet/, -YASnippet} pour développer des chaînes courtes de déclenchement en extraits -de texte interactifs. Vous pouvez ajouter le répertoire des modèles dans la -variables @var{yas-snippet-dirs} d'Emacs. - -@lisp -;; @r{Si l'extrait est dans ~/src/guix.} -(with-eval-after-load 'yasnippet - (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets")) -@end lisp - -Les extraits de messages de commit dépendent de @url{https://magit.vc/, -Magit} pour afficher les fichiers sélectionnés. Lors de la modification -d'un message de commit, tapez @code{add} suivi de @kbd{TAB} pour insérer un -modèle de message de commit pour ajouter un paquet ; tapez @code{update} -suivi de @kbd{TAB} pour insérer un modèle pour la mise à jour d'un paquet ; -tapez @code{https} suivi de @kbd{TAB} pour insérer un modèle pour le -changement à HTTPS de l'URI de la page d'accueil. - -L'extrait principal pour @code{scheme-mode} est lancé en tapant -@code{package…} suivi par @kbd{TAB}. Cet extrait insère aussi la chaîne de -déclenchement @code{origin…}, qui peut aussi être étendue. L'extrait -@code{origin} lui-même peut aussi insérer des chaînes de déclenchement qui -finissent sur @code{…}, qui peuvent aussi être étendues. - - -@node Consignes d'empaquetage -@section Consignes d'empaquetage - -@cindex paquets, création -La distribution GNU est jeune et vos paquets préférés peuvent manquer. -Cette section décrit comment vous pouvez aider à agrandir la distribution. - -Les paquets de logiciels libres sont habituellement distribués sous forme -@dfn{d'archives de sources} — typiquement des fichiers @file{.tar.gz} -contenant tous les fichiers sources. Ajouter un paquet à la distribution -signifie essentiellement deux choses : ajouter une @dfn{recette} qui décrit -comment construire le paquet, avec une liste d'autres paquets requis pour le -construire, et ajouter des @dfn{métadonnées de paquet} avec la recette, -comme une description et une licence. - -Dans Guix, toutes ces informations sont incorporées dans les -@dfn{définitions de paquets}. Les définitions de paquets fournissent une -vue de haut-niveau du paquet. Elles sont écrites avec la syntaxe du langage -de programmation Scheme ; en fait, pour chaque paquet nous définissons une -variable liée à la définition et exportons cette variable à partir d'un -module (@pxref{Modules de paquets}). Cependant, il n'est @emph{pas} nécessaire -d'avoir une connaissance approfondie du Scheme pour créer des paquets. Pour -plus d'informations sur les définitions des paquets, @pxref{Définition des paquets}. - -Une fois une définition de paquet en place, stocké dans un fichier de -l'arborescence des sources de Guix, il peut être testé avec la commande -@command{guix build} (@pxref{Invoquer guix build}). Par exemple, en -supposant que le nouveau paquet s'appelle @code{gnew}, vous pouvez lancer -cette commande depuis l'arborescence de construction de Guix (@pxref{Lancer Guix avant qu'il ne soit installé}) : - -@example -./pre-inst-env guix build gnew --keep-failed -@end example - -Utiliser @code{--keep-failed} rend facile le débogage des échecs car il -fournit l'accès à l'arborescence de construction qui a échouée. Une autre -sous-commande utile pour le débogage est @code{--log-file}, pour accéder au -journal de construction. - -Si le paquet n'est pas connu de la commande @command{guix}, il se peut que -le fichier source ait une erreur de syntaxe, ou qu'il manque une clause -@code{define-public} pour exporter la variable du paquet. Pour comprendre -cela, vous pouvez charger le module depuis Guile pour avoir plus -d'informations sur la véritable erreur : - -@example -./pre-inst-env guile -c '(use-modules (gnu packages gnew))' -@end example - -Une fois que votre paquet est correctement construit, envoyez-nous un -correctif (@pxref{Contribuer}). Enfin, si vous avez besoin d'aide, nous -serrons ravis de vous aider. Une fois que le correctif soumis est committé -dans le dépôt Guix, le nouveau paquet est automatiquement construit sur les -plate-formes supportées par @url{http://hydra.gnu.org/jobset/gnu/master, -notre système d'intégration continue}. - -@cindex substitution -On peut obtenir la nouvelle définition du paquet simplement en lançant -@command{guix pull} (@pxref{Invoquer guix pull}). Lorsque -@code{@value{SUBSTITUTE-SERVER}} a fini de construire le paquet, -l'installation du paquet y télécharge automatiquement les binaires -(@pxref{Substituts}). La seule intervention humaine requise est pendant la -revue et l'application du correctif. - - -@menu -* Liberté logiciel:: Ce que la distribution peut contenir. -* Conventions de nommage:: Qu'est-ce qu'un bon nom ? -* Numéros de version:: Lorsque le nom n'est pas suffisant. -* Synopsis et descriptions:: Aider les utilisateurs à trouver le bon - paquet. -* Modules python:: Un peu de comédie anglaise. -* Modules perl:: Petites perles. -* Paquets java:: Pause café. -* Polices de caractères:: À fond les fontes. -@end menu - -@node Liberté logiciel -@subsection Liberté logiciel - -@c =========================================================================== -@c -@c This file was generated with po4a. Translate the source file. -@c -@c =========================================================================== -@c Adapted from http://www.gnu.org/philosophy/philosophy.html. -@cindex logiciel libre -Le système d'exploitation GNU a été développé pour que les utilisateurs -puissent utiliser leur ordinateur en toute liberté. GNU est un -@dfn{logiciel libre}, ce qui signifie que les utilisateur ont les -@url{http://www.gnu.org/philosophy/free-sw.fr.html,quatre libertés -essentielles} : exécuter le programmer, étudier et modifier le programme -sous sa forme source, redistribuer des copies exactes et distribuer les -versions modifiées. Les paquets qui se trouvent dans la distribution GNU ne -fournissent que des logiciels qui respectent ces quatre libertés. - -En plus, la distribution GNU suit les -@url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,recommandations -pour les distributions systèmes libres}. Entre autres choses, ces -recommandations rejettent les microgiciels non libres, les recommandations -de logiciels non libres et discute des façon de gérer les marques et les -brevets. - -Certaines sources amont autrement parfaitement libres contiennent une petite -partie facultative qui viole les recommandations ci-dessus, par exemple car -cette partie est du code non-libre. Lorsque cela arrive, les éléments en -question sont supprimés avec des correctifs ou des bouts de codes appropriés -dans la forme @code{origin} du paquet (@pxref{Définition des paquets}). De cette -manière, @code{guix build --source} renvoie la source « libérée » plutôt que -la source amont sans modification. - - -@node Conventions de nommage -@subsection Conventions de nommage - -@cindex nom du paquet -Un paquet a en fait deux noms qui lui sont associés : d'abord il y a le nom -de la @emph{variable Scheme}, celui qui suit @code{define-public}. Par ce -nom, le paquet peut se faire connaître par le code Scheme, par exemple comme -entrée d'un autre paquet. Deuxièmement, il y a la chaîne dans le champ -@code{name} d'une définition de paquet. Ce nom est utilisé par les -commandes de gestion des paquets comme @command{guix package} et -@command{guix build}. - -Les deux sont habituellement les mêmes et correspondent à la conversion en -minuscule du nom du projet choisi en amont, où les underscores sont -remplacés par des tirets. Par exemple, GNUnet est disponible en tant que -@code{gnunet} et SDL_net en tant que @code{sdl-net}. - -Nous n'ajoutons pas de préfixe @code{lib} au bibliothèques de paquets, à -moins qu'il ne fasse partie du nom officiel du projet. Mais @pxref{Modules python} et @ref{Modules perl} pour des règles spéciales concernant les -modules pour les langages Python et Perl. - -Les noms de paquets de polices sont gérés différemment, @pxref{Polices de caractères}. - - -@node Numéros de version -@subsection Numéros de version - -@cindex version du paquet -Nous n'incluons en général que la dernière version d'un projet de logiciel -libre donné. Mais parfois, par exemple pour des versions incompatibles de -bibliothèques, deux (ou plus) versions du même paquet sont requises. Elles -ont besoin d'un nom de variable Scheme différent. Nous utilisons le nom -défini dans @ref{Conventions de nommage} pour la version la plus récente ; les -versions précédentes utilisent le même nom, suffixé par @code{-} et le plus -petit préfixe du numéro de version qui permet de distinguer deux versions. - -Le nom dans la définition du paquet est le même pour toutes les versions -d'un paquet et ne contient pas de numéro de version. - -Par exemple, les version 2.24.20 et 3.9.12 de GTK+ peuvent être inclus de -cette manière : - -@example -(define-public gtk+ - (package - (name "gtk+") - (version "3.9.12") - ...)) -(define-public gtk+-2 - (package - (name "gtk+") - (version "2.24.20") - ...)) -@end example -Si nous voulons aussi GTK+ 3.8.2, cela serait inclus de cette manière : -@example -(define-public gtk+-3.8 - (package - (name "gtk+") - (version "3.8.2") - ...)) -@end example - -@c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>, -@c for a discussion of what follows. -@cindex numéro de version, pour les instantanés des systèmes de contrôle de version -Parfois, nous incluons des paquets provenant d'instantanés de systèmes de -contrôle de version (VCS) au lieu de versions publiées formellement. Cela -devrait rester exceptionnel, car c'est le rôle des développeurs amont de -spécifier quel est la version stable. Cependant, c'est parfois nécessaire. -Donc, que faut-il mettre dans le champ @code{version} ? - -Clairement, nous devons rendre l'identifiant de commit de l'instantané du -VCS visible dans la version, mais nous devons aussi nous assurer que la -version augmente de manière monotone pour que @command{guix package ---upgrade} puisse déterminer quelle version est la plus récente. Comme les -identifiants de commits, notamment avec Git, n'augmentent pas, nous ajoutons -un numéro de révision qui nous augmentons à chaque fois que nous mettons à -jour vers un nouvel instantané. La chaîne qui en résulte ressemble à cela : - -@example -2.0.11-3.cabba9e - ^ ^ ^ - | | `-- ID du commit en amont - | | - | `--- révision du paquet Guix - | -dernière version en amont -@end example - -C'est une bonne idée de tronquer les identifiants dans le champ -@code{version} à disons 7 caractères. Cela évite un problème esthétique (en -supposant que l'esthétique ait un rôle à jouer ici) et des problèmes avec -les limites de l'OS comme la longueur maximale d'un shebang (127 octets pour -le noyau Linux). Il vaut mieux utilise l'identifiant de commit complet dans -@code{origin} cependant, pour éviter les ambiguïtés. Une définition de -paquet peut ressembler à ceci : - -@example -(define my-package - (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7") - (revision "1")) ;révision du paquet Guix - (package - (version (git-version "0.9" revision commit)) - (source (origin - (method git-fetch) - (uri (git-reference - (url "git://example.org/my-package.git") - (commit commit))) - (sha256 (base32 "1mbikn@dots{}")) - (file-name (git-file-name name version)))) - ;; @dots{} - ))) -@end example - -@node Synopsis et descriptions -@subsection Synopsis et descriptions - -@cindex description du paquet -@cindex résumé du paquet -Comme nous l'avons vu avant, chaque paquet dans GNU@tie{}Guix contient un -résumé et une description (@pxref{Définition des paquets}). Les résumés et les -descriptions sont importants : ce sont eux que recherche @command{guix -package --search}, et c'est une source d'informations cruciale pour aider -les utilisateurs à déterminer si un paquet donner correspond à leurs -besoins. En conséquence, les mainteneurs doivent prêter attention à leur -contenu. - -Les résumés doivent commencer par une lettre capitale et ne doit pas finir -par un point. Ils ne doivent pas commencer par « a » ou « the » (« un » ou -« le/la »), ce qui n'apporte généralement rien ; par exemple, préférez « -File-frobbing tool » (« Outil de frobage de fichier ») à « A tool that frobs -file » (« Un outil qui frobe les fichiers »). Le résumé devrait dire ce que -le paquet est — p.@: ex.@: « Utilitaire du cœur de GNU (fichier, text, -shell) » — ou ce à quoi il sert — p.@: ex.@: le résumé de grep est « Affiche -des lignes correspondant à un motif ». - -Gardez à l'esprit que le résumé doit avoir un sens pour une large audience. -Par exemple « Manipulation d'alignements au format SAM » peut avoir du sens -pour un bioinformaticien chevronné, mais n'aidera pas ou pourra perdre une -audience de non-spécialistes. C'est une bonne idée de créer un résumé qui -donne une idée du domaine d'application du paquet. Dans cet exemple, cela -donnerait « Manipulation d'alignements de séquences de nucléotides », ce qui -devrait donner une meilleure idée à l'utilisateur pour savoir si c'est ce -qu'il recherche. - -Les descriptions devraient faire entre cinq et dix lignes. Utilisez des -phrases complètes, et évitez d'utiliser des acronymes sans les introduire -d'abord. Évitez les phrases marketings comme « world-leading », « -industrial-strength » et « next-generation » et évitez les superlatifs comme -« the most advanced » — ils ne sont pas utiles pour les utilisateurs qui -cherchent un paquet et semblent même un peu suspects. À la place, essayez -d'être factuels, en mentionnant les cas d'utilisation et les -fonctionnalités. - -@cindex balisage texinfo, dans les descriptions de paquets -Les descriptions peuvent inclure du balisage Texinfo, ce qui est utile pour -introduire des ornements comme @code{@@code} ou @code{@@dfn}, des listes à -points ou des hyperliens (@pxref{Overview,,, texinfo, GNU Texinfo}). -Cependant soyez prudents lorsque vous utilisez certains symboles, par -exemple @samp{@@} et les accolades qui sont les caractères spéciaux de base -en Texinfo (@pxref{Special Characters,,, texinfo, GNU Texinfo}). Les -interfaces utilisateurs comme @command{guix package --show} prennent en -charge le rendu. - -Les résumés et les descriptions sont traduits par des volontaires -@uref{http://translationproject.org/domain/guix-packages.html, sur le projet -de traduction} pour que le plus d'utilisateurs possible puissent les lire -dans leur langue natale. Les interfaces utilisateurs les recherchent et les -affichent dans la langue spécifiée par le paramètre de régionalisation -actuel. - -Pour permettre à @command{xgettext} de les extraire comme des chaînes -traduisibles, les résumés et les descriptions @emph{doivent être des chaînes -litérales}. Cela signifie que vous ne pouvez pas utiliser -@code{string-append} ou @code{format} pour construire ces chaînes : - -@lisp -(package - ;; @dots{} - (synopsis "Ceci est traduisible") - (description (string-append "Ceci n'est " "*pas*" " traduisible."))) -@end lisp - -La traduction demande beaucoup de travail, donc en tant que packageur, -faîtes encore plus attention à vos résumés et descriptions car chaque -changement peut demander d'autant plus de travail de la part des -traducteurs. Pour les aider, il est possible de donner des recommandations -ou des instructions qu'ils pourront voir en insérant des commentaires -spéciaux comme ceci (@pxref{xgettext Invocation,,, gettext, GNU Gettext}) : - -@example -;; TRANSLATORS: "X11 resize-and-rotate" should not be translated. -(description "ARandR is designed to provide a simple visual front end -for the X11 resize-and-rotate (RandR) extension. @dots{}") -@end example - - -@node Modules python -@subsection Modules python - -@cindex python -Nous incluons actuellement Python 2 et Python 3, sous les noms de variables -Scheme @code{python-2} et @code{python} comme expliqué dans @ref{Numéros de version}. Pour éviter la confusion et les problèmes de noms avec d'autres -langages de programmation, il semble désirable que le nom d'un paquet pour -un module Python contienne le mot @code{python}. - -Certains modules ne sont compatibles qu'avec une version de Python, d'autres -avec les deux. Si le paquet Foo ne compile qu'avec Ptyhon 3, on le nomme -@code{python-foo} ; s'il ne compile qu'avec Python 2, on le nome -@code{python2-foo}. S'il est compatible avec les deux versions, nous créons -deux paquets avec les noms correspondant. - -Si un projet contient déjà le mot @code{python}, on l'enlève, par exemple le -module python-dateutil est packagé sous les noms @code{python-dateutil} et -@code{python2-dateutil}. Si le nom du projet commence par @code{py} (p.@: -ex.@: @code{pytz}), on le garde et on le préfixe comme décrit ci-dessus. - -@subsubsection Spécifier les dépendances -@cindex entrées, pour les paquets Python - -Les informations de dépendances pour les paquets Python se trouvent -généralement dans l'arborescence des source du paquet, avec plus ou moins de -précision : dans le fichier @file{setup.py}, dans @file{requirements.txt} ou -dans @file{tox.ini}. - -Votre mission, lorsque vous écrivez une recette pour un paquet Python, est -de faire correspondre ces dépendances au bon type « d'entrée » -(@pxref{Référence des paquets, inputs}). Bien que l'importeur @code{pypi} fasse -du bon boulot (@pxref{Invoquer guix import}), vous devriez vérifier la liste -suivant pour déterminer où va telle dépendance. - -@itemize - -@item -Nous empaquetons Python 2 avec @code{setuptools} et @code{pip} installé -comme Python 3.4 par défaut. Ainsi, vous n'avez pas à spécifié ces -entrées. @command{guix lint} vous avertira si vous faîtes cela. - -@item -Les dépendances Python requises à l'exécutions vont dans -@code{propagated-inputs}. Elles sont typiquement définies dans le mot-clef -@code{install_requires} dans @file{setup.py} ou dans le fichier -@file{requirements.txt}. - -@item -Les paquets Python requis uniquement à la construction — p.@: ex.@: ceux -listés dans le mot-clef @code{setup_requires} de @file{setup.py} — ou -seulement pour les tests — p.@: ex.@: ceux dans @code{tests_require} — vont -dans @code{native-inputs}. La raison est qu'ils n'ont pas besoin d'être -propagés car ils ne sont pas requis à l'exécution et dans le cas d'une -compilation croisée, c'est l'entrée « native » qu'il nous faut. - -Les cadriciels de tests @code{pytest}, @code{mock} et @code{nose} sont des -exemples. Bien sûr si l'un de ces paquets est aussi requis à l'exécution, -il doit aller dans @code{propagated-inputs}. - -@item -Tout ce qui ne tombe pas dans les catégories précédentes va dans -@code{inputs}, par exemple des programmes pour des bibliothèques C requises -pour construire des paquets Python avec des extensions C. - -@item -Si un paquet Python a des dépendances facultatives (@code{extras_require}), -c'est à vous de décider de les ajouter ou non, en fonction du ratio entre -utilité et complexité (@pxref{Envoyer des correctifs, @command{guix size}}). - -@end itemize - - -@node Modules perl -@subsection Modules perl - -@cindex perl -Les programmes Perl utiles en soit sont nommés comme les autres paquets, -avec le nom amont en minuscule. Pour les paquets Perl contenant une seule -classe, nous utilisons le nom de la classe en minuscule, en remplaçant les -occurrences de @code{::} par des tirets et en préfixant le tout par -@code{perl-}. Donc la classe @code{XML::Parser} devient -@code{perl-xml-parser}. Les modules contenant plusieurs classes gardent -leur nom amont en minuscule et sont aussi préfixés par @code{perl-}. Ces -modules tendent à avoir le mot @code{perl} quelque part dans leur nom, que -nous supprimons en faveur du préfixe. Par exemple, @code{libwww-perl} -devient @code{perl-libwww}. - - -@node Paquets java -@subsection Paquets java - -@cindex java -Le programmes Java utiles en soit sont nommés comme les autres paquets, avec -le nom amont en minuscule. - -Pour éviter les confusions et les problèmes de nom avec d'autres langages de -programmation, il est désirable que le nom d'un paquet Java soit préfixé par -@code{java-}. Si un projet contient déjà le mot @code{java}, nous le -supprimons, par exemple le paquet @code{ngsjava} est empaqueté sous le nom -@code{java-ngs}. - -Pour les paquets java contenant une seul classe ou une petite hiérarchie de -classes, nous utilisons le nom de la classe en minuscule, en remplaçant les -occurrences de @code{.} par des tirets et en préfixant le tout par -@code{java-}. Donc la classe @code{apache.commons.cli} devient -@code{java-apache-commons-cli}. - - -@node Polices de caractères -@subsection Polices de caractères - -@cindex polices -Pour les polices qui n esont en général par installées par un utilisateurs -pour du traitement de texte, ou qui sont distribuées en tant que partie d'un -paquet logiciel plus gros, nous nous appuyons sur les règles générales pour -les logiciels ; par exemple, cela s'applique aux polices livrées avec le -système X.Org ou les polices qui font partie de TeX Live. - -Pour rendre plus facile la recherche par l'utilisateur, les noms des autres -paquets contenant seulement des polices sont construits ainsi, -indépendamment du nom du paquet en amont. - -Le nom d'un paquet contenant une unique famille de polices commence par -@code{font-} ; il est suivi du nom du fondeur et d'un tiret @code{-} si le -fondeur est connu, et du nom de la police, dont les espaces sont remplacés -par des tirets (et comme d'habitude, toutes les lettres majuscules sont -transformées en minuscules). Par exemple, la famille de polices Gentium de -SIL est empaqueté sous le nom @code{font-sil-gentium}. - -Pour un paquet contenant plusieurs familles de polices, le nom de la -collection est utilisée à la place du nom de la famille. Par exemple les -polices Liberation consistent en trois familles, Liberation Sans, Liberation -Serif et Liberation Mono. Elles pourraient être empaquetées séparément sous -les noms @code{font-liberation-sans} etc, mais comme elles sont distribuées -ensemble sous un nom commun, nous préférons les empaqueter ensemble en tant -que @code{font-liberation}. - -Dans le cas où plusieurs formats de la même famille ou collection sont -empaquetés séparément, une forme courte du format, préfixé d'un tiret est -ajouté au nom du paquet. Nous utilisont @code{-ttf} pour les polices -TrueType, @code{-otf} pour les polices OpenType et @code{-type1} pour les -polices Type 1 de PostScript. - - -@node Style de code -@section Style de code - -En général notre code suit le Standard de Code GNU (@pxref{Top,,, standards, -GNU Coding Standards}). Cependant, il ne parle pas beaucoup de Scheme, donc -voici quelques règles supplémentaires. - -@menu -* Paradigme de programmation:: Comment composer vos éléments. -* Modules:: Où stocker votre code ? -* Types de données et reconnaissance de motif:: Implémenter des - structures de données. -* Formatage du code:: Conventions d'écriture. -@end menu - -@node Paradigme de programmation -@subsection Paradigme de programmation - -Le code Scheme dans Guix est écrit dans un style purement fonctionnel. Le -code qui s'occupe des entrées-sorties est une exception ainsi que les -procédures qui implémentent des concepts bas-niveau comme la procédure -@code{memoize}. - -@node Modules -@subsection Modules - -Les modules Guile qui sont sensés être utilisés du côté de la construction -doivent se trouver dans l'espace de nom @code{(guix build @dots{})}. Ils ne -doivent pas se référer à d'autres modules Guix ou GNU@. Cependant il est -correct pour un module « côté hôte » de dépendre d'un module coté -construction. - -Les modules qui s'occupent du système GNU général devraient se trouver dans -l'espace de nom @code{(gnu @dots{})} plutôt que @code{(guix @dots{})}. - -@node Types de données et reconnaissance de motif -@subsection Types de données et reconnaissance de motif - -La tendance en Lisp classique est d'utiliser des listes pour tout -représenter et de naviguer dedans « à la main ( avec @code{car}, @code{cdr}, -@code{cadr} et compagnie. Il y a plusieurs problèmes avec ce style, -notamment le fait qu'il soit dur à lire, source d'erreur et un obstacle aux -rapports d'erreur bien typés. - -Le code de Guix devrait définir des types de données appropriées (par -exemple, avec @code{define-record-type*}) plutôt que d'abuser des listes. -En plus, il devrait utiliser la recherche de motifs, via le module Guile -@code{(ice-9 match)}, surtout pour rechercher dans des listes. - -@node Formatage du code -@subsection Formatage du code - -@cindex formater le code -@cindex style de code -Lorsque nous écrivons du code Scheme, nous suivons la sagesse commune aux -programmeurs Scheme. En général, nous suivons les -@url{http://mumble.net/~campbell/scheme/style.txt, règles de style de -Riastradh}. Ce document décrit aussi les conventions utilisées dans le code -de Guile. Il est bien pensé et bien écrit, alors n'hésitez pas à le lire. - -Certaines formes spéciales introduites dans Guix comme la macro -@code{substitute*} ont des règles d'indentation spécifiques. Elles sont -définies dans le fichier @file{.dir-locals.el} qu'Emacs utilise -automatiquement. Remarquez aussi qu'Emacs-Guix fournit le mode -@code{guix-devel-mode} qui indente et colore le code Guix correctement -(@pxref{Développement,,, emacs-guix, The Emacs-Guix Reference Manual}). - -@cindex indentation, du code -@cindex formatage, du code -Si vous n'utilisez pas Emacs, assurez-vous que votre éditeur connaisse ces -règles. Pour indenter automatiquement une définition de paquet, vous pouvez -aussi lancer : - -@example -./etc/indent-code.el gnu/packages/@var{file}.scm @var{package} -@end example - -@noindent -Cela indente automatiquement la définition de @var{package} dans -@file{gnu/packages/@var{file}.scm} en lançant Emacs en mode commande. Pour -indenter un fichier complet, n'indiquez pas de second argument : - -@example -./etc/indent-code.el gnu/services/@var{file}.scm -@end example - -@cindex Vim, édition de code Scheme -Si vous éditez du code avec Vim, nous recommandons de lancer @code{:set -autoindent} pour que votre code soit automatiquement indenté au moment où -vous l'entrez. En plus, -@uref{https://www.vim.org/scripts/script.php?script_id=3998, -@code{paredit.vim}} peut vous aider à gérer toutes ces parenthèses. - -Nous demandons que toutes les procédure de premier niveau contiennent une -chaîne de documentation. Ce prérequis peut être relâché pour les procédures -privées simples dans l'espace de nom @code{(guix build @dots{})} cependant. - -Les procédures ne devraient pas avoir plus de quatre paramètres -positionnés. Utilisez des paramètres par mot-clefs pour les procédures qui -prennent plus de quatre paramètres. - - -@node Envoyer des correctifs -@section Envoyer des correctifs - -Le développement se fait avec le système de contrôle de version Git. Ainsi, -l'accès au dépôt n'est pas strictement nécessaire. Nous accueillons les -contributions sous forme de correctifs produits par @code{git format-patch} -envoyés sur la liste de diffusion @email{guix-patches@@gnu.org}. - -Cette liste de diffusion est gérée par une instance Debbugs accessible à -l'adresse @uref{https://bugs.gnu.org/guix-patches}, qui nous permet de -suivre les soumissions. Chaque message envoyé à cette liste se voit -attribuer un numéro de suivi ; les gens peuvent ensuite répondre à cette -soumission en envoyant un courriel à @code{@var{NNN}@@debbugs.gnu.org}, où -@var{NNN} est le numéro de suivi (@pxref{Envoyer une série de correctifs}). - -Veuillez écrire les messages de commit dans le format ChangeLog -(@pxref{Change Logs,,, standards, GNU Coding Standards}) ; vous pouvez -regarder l'historique des commits pour trouver des exemples. - -Avant de soumettre un correctif qui ajoute ou modifie la définition d'un -paquet, veuillez vérifier cette check-list : - -@enumerate -@item -Si les auteurs du paquet logiciel fournissent une signature cryptographique -pour l'archive, faîtes un effort pour vérifier l'authenticité de l'archive. -Pour un fichier de signature GPG détaché, cela se fait avec la commande -@code{gpg --verify}. - -@item -Prenez un peu de temps pour fournir un synopsis et une description adéquats -pour le paquet. Voir @xref{Synopsis et descriptions} pour quelques lignes -directrices. - -@item -Lancez @code{guix lint @var{paquet}}, où @var{paquet} est le nom du nouveau -paquet ou du paquet modifié, et corrigez les erreurs qu'il rapporte -(@pxref{Invoquer guix lint}). - -@item -Assurez-vous que le paquet se construise sur votre plate-forme avec -@code{guix build @var{paquet}}. - -@item -Nous vous recommandons aussi d'essayer de construire le paquet sur les -autres plate-formes prises en charge. Comme vous n'avez pas forcément accès -aux plate-formes matérielles, nous vous recommandons d'utiliser le -@code{qemu-binfmt-service-type} pour les émuler. Pour cela, ajoutez le -service suivant à la liste des services dans votre configuration de système -d'exploitation : - -@example -(service qemu-binfmt-service-type - (qemu-binfmt-configuration - (platforms (lookup-qemu-platforms "arm" "aarch64" "mips64el")) - (guix-support? #t))) -@end example - -Puis reconfigurez votre système. - -Vous pourrez ensuite construire les paquets pour différentes plate-formes en -spécifiant l'option @code{--system}. Par exemple pour construire le paquet -« hello » pour les architectures armhf, aarch64 ou mips64, vous devrez -lancer les commandes suivantes, respectivement : -@example -guix build --system=armhf-linux --rounds=2 hello -guix build --system=aarch64-linux --rounds=2 hello -guix build --system=mips64el-linux --rounds=2 hello -@end example - -@item -@cindex construction groupée -Assurez-vous que le paquet n'utilise pas de copie groupée d'un logiciel déjà -disponible dans un paquet séparé. - -Parfois, les paquets incluent des copie du code source de leurs dépendances -pour le confort de leurs utilisateurs. Cependant, en tant que distribution, -nous voulons nous assurer que ces paquets utilisent bien les copient que -nous avons déjà dans la distribution si elles existent. Cela améliore -l'utilisation des ressources (la dépendance n'est construite et stockée -qu'une seule fois) et permet à la distribution de faire des changements -transversaux comme appliquer des correctifs de sécurité pour un paquet donné -depuis un unique emplacement et qu'ils affectent tout le système, ce -qu'empêchent les copies groupées. - -@item -Regardez le profil rapporté par @command{guix size} (@pxref{Invoquer guix size}). Cela vous permettra de remarquer des références à d'autres paquets -qui ont été retenus sans que vous vous y attendiez. Il peut aussi aider à -déterminer s'il faut découper le paquet (@pxref{Des paquets avec plusieurs -résultats}) et quelles dépendances facultatives utiliser. En particulier, -évitez d'ajouter @code{texlive} en dépendance : à cause de sa taille -extrême, utilisez @code{texlive-tiny} ou @code{texlive-union} à la place. - -@item -Pour les changements important, vérifiez que les paquets qui en dépendent -(s'ils existent) ne sont pas affectés par le changement ; @code{guix refresh ---list-dependant @var{paquet}} vous aidera (@pxref{Invoquer guix refresh}). - -@c See <https://lists.gnu.org/archive/html/guix-devel/2016-10/msg00933.html>. -@cindex stratégie de branche -@cindex stratégie de planification des reconstructions -Suivant le nombre de paquets dépendants et donc le nombre de reconstruction -induites, les commits vont vers des branches différentes, suivant ces -principes : - -@table @asis -@item 300 paquets dépendants ou moins -branche @code{master} (changements non-disruptifs). - -@item entre 300 et 1 200 paquets dépendants -branche @code{staging} (changements non-disruptifs). Cette branche devrait -être fusionnées dans @code{master} tous les 3 semaines. Les changements par -thèmes (par exemple une mise à jour de la pile GNOME) peuvent aller dans une -branche spécifique (disons, @code{gnome-updates}). - -@item plus de 1 200 paquets dépendants -branche @code{core-updates} (peut inclure des changements majeurs et -potentiellement disruptifs). Cette branche devrait être fusionnée dans -@code{master} tous les 2,5 mois environ. -@end table - -Toutes ces branches sont @uref{https://hydra.gnu.org/project/gnu, gérées par -notre ferme de construction} et fusionnées dans @code{master} une fois que -tout a été construit correctement. Cela nous permet de corriger des -problèmes avant qu'ils n'atteignent les utilisateurs et réduit la fenêtre -pendant laquelle les binaires pré-construits ne sont pas disponibles. - -@c TODO: It would be good with badges on the website that tracks these -@c branches. Or maybe even a status page. -Généralement les autres branches que @code{master} sont considérées comme -@emph{gelées} s'il y a eu une évaluation récente ou qu'il y a une branche -@code{-next} correspondante. Demandez sur la liste de diffusion ou sur IRC -si vous n'êtes pas sûr de savoir où pousser votre correctif. - -@item -@cindex déterminisme, du processus de construction -@cindex construction reproductibles, vérification -Vérifiez si le processus de construction du paquet est déterministe. Cela -signifie typiquement vérifier qu'une construction indépendante du paquet -renvoie exactement le même résultat que vous avez obtenu, bit à bit. - -Une manière simple de le faire est de reconstruire le paquet plusieurs fois -à la suite sur votre machine (@pxref{Invoquer guix build}) : - -@example -guix build --rounds=2 mon-paquet -@end example - -Cela est suffisant pour trouver une classe de non-déterminisme commune, -comme l'horodatage ou des sorties générées aléatoirement dans le résultat de -la construction. - -Une autre option consiste à utiliser @command{guix challenge} -(@pxref{Invoquer guix challenge}). Vous pouvez lancer la commande une fois -que les paquets ont été committés et construits par -@code{@value{SUBSTITUTE-SERVER}} pour vérifier s'il obtient le même résultat -que vous. Mieux encore : trouvez une autre machine qui peut le construire -et lancez @command{guix publish}. Puisque la machine distante est sûrement -différente de la vôtre, cela peut trouver des problèmes de non-déterminisme -liés au matériel — par exemple utiliser une extension du jeu d'instruction — -ou du noyau du système d'exploitation — par exemple se reposer sur -@code{uname} ou les fichiers de @file{/proc}. - -@item -Lorsque vous écrivez de la documentation, utilisez une formulation au genre -neutre lorsque vous vous référez à des personnes, comme le -@uref{https://fr.wikipedia.org/wiki/They_singulier, ``they''@comma{} -``their''@comma{} ``them'' singulier} (en anglais). - -@item -Vérifiez que votre correctif contienne seulement un ensemble de changements -liés. Grouper des changements non liés ensemble rend la revue plus -difficile et plus lente. - -Ajouter plusieurs paquet ou une mise à jour d'un paquet avec des corrections -dans ce paquet sont des exemples de changements sans rapport. - -@item -Suivez nos règles de formatage de code, éventuellement en lançant le script -@command{et/indent-code.el} pour le faire automatiquement (@pxref{Formatage -du code}). - -@item -Si possible, utilisez des miroirs dans l'URL des sources (@pxref{Invoquer guix download}). Utilisez des URL stable, pas des URL générées. Par -exemple, les archives GitHub ne sont pas nécessairement identiques d'une -génération à la suivante, donc il vaut mieux dans ce cas cloner le dépôt. -N'utilisez pas le champ @command{name} dans l'URL : ce n'est pas très utile -et si le nom change, l'URL sera probablement erronée. - -@end enumerate - -Lorsque vous envoyez un correctif à la liste de diffusion, utilisez -@samp{[PATCH] @dots{}} comme sujet. Vous pouvez utiliser votre client de -courriel ou la commande @command{git send-email} (@pxref{Envoyer une série -de correctifs}). Nous préférons recevoir des correctifs en texte brut, soit -en ligne, soit en pièce-jointe MIME@. Nous vous conseillons de faire -attention si votre client de courriel change par exemple les retours à la -ligne ou l'indentation, ce qui peut casser les correctifs. - -Lorsqu'un bogue est résolu, veuillez fermer le fil en envoyant un courriel à -@email{@var{NNN}-done@@debbugs.gnu.org}. - -@unnumberedsubsec Envoyer une série de correctifs -@anchor{Envoyer une série de correctifs} -@cindex série de correctifs -@cindex @code{git send-email} -@cindex @code{git-send-email} - -@c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html -Lorsque vous envoyez une série de correctifs (p.@@:: ex.@: avec @code{git -send-email}), envoyez d'abord une premier message à -@email{guix-patches@@gnu.org} puis envoyez le reste des correctifs à -@email{@var{NNN}@@debbugs.gnu.org} pour vous assurer qu'ils seront groupés -ensemble. Voyez @uref{https://debbugs.gnu.org/Advanced.html, la -documentation de Debbugs} pour plus d'informations. |