Commit | Line | Data |
---|---|---|
bf5c74e7 JL |
1 | @node Contribuer |
2 | @chapter Contribuer | |
3 | ||
4 | Ce projet est un effort coopératif et nous avons besoin de votre aide pour | |
5 | le faire grandir ! Contactez-nous sur @email{guix-devel@@gnu.org} et | |
3cacfa9e LC |
6 | @code{#guix} sur le réseau IRC Freenode. Nous accueillons les idées, les |
7 | rapports de bogues, les correctifs et tout ce qui pourrait aider le projet. | |
8 | Nous apprécions particulièrement toute aide sur la création de paquets | |
9 | (@pxref{Consignes d'empaquetage}). | |
bf5c74e7 JL |
10 | |
11 | @cindex code de conduite, des contributeurs | |
12 | @cindex convention de contribution | |
13 | Nous souhaitons fournir un environnement chaleureux, amical et sans | |
14 | harcèlement pour que tout le monde puisse contribuer au mieux de ses | |
3cacfa9e LC |
15 | capacités. Pour cela notre projet a une « Convention de contribution » |
16 | adaptée de @url{http://contributor-covenant.org/}. Vous pouvez trouver une | |
bf5c74e7 JL |
17 | version locale dans le fichier @file{CODE-OF-CONDUCT} dans l'arborescence |
18 | des sources. | |
19 | ||
20 | Les contributeurs n'ont pas besoin d'utiliser leur nom légal dans leurs | |
21 | correctifs et leurs communications en ligne ; ils peuvent utiliser n'importe | |
22 | quel nom ou pseudonyme de leur choix. | |
23 | ||
24 | @menu | |
ad377c3d | 25 | * Construire depuis Git:: Toujours le plus récent. |
bf5c74e7 JL |
26 | * Lancer Guix avant qu'il ne soit installé:: Astuces pour les hackers. |
27 | * La configuration parfaite:: Les bons outils. | |
15f1bff4 | 28 | * Consignes d'empaquetage:: Faire grandir la distribution. |
bf5c74e7 JL |
29 | * Style de code:: Hygiène du contributeur. |
30 | * Envoyer des correctifs:: Partager votre travail. | |
31 | @end menu | |
32 | ||
33 | @node Construire depuis Git | |
34 | @section Construire depuis Git | |
35 | ||
36 | Si vous souhaitez travailler sur Guix lui-même, il est recommandé d'utiliser | |
37 | la dernière version du dépôt Git : | |
38 | ||
39 | @example | |
40 | git clone https://git.savannah.gnu.org/git/guix.git | |
41 | @end example | |
42 | ||
43 | Lors de la construction de Guix depuis un extrait, les paquets suivants sont | |
44 | requis en plus de ceux mentionnés dans les instructions d'installation | |
45 | (@pxref{Prérequis}). | |
46 | ||
47 | @itemize | |
48 | @item @url{http://gnu.org/software/autoconf/, GNU Autoconf}; | |
49 | @item @url{http://gnu.org/software/automake/, GNU Automake}; | |
50 | @item @url{http://gnu.org/software/gettext/, GNU Gettext}; | |
51 | @item @url{http://gnu.org/software/texinfo/, GNU Texinfo}; | |
52 | @item @url{http://www.graphviz.org/, Graphviz}; | |
53 | @item @url{http://www.gnu.org/software/help2man/, GNU Help2man (facultatif)}. | |
54 | @end itemize | |
55 | ||
56 | La manière la plus simple de configurer un environnement de développement | |
57 | pour Guix est, bien sûr, d'utiliser Guix ! La commande suivante démarre un | |
58 | nouveau shell où toutes les dépendances et les variables d'environnements | |
59 | appropriées sont configurés pour travailler sur Guix : | |
60 | ||
61 | @example | |
62 | guix environment guix | |
63 | @end example | |
64 | ||
65 | @xref{Invoquer guix environment}, pour plus d'information sur cette | |
3cacfa9e | 66 | commande. On peut ajouter des dépendances supplémentaires avec |
bf5c74e7 JL |
67 | @option{--ad-hoc} : |
68 | ||
69 | @example | |
70 | guix environment guix --ad-hoc help2man git strace | |
71 | @end example | |
72 | ||
73 | Lancez @command{./bootstrap} pour générer l'infrastructure du système de | |
3cacfa9e | 74 | construction avec Autoconf et Automake. Si vous avez une erreur comme : |
bf5c74e7 JL |
75 | |
76 | @example | |
77 | configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES | |
78 | @end example | |
79 | ||
80 | @noindent | |
81 | cela signifie probablement qu'Autoconf n'a pas pu trouver @file{pkg.m4} qui | |
3cacfa9e LC |
82 | est fournit par pkg-config. Assurez-vous que @file{pkg.m4} est disponible. |
83 | C'est aussi vrai pour l'ensemble de macros de @file{guile.m4} fournies par | |
84 | Guile. Par exemple, si vous avez installé Automake dans @file{/usr/local}, | |
85 | il ne cherchera pas les fichiers @file{.m4} dans @file{/usr/share}. Dans ce | |
86 | case vous devez invoquer la commande suivante : | |
bf5c74e7 JL |
87 | |
88 | @example | |
89 | export ACLOCAL_PATH=/usr/share/aclocal | |
90 | @end example | |
91 | ||
92 | @xref{Macro Search Path,,, automake, The GNU Automake Manual}, pour plus | |
93 | d'information. | |
94 | ||
3cacfa9e | 95 | Ensuite, lancez @command{./configure} comme d'habitude. Assurez-vous de |
bf5c74e7 JL |
96 | passer @code{--localstatedir=@var{directory}} où @var{directory} est la |
97 | valeur @code{localstatedir} utilisée par votre installation actuelle | |
98 | (@pxref{Le dépôt} pour plus d'informations à ce propos). | |
99 | ||
100 | Finalement, vous devez invoquer @code{make check} pour lancer les tests | |
3cacfa9e | 101 | (@pxref{Lancer la suite de tests}). Si quelque chose échoue, jetez un œil |
bf5c74e7 | 102 | aux instructions d'installation (@pxref{Installation}) ou envoyez un message |
15f1bff4 | 103 | à la liste @email{guix-devel@@gnu.org}. |
bf5c74e7 JL |
104 | |
105 | ||
106 | @node Lancer Guix avant qu'il ne soit installé | |
107 | @section Lancer Guix avant qu'il ne soit installé | |
108 | ||
109 | Pour garder un environnement de travail sain, il est utile de tester les | |
3cacfa9e | 110 | changement localement sans les installer pour de vrai. Pour pouvoir |
bf5c74e7 JL |
111 | distinguer votre rôle « d'utilisateur final » de celui parfois haut en |
112 | couleur de « développeur ». | |
113 | ||
adfb167f JL |
114 | Pour cela, tous les outils en ligne de commande sont utilisables même sans |
115 | avoir lancé @code{make install}. Pour cela, vous devez d'abord avoir un | |
116 | environnement avec toutes les dépendances disponibles (@pxref{Construire depuis Git}), puis préfixer chaque commande par @command{./pre-inst-env} (le script | |
117 | @file{pre-inst-env} se trouve dans le répertoire de plus haut niveau de | |
118 | l'arborescence des sources de Guix ; il est généré par | |
119 | @command{./configure}) comme cela@footnote{L'option @option{-E} de | |
120 | @command{sudo} garantie que @code{GUILE_LOAD_PATH} est bien paramétré pour | |
121 | @command{guix-daemon} et pour que les outils qu'il utilise puissent trouver | |
122 | les modules Guile dont ils ont besoin.} : | |
bf5c74e7 JL |
123 | |
124 | @example | |
125 | $ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild | |
126 | $ ./pre-inst-env guix build hello | |
127 | @end example | |
128 | ||
129 | @noindent | |
130 | De même, pour une session Guile qui utilise les modules Guix : | |
131 | ||
132 | @example | |
133 | $ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))' | |
134 | ||
135 | ;;; ("x86_64-linux") | |
136 | @end example | |
137 | ||
138 | @noindent | |
139 | @cindex REPL | |
140 | @cindex read-eval-print loop | |
141 | @dots{} et pour un REPL (@pxref{Using Guile Interactively,,, guile, Guile | |
142 | Reference Manual}) | |
143 | ||
144 | @example | |
145 | $ ./pre-inst-env guile | |
146 | scheme@@(guile-user)> ,use(guix) | |
147 | scheme@@(guile-user)> ,use(gnu) | |
148 | scheme@@(guile-user)> (define snakes | |
149 | (fold-packages | |
150 | (lambda (package lst) | |
151 | (if (string-prefix? "python" | |
152 | (package-name package)) | |
153 | (cons package lst) | |
154 | lst)) | |
155 | '())) | |
156 | scheme@@(guile-user)> (length snakes) | |
157 | $1 = 361 | |
158 | @end example | |
159 | ||
160 | Le script @command{pre-inst-env} paramètre toutes les variables | |
161 | d'environnement nécessaires, dont @env{PATH} et @env{GUILE_LOAD_PATH}. | |
162 | ||
163 | Remarquez que @command{./pre-inst-env guix pull} ne met @emph{pas} à jour | |
2cf2c778 JL |
164 | l'arborescence des sources locale ; cela met seulement à jour le lien |
165 | symbolique de @file{~/.config/guix/current} (@pxref{Invoquer guix pull}). | |
3cacfa9e | 166 | Lancez @command{git pull} à la place si vous voulez mettre à jour votre |
2cf2c778 | 167 | arborescence des source locale. |
bf5c74e7 JL |
168 | |
169 | ||
170 | @node La configuration parfaite | |
171 | @section La configuration parfaite | |
172 | ||
ad377c3d JL |
173 | La configuration parfaite pour travailler sur Guix est simplement la |
174 | configuration parfaite pour travailler en Guile (@pxref{Using Guile in | |
175 | Emacs,,, guile, Guile Reference Manual}). Tout d'abord, vous avez besoin de | |
176 | mieux qu'un éditeur de texte, vous avez besoin de | |
177 | @url{http://www.gnu.org/software/emacs, Emacs}, amélioré par le superbe | |
178 | @url{http://nongnu.org/geiser/, Geiser}. Pour paramétrer cela, lancez : | |
15f1bff4 JL |
179 | |
180 | @example | |
181 | guix package -i emacs guile emacs-geiser | |
182 | @end example | |
bf5c74e7 JL |
183 | |
184 | Geiser permet le développement interactif et incrémental depuis Emacs : la | |
185 | compilation du code et son évaluation depuis les buffers, l'accès à la | |
186 | documentation en ligne (docstrings), la complétion sensible au contexte, | |
187 | @kbd{M-.} pour sauter à la définition d'un objet, un REPL pour tester votre | |
3cacfa9e LC |
188 | code, et bien plus (@pxref{Introduction,,, geiser, Geiser User Manual}). |
189 | Pour travailler confortablement sur Guix, assurez-vous de modifier le chemin | |
190 | de chargement de Guile pour qu'il trouve les fichiers source de votre dépôt | |
191 | : | |
bf5c74e7 JL |
192 | |
193 | @lisp | |
194 | ;; @r{Si l'extrait est dans ~/src/guix.} | |
195 | (with-eval-after-load 'geiser-guile | |
196 | (add-to-list 'geiser-guile-load-path "~/src/guix")) | |
197 | @end lisp | |
198 | ||
3cacfa9e LC |
199 | Pour effectivement éditer le code, Emacs a déjà un très bon mode Scheme. |
200 | Mais en plus de ça, vous ne devez pas rater | |
201 | @url{http://www.emacswiki.org/emacs/ParEdit, Paredit}. Il fournit des | |
202 | fonctionnalités pour opérer directement sur l'arbre de syntaxe, comme | |
203 | relever une s-expression ou l'envelopper, absorber ou rejeter la | |
204 | s-expression suivante, etc. | |
bf5c74e7 JL |
205 | |
206 | @cindex extraits de code | |
207 | @cindex modèles | |
208 | @cindex réduire la quantité de code commun | |
209 | Nous fournissons aussi des modèles pour les messages de commit git communs | |
3cacfa9e | 210 | et les définitions de paquets dans le répertoire @file{etc/snippets}. Ces |
bf5c74e7 JL |
211 | modèles s'utilisent avec @url{http://joaotavora.github.io/yasnippet/, |
212 | YASnippet} pour développer des chaînes courtes de déclenchement en extraits | |
3cacfa9e | 213 | de texte interactifs. Vous pouvez ajouter le répertoire des modèles dans la |
bf5c74e7 JL |
214 | variables @var{yas-snippet-dirs} d'Emacs. |
215 | ||
216 | @lisp | |
217 | ;; @r{Si l'extrait est dans ~/src/guix.} | |
218 | (with-eval-after-load 'yasnippet | |
219 | (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets")) | |
220 | @end lisp | |
221 | ||
adfb167f JL |
222 | Les extraits de messages de commit dépendent de @url{https://magit.vc/, |
223 | Magit} pour afficher les fichiers sélectionnés. Lors de la modification | |
224 | d'un message de commit, tapez @code{add} suivi de @kbd{TAB} pour insérer un | |
225 | modèle de message de commit pour ajouter un paquet ; tapez @code{update} | |
226 | suivi de @kbd{TAB} pour insérer un modèle pour la mise à jour d'un paquet ; | |
227 | tapez @code{https} suivi de @kbd{TAB} pour insérer un modèle pour le | |
228 | changement à HTTPS de l'URI de la page d'accueil. | |
bf5c74e7 JL |
229 | |
230 | L'extrait principal pour @code{scheme-mode} est lancé en tapant | |
3cacfa9e LC |
231 | @code{package…} suivi par @kbd{TAB}. Cet extrait insère aussi la chaîne de |
232 | déclenchement @code{origin…}, qui peut aussi être étendue. L'extrait | |
bf5c74e7 JL |
233 | @code{origin} lui-même peut aussi insérer des chaînes de déclenchement qui |
234 | finissent sur @code{…}, qui peuvent aussi être étendues. | |
235 | ||
236 | ||
15f1bff4 JL |
237 | @node Consignes d'empaquetage |
238 | @section Consignes d'empaquetage | |
239 | ||
240 | @cindex paquets, création | |
ad377c3d JL |
241 | La distribution GNU est jeune et vos paquets préférés peuvent manquer. |
242 | Cette section décrit comment vous pouvez aider à agrandir la distribution. | |
15f1bff4 JL |
243 | |
244 | Les paquets de logiciels libres sont habituellement distribués sous forme | |
245 | @dfn{d'archives de sources} — typiquement des fichiers @file{.tar.gz} | |
246 | contenant tous les fichiers sources. Ajouter un paquet à la distribution | |
247 | signifie essentiellement deux choses : ajouter une @dfn{recette} qui décrit | |
248 | comment construire le paquet, avec une liste d'autres paquets requis pour le | |
249 | construire, et ajouter des @dfn{métadonnées de paquet} avec la recette, | |
250 | comme une description et une licence. | |
251 | ||
252 | Dans Guix, toutes ces informations sont incorporées dans les | |
253 | @dfn{définitions de paquets}. Les définitions de paquets fournissent une | |
254 | vue de haut-niveau du paquet. Elles sont écrites avec la syntaxe du langage | |
255 | de programmation Scheme ; en fait, pour chaque paquet nous définissons une | |
256 | variable liée à la définition et exportons cette variable à partir d'un | |
257 | module (@pxref{Modules de paquets}). Cependant, il n'est @emph{pas} nécessaire | |
258 | d'avoir une connaissance approfondie du Scheme pour créer des paquets. Pour | |
259 | plus d'informations sur les définitions des paquets, @pxref{Définition des paquets}. | |
260 | ||
261 | Une fois une définition de paquet en place, stocké dans un fichier de | |
262 | l'arborescence des sources de Guix, il peut être testé avec la commande | |
263 | @command{guix build} (@pxref{Invoquer guix build}). Par exemple, en | |
264 | supposant que le nouveau paquet s'appelle @code{gnew}, vous pouvez lancer | |
265 | cette commande depuis l'arborescence de construction de Guix (@pxref{Lancer Guix avant qu'il ne soit installé}) : | |
266 | ||
267 | @example | |
268 | ./pre-inst-env guix build gnew --keep-failed | |
269 | @end example | |
270 | ||
271 | Utiliser @code{--keep-failed} rend facile le débogage des échecs car il | |
272 | fournit l'accès à l'arborescence de construction qui a échouée. Une autre | |
273 | sous-commande utile pour le débogage est @code{--log-file}, pour accéder au | |
274 | journal de construction. | |
275 | ||
276 | Si le paquet n'est pas connu de la commande @command{guix}, il se peut que | |
277 | le fichier source ait une erreur de syntaxe, ou qu'il manque une clause | |
278 | @code{define-public} pour exporter la variable du paquet. Pour comprendre | |
279 | cela, vous pouvez charger le module depuis Guile pour avoir plus | |
280 | d'informations sur la véritable erreur : | |
281 | ||
282 | @example | |
283 | ./pre-inst-env guile -c '(use-modules (gnu packages gnew))' | |
284 | @end example | |
285 | ||
ad377c3d JL |
286 | Une fois que votre paquet est correctement construit, envoyez-nous un |
287 | correctif (@pxref{Contribuer}). Enfin, si vous avez besoin d'aide, nous | |
288 | serrons ravis de vous aider. Une fois que le correctif soumis est committé | |
289 | dans le dépôt Guix, le nouveau paquet est automatiquement construit sur les | |
290 | plate-formes supportées par @url{http://hydra.gnu.org/jobset/gnu/master, | |
291 | notre système d'intégration continue}. | |
15f1bff4 JL |
292 | |
293 | @cindex substitution | |
ad377c3d JL |
294 | On peut obtenir la nouvelle définition du paquet simplement en lançant |
295 | @command{guix pull} (@pxref{Invoquer guix pull}). Lorsque | |
296 | @code{@value{SUBSTITUTE-SERVER}} a fini de construire le paquet, | |
297 | l'installation du paquet y télécharge automatiquement les binaires | |
298 | (@pxref{Substituts}). La seule intervention humaine requise est pendant la | |
299 | revue et l'application du correctif. | |
15f1bff4 JL |
300 | |
301 | ||
302 | @menu | |
303 | * Liberté logiciel:: Ce que la distribution peut contenir. | |
304 | * Conventions de nommage:: Qu'est-ce qu'un bon nom ? | |
305 | * Numéros de version:: Lorsque le nom n'est pas suffisant. | |
306 | * Synopsis et descriptions:: Aider les utilisateurs à trouver le bon | |
307 | paquet. | |
308 | * Modules python:: Un peu de comédie anglaise. | |
309 | * Modules perl:: Petites perles. | |
310 | * Paquets java:: Pause café. | |
311 | * Polices de caractères:: À fond les fontes. | |
312 | @end menu | |
313 | ||
314 | @node Liberté logiciel | |
315 | @subsection Liberté logiciel | |
316 | ||
317 | @c =========================================================================== | |
318 | @c | |
319 | @c This file was generated with po4a. Translate the source file. | |
320 | @c | |
321 | @c =========================================================================== | |
322 | @c Adapted from http://www.gnu.org/philosophy/philosophy.html. | |
323 | @cindex logiciel libre | |
324 | Le système d'exploitation GNU a été développé pour que les utilisateurs | |
325 | puissent utiliser leur ordinateur en toute liberté. GNU est un | |
326 | @dfn{logiciel libre}, ce qui signifie que les utilisateur ont les | |
327 | @url{http://www.gnu.org/philosophy/free-sw.fr.html,quatre libertés | |
328 | essentielles} : exécuter le programmer, étudier et modifier le programme | |
329 | sous sa forme source, redistribuer des copies exactes et distribuer les | |
330 | versions modifiées. Les paquets qui se trouvent dans la distribution GNU ne | |
331 | fournissent que des logiciels qui respectent ces quatre libertés. | |
332 | ||
333 | En plus, la distribution GNU suit les | |
334 | @url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,recommandations | |
335 | pour les distributions systèmes libres}. Entre autres choses, ces | |
336 | recommandations rejettent les microgiciels non libres, les recommandations | |
337 | de logiciels non libres et discute des façon de gérer les marques et les | |
338 | brevets. | |
339 | ||
340 | Certaines sources amont autrement parfaitement libres contiennent une petite | |
341 | partie facultative qui viole les recommandations ci-dessus, par exemple car | |
342 | cette partie est du code non-libre. Lorsque cela arrive, les éléments en | |
343 | question sont supprimés avec des correctifs ou des bouts de codes appropriés | |
344 | dans la forme @code{origin} du paquet (@pxref{Définition des paquets}). De cette | |
345 | manière, @code{guix build --source} renvoie la source « libérée » plutôt que | |
346 | la source amont sans modification. | |
347 | ||
348 | ||
349 | @node Conventions de nommage | |
350 | @subsection Conventions de nommage | |
351 | ||
352 | @cindex nom du paquet | |
353 | Un paquet a en fait deux noms qui lui sont associés : d'abord il y a le nom | |
354 | de la @emph{variable Scheme}, celui qui suit @code{define-public}. Par ce | |
355 | nom, le paquet peut se faire connaître par le code Scheme, par exemple comme | |
356 | entrée d'un autre paquet. Deuxièmement, il y a la chaîne dans le champ | |
357 | @code{name} d'une définition de paquet. Ce nom est utilisé par les | |
358 | commandes de gestion des paquets comme @command{guix package} et | |
359 | @command{guix build}. | |
360 | ||
361 | Les deux sont habituellement les mêmes et correspondent à la conversion en | |
362 | minuscule du nom du projet choisi en amont, où les underscores sont | |
363 | remplacés par des tirets. Par exemple, GNUnet est disponible en tant que | |
364 | @code{gnunet} et SDL_net en tant que @code{sdl-net}. | |
365 | ||
366 | Nous n'ajoutons pas de préfixe @code{lib} au bibliothèques de paquets, à | |
367 | 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 | |
368 | modules pour les langages Python et Perl. | |
369 | ||
370 | Les noms de paquets de polices sont gérés différemment, @pxref{Polices de caractères}. | |
371 | ||
372 | ||
373 | @node Numéros de version | |
374 | @subsection Numéros de version | |
375 | ||
376 | @cindex version du paquet | |
377 | Nous n'incluons en général que la dernière version d'un projet de logiciel | |
378 | libre donné. Mais parfois, par exemple pour des versions incompatibles de | |
379 | bibliothèques, deux (ou plus) versions du même paquet sont requises. Elles | |
380 | ont besoin d'un nom de variable Scheme différent. Nous utilisons le nom | |
381 | défini dans @ref{Conventions de nommage} pour la version la plus récente ; les | |
382 | versions précédentes utilisent le même nom, suffixé par @code{-} et le plus | |
383 | petit préfixe du numéro de version qui permet de distinguer deux versions. | |
384 | ||
385 | Le nom dans la définition du paquet est le même pour toutes les versions | |
386 | d'un paquet et ne contient pas de numéro de version. | |
387 | ||
388 | Par exemple, les version 2.24.20 et 3.9.12 de GTK+ peuvent être inclus de | |
389 | cette manière : | |
390 | ||
391 | @example | |
392 | (define-public gtk+ | |
393 | (package | |
394 | (name "gtk+") | |
395 | (version "3.9.12") | |
396 | ...)) | |
397 | (define-public gtk+-2 | |
398 | (package | |
399 | (name "gtk+") | |
400 | (version "2.24.20") | |
401 | ...)) | |
402 | @end example | |
403 | Si nous voulons aussi GTK+ 3.8.2, cela serait inclus de cette manière : | |
404 | @example | |
405 | (define-public gtk+-3.8 | |
406 | (package | |
407 | (name "gtk+") | |
408 | (version "3.8.2") | |
409 | ...)) | |
410 | @end example | |
411 | ||
412 | @c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>, | |
413 | @c for a discussion of what follows. | |
414 | @cindex numéro de version, pour les instantanés des systèmes de contrôle de version | |
415 | Parfois, nous incluons des paquets provenant d'instantanés de systèmes de | |
416 | contrôle de version (VCS) au lieu de versions publiées formellement. Cela | |
417 | devrait rester exceptionnel, car c'est le rôle des développeurs amont de | |
418 | spécifier quel est la version stable. Cependant, c'est parfois nécessaire. | |
419 | Donc, que faut-il mettre dans le champ @code{version} ? | |
420 | ||
421 | Clairement, nous devons rendre l'identifiant de commit de l'instantané du | |
422 | VCS visible dans la version, mais nous devons aussi nous assurer que la | |
423 | version augmente de manière monotone pour que @command{guix package | |
424 | --upgrade} puisse déterminer quelle version est la plus récente. Comme les | |
425 | identifiants de commits, notamment avec Git, n'augmentent pas, nous ajoutons | |
426 | un numéro de révision qui nous augmentons à chaque fois que nous mettons à | |
427 | jour vers un nouvel instantané. La chaîne qui en résulte ressemble à cela : | |
428 | ||
429 | @example | |
430 | 2.0.11-3.cabba9e | |
431 | ^ ^ ^ | |
432 | | | `-- ID du commit en amont | |
433 | | | | |
434 | | `--- révision du paquet Guix | |
435 | | | |
436 | dernière version en amont | |
437 | @end example | |
438 | ||
439 | C'est une bonne idée de tronquer les identifiants dans le champ | |
440 | @code{version} à disons 7 caractères. Cela évite un problème esthétique (en | |
441 | supposant que l'esthétique ait un rôle à jouer ici) et des problèmes avec | |
442 | les limites de l'OS comme la longueur maximale d'un shebang (127 octets pour | |
443 | le noyau Linux). Il vaut mieux utilise l'identifiant de commit complet dans | |
444 | @code{origin} cependant, pour éviter les ambiguïtés. Une définition de | |
445 | paquet peut ressembler à ceci : | |
446 | ||
447 | @example | |
448 | (define my-package | |
449 | (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7") | |
450 | (revision "1")) ;révision du paquet Guix | |
451 | (package | |
452 | (version (git-version "0.9" revision commit)) | |
453 | (source (origin | |
454 | (method git-fetch) | |
455 | (uri (git-reference | |
456 | (url "git://example.org/my-package.git") | |
457 | (commit commit))) | |
458 | (sha256 (base32 "1mbikn@dots{}")) | |
459 | (file-name (git-file-name name version)))) | |
460 | ;; @dots{} | |
461 | ))) | |
462 | @end example | |
463 | ||
464 | @node Synopsis et descriptions | |
465 | @subsection Synopsis et descriptions | |
466 | ||
467 | @cindex description du paquet | |
468 | @cindex résumé du paquet | |
469 | Comme nous l'avons vu avant, chaque paquet dans GNU@tie{}Guix contient un | |
470 | résumé et une description (@pxref{Définition des paquets}). Les résumés et les | |
471 | descriptions sont importants : ce sont eux que recherche @command{guix | |
472 | package --search}, et c'est une source d'informations cruciale pour aider | |
473 | les utilisateurs à déterminer si un paquet donner correspond à leurs | |
474 | besoins. En conséquence, les mainteneurs doivent prêter attention à leur | |
475 | contenu. | |
476 | ||
477 | Les résumés doivent commencer par une lettre capitale et ne doit pas finir | |
478 | par un point. Ils ne doivent pas commencer par « a » ou « the » (« un » ou | |
479 | « le/la »), ce qui n'apporte généralement rien ; par exemple, préférez « | |
480 | File-frobbing tool » (« Outil de frobage de fichier ») à « A tool that frobs | |
481 | file » (« Un outil qui frobe les fichiers »). Le résumé devrait dire ce que | |
482 | le paquet est — p.@: ex.@: « Utilitaire du cœur de GNU (fichier, text, | |
483 | shell) » — ou ce à quoi il sert — p.@: ex.@: le résumé de grep est « Affiche | |
484 | des lignes correspondant à un motif ». | |
485 | ||
486 | Gardez à l'esprit que le résumé doit avoir un sens pour une large audience. | |
487 | Par exemple « Manipulation d'alignements au format SAM » peut avoir du sens | |
488 | pour un bioinformaticien chevronné, mais n'aidera pas ou pourra perdre une | |
489 | audience de non-spécialistes. C'est une bonne idée de créer un résumé qui | |
490 | donne une idée du domaine d'application du paquet. Dans cet exemple, cela | |
491 | donnerait « Manipulation d'alignements de séquences de nucléotides », ce qui | |
492 | devrait donner une meilleure idée à l'utilisateur pour savoir si c'est ce | |
493 | qu'il recherche. | |
494 | ||
495 | Les descriptions devraient faire entre cinq et dix lignes. Utilisez des | |
496 | phrases complètes, et évitez d'utiliser des acronymes sans les introduire | |
497 | d'abord. Évitez les phrases marketings comme « world-leading », « | |
498 | industrial-strength » et « next-generation » et évitez les superlatifs comme | |
499 | « the most advanced » — ils ne sont pas utiles pour les utilisateurs qui | |
500 | cherchent un paquet et semblent même un peu suspects. À la place, essayez | |
501 | d'être factuels, en mentionnant les cas d'utilisation et les | |
502 | fonctionnalités. | |
503 | ||
504 | @cindex balisage texinfo, dans les descriptions de paquets | |
505 | Les descriptions peuvent inclure du balisage Texinfo, ce qui est utile pour | |
506 | introduire des ornements comme @code{@@code} ou @code{@@dfn}, des listes à | |
507 | points ou des hyperliens (@pxref{Overview,,, texinfo, GNU Texinfo}). | |
508 | Cependant soyez prudents lorsque vous utilisez certains symboles, par | |
509 | exemple @samp{@@} et les accolades qui sont les caractères spéciaux de base | |
510 | en Texinfo (@pxref{Special Characters,,, texinfo, GNU Texinfo}). Les | |
511 | interfaces utilisateurs comme @command{guix package --show} prennent en | |
512 | charge le rendu. | |
513 | ||
514 | Les résumés et les descriptions sont traduits par des volontaires | |
515 | @uref{http://translationproject.org/domain/guix-packages.html, sur le projet | |
516 | de traduction} pour que le plus d'utilisateurs possible puissent les lire | |
517 | dans leur langue natale. Les interfaces utilisateurs les recherchent et les | |
518 | affichent dans la langue spécifiée par le paramètre de régionalisation | |
519 | actuel. | |
520 | ||
521 | Pour permettre à @command{xgettext} de les extraire comme des chaînes | |
522 | traduisibles, les résumés et les descriptions @emph{doivent être des chaînes | |
523 | litérales}. Cela signifie que vous ne pouvez pas utiliser | |
524 | @code{string-append} ou @code{format} pour construire ces chaînes : | |
525 | ||
526 | @lisp | |
527 | (package | |
528 | ;; @dots{} | |
529 | (synopsis "Ceci est traduisible") | |
530 | (description (string-append "Ceci n'est " "*pas*" " traduisible."))) | |
531 | @end lisp | |
532 | ||
533 | La traduction demande beaucoup de travail, donc en tant que packageur, | |
534 | faîtes encore plus attention à vos résumés et descriptions car chaque | |
535 | changement peut demander d'autant plus de travail de la part des | |
536 | traducteurs. Pour les aider, il est possible de donner des recommandations | |
537 | ou des instructions qu'ils pourront voir en insérant des commentaires | |
538 | spéciaux comme ceci (@pxref{xgettext Invocation,,, gettext, GNU Gettext}) : | |
539 | ||
540 | @example | |
541 | ;; TRANSLATORS: "X11 resize-and-rotate" should not be translated. | |
542 | (description "ARandR is designed to provide a simple visual front end | |
543 | for the X11 resize-and-rotate (RandR) extension. @dots{}") | |
544 | @end example | |
545 | ||
546 | ||
547 | @node Modules python | |
548 | @subsection Modules python | |
549 | ||
550 | @cindex python | |
551 | Nous incluons actuellement Python 2 et Python 3, sous les noms de variables | |
552 | 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 | |
553 | langages de programmation, il semble désirable que le nom d'un paquet pour | |
554 | un module Python contienne le mot @code{python}. | |
555 | ||
556 | Certains modules ne sont compatibles qu'avec une version de Python, d'autres | |
557 | avec les deux. Si le paquet Foo ne compile qu'avec Ptyhon 3, on le nomme | |
558 | @code{python-foo} ; s'il ne compile qu'avec Python 2, on le nome | |
559 | @code{python2-foo}. S'il est compatible avec les deux versions, nous créons | |
560 | deux paquets avec les noms correspondant. | |
561 | ||
ad377c3d JL |
562 | Si un projet contient déjà le mot @code{python}, on l'enlève, par exemple le |
563 | module python-dateutil est packagé sous les noms @code{python-dateutil} et | |
564 | @code{python2-dateutil}. Si le nom du projet commence par @code{py} (p.@: | |
565 | ex.@: @code{pytz}), on le garde et on le préfixe comme décrit ci-dessus. | |
15f1bff4 JL |
566 | |
567 | @subsubsection Spécifier les dépendances | |
568 | @cindex entrées, pour les paquets Python | |
569 | ||
570 | Les informations de dépendances pour les paquets Python se trouvent | |
571 | généralement dans l'arborescence des source du paquet, avec plus ou moins de | |
572 | précision : dans le fichier @file{setup.py}, dans @file{requirements.txt} ou | |
573 | dans @file{tox.ini}. | |
574 | ||
575 | Votre mission, lorsque vous écrivez une recette pour un paquet Python, est | |
576 | de faire correspondre ces dépendances au bon type « d'entrée » | |
ad377c3d | 577 | (@pxref{Référence des paquets, inputs}). Bien que l'importeur @code{pypi} fasse |
15f1bff4 JL |
578 | du bon boulot (@pxref{Invoquer guix import}), vous devriez vérifier la liste |
579 | suivant pour déterminer où va telle dépendance. | |
580 | ||
581 | @itemize | |
582 | ||
583 | @item | |
584 | Nous empaquetons Python 2 avec @code{setuptools} et @code{pip} installé | |
585 | comme Python 3.4 par défaut. Ainsi, vous n'avez pas à spécifié ces | |
586 | entrées. @command{guix lint} vous avertira si vous faîtes cela. | |
587 | ||
588 | @item | |
589 | Les dépendances Python requises à l'exécutions vont dans | |
590 | @code{propagated-inputs}. Elles sont typiquement définies dans le mot-clef | |
591 | @code{install_requires} dans @file{setup.py} ou dans le fichier | |
592 | @file{requirements.txt}. | |
593 | ||
594 | @item | |
595 | Les paquets Python requis uniquement à la construction — p.@: ex.@: ceux | |
596 | listés dans le mot-clef @code{setup_requires} de @file{setup.py} — ou | |
597 | seulement pour les tests — p.@: ex.@: ceux dans @code{tests_require} — vont | |
598 | dans @code{native-inputs}. La raison est qu'ils n'ont pas besoin d'être | |
599 | propagés car ils ne sont pas requis à l'exécution et dans le cas d'une | |
600 | compilation croisée, c'est l'entrée « native » qu'il nous faut. | |
601 | ||
602 | Les cadriciels de tests @code{pytest}, @code{mock} et @code{nose} sont des | |
603 | exemples. Bien sûr si l'un de ces paquets est aussi requis à l'exécution, | |
604 | il doit aller dans @code{propagated-inputs}. | |
605 | ||
606 | @item | |
607 | Tout ce qui ne tombe pas dans les catégories précédentes va dans | |
608 | @code{inputs}, par exemple des programmes pour des bibliothèques C requises | |
609 | pour construire des paquets Python avec des extensions C. | |
610 | ||
611 | @item | |
612 | Si un paquet Python a des dépendances facultatives (@code{extras_require}), | |
613 | c'est à vous de décider de les ajouter ou non, en fonction du ratio entre | |
614 | utilité et complexité (@pxref{Envoyer des correctifs, @command{guix size}}). | |
615 | ||
616 | @end itemize | |
617 | ||
618 | ||
619 | @node Modules perl | |
620 | @subsection Modules perl | |
621 | ||
622 | @cindex perl | |
623 | Les programmes Perl utiles en soit sont nommés comme les autres paquets, | |
624 | avec le nom amont en minuscule. Pour les paquets Perl contenant une seule | |
625 | classe, nous utilisons le nom de la classe en minuscule, en remplaçant les | |
626 | occurrences de @code{::} par des tirets et en préfixant le tout par | |
627 | @code{perl-}. Donc la classe @code{XML::Parser} devient | |
628 | @code{perl-xml-parser}. Les modules contenant plusieurs classes gardent | |
629 | leur nom amont en minuscule et sont aussi préfixés par @code{perl-}. Ces | |
630 | modules tendent à avoir le mot @code{perl} quelque part dans leur nom, que | |
631 | nous supprimons en faveur du préfixe. Par exemple, @code{libwww-perl} | |
632 | devient @code{perl-libwww}. | |
633 | ||
634 | ||
635 | @node Paquets java | |
636 | @subsection Paquets java | |
637 | ||
638 | @cindex java | |
639 | Le programmes Java utiles en soit sont nommés comme les autres paquets, avec | |
640 | le nom amont en minuscule. | |
641 | ||
642 | Pour éviter les confusions et les problèmes de nom avec d'autres langages de | |
643 | programmation, il est désirable que le nom d'un paquet Java soit préfixé par | |
644 | @code{java-}. Si un projet contient déjà le mot @code{java}, nous le | |
645 | supprimons, par exemple le paquet @code{ngsjava} est empaqueté sous le nom | |
646 | @code{java-ngs}. | |
647 | ||
648 | Pour les paquets java contenant une seul classe ou une petite hiérarchie de | |
649 | classes, nous utilisons le nom de la classe en minuscule, en remplaçant les | |
650 | occurrences de @code{.} par des tirets et en préfixant le tout par | |
651 | @code{java-}. Donc la classe @code{apache.commons.cli} devient | |
652 | @code{java-apache-commons-cli}. | |
653 | ||
654 | ||
655 | @node Polices de caractères | |
656 | @subsection Polices de caractères | |
657 | ||
658 | @cindex polices | |
659 | Pour les polices qui n esont en général par installées par un utilisateurs | |
660 | pour du traitement de texte, ou qui sont distribuées en tant que partie d'un | |
661 | paquet logiciel plus gros, nous nous appuyons sur les règles générales pour | |
662 | les logiciels ; par exemple, cela s'applique aux polices livrées avec le | |
663 | système X.Org ou les polices qui font partie de TeX Live. | |
664 | ||
665 | Pour rendre plus facile la recherche par l'utilisateur, les noms des autres | |
666 | paquets contenant seulement des polices sont construits ainsi, | |
667 | indépendamment du nom du paquet en amont. | |
668 | ||
669 | Le nom d'un paquet contenant une unique famille de polices commence par | |
670 | @code{font-} ; il est suivi du nom du fondeur et d'un tiret @code{-} si le | |
671 | fondeur est connu, et du nom de la police, dont les espaces sont remplacés | |
672 | par des tirets (et comme d'habitude, toutes les lettres majuscules sont | |
673 | transformées en minuscules). Par exemple, la famille de polices Gentium de | |
674 | SIL est empaqueté sous le nom @code{font-sil-gentium}. | |
675 | ||
676 | Pour un paquet contenant plusieurs familles de polices, le nom de la | |
677 | collection est utilisée à la place du nom de la famille. Par exemple les | |
678 | polices Liberation consistent en trois familles, Liberation Sans, Liberation | |
679 | Serif et Liberation Mono. Elles pourraient être empaquetées séparément sous | |
680 | les noms @code{font-liberation-sans} etc, mais comme elles sont distribuées | |
681 | ensemble sous un nom commun, nous préférons les empaqueter ensemble en tant | |
682 | que @code{font-liberation}. | |
683 | ||
684 | Dans le cas où plusieurs formats de la même famille ou collection sont | |
685 | empaquetés séparément, une forme courte du format, préfixé d'un tiret est | |
686 | ajouté au nom du paquet. Nous utilisont @code{-ttf} pour les polices | |
687 | TrueType, @code{-otf} pour les polices OpenType et @code{-type1} pour les | |
688 | polices Type 1 de PostScript. | |
689 | ||
690 | ||
bf5c74e7 JL |
691 | @node Style de code |
692 | @section Style de code | |
693 | ||
694 | En général notre code suit le Standard de Code GNU (@pxref{Top,,, standards, | |
3cacfa9e | 695 | GNU Coding Standards}). Cependant, il ne parle pas beaucoup de Scheme, donc |
bf5c74e7 JL |
696 | voici quelques règles supplémentaires. |
697 | ||
698 | @menu | |
699 | * Paradigme de programmation:: Comment composer vos éléments. | |
700 | * Modules:: Où stocker votre code ? | |
701 | * Types de données et reconnaissance de motif:: Implémenter des | |
702 | structures de données. | |
703 | * Formatage du code:: Conventions d'écriture. | |
704 | @end menu | |
705 | ||
706 | @node Paradigme de programmation | |
707 | @subsection Paradigme de programmation | |
708 | ||
3cacfa9e | 709 | Le code Scheme dans Guix est écrit dans un style purement fonctionnel. Le |
bf5c74e7 JL |
710 | code qui s'occupe des entrées-sorties est une exception ainsi que les |
711 | procédures qui implémentent des concepts bas-niveau comme la procédure | |
712 | @code{memoize}. | |
713 | ||
714 | @node Modules | |
715 | @subsection Modules | |
716 | ||
717 | Les modules Guile qui sont sensés être utilisés du côté de la construction | |
3cacfa9e LC |
718 | doivent se trouver dans l'espace de nom @code{(guix build @dots{})}. Ils ne |
719 | doivent pas se référer à d'autres modules Guix ou GNU@. Cependant il est | |
bf5c74e7 JL |
720 | correct pour un module « côté hôte » de dépendre d'un module coté |
721 | construction. | |
722 | ||
723 | Les modules qui s'occupent du système GNU général devraient se trouver dans | |
724 | l'espace de nom @code{(gnu @dots{})} plutôt que @code{(guix @dots{})}. | |
725 | ||
726 | @node Types de données et reconnaissance de motif | |
727 | @subsection Types de données et reconnaissance de motif | |
728 | ||
729 | La tendance en Lisp classique est d'utiliser des listes pour tout | |
730 | représenter et de naviguer dedans « à la main ( avec @code{car}, @code{cdr}, | |
3cacfa9e | 731 | @code{cadr} et compagnie. Il y a plusieurs problèmes avec ce style, |
bf5c74e7 JL |
732 | notamment le fait qu'il soit dur à lire, source d'erreur et un obstacle aux |
733 | rapports d'erreur bien typés. | |
734 | ||
735 | Le code de Guix devrait définir des types de données appropriées (par | |
3cacfa9e LC |
736 | exemple, avec @code{define-record-type*}) plutôt que d'abuser des listes. |
737 | En plus, il devrait utiliser la recherche de motifs, via le module Guile | |
bf5c74e7 JL |
738 | @code{(ice-9 match)}, surtout pour rechercher dans des listes. |
739 | ||
740 | @node Formatage du code | |
741 | @subsection Formatage du code | |
742 | ||
743 | @cindex formater le code | |
744 | @cindex style de code | |
745 | Lorsque nous écrivons du code Scheme, nous suivons la sagesse commune aux | |
3cacfa9e | 746 | programmeurs Scheme. En général, nous suivons les |
bf5c74e7 | 747 | @url{http://mumble.net/~campbell/scheme/style.txt, règles de style de |
3cacfa9e LC |
748 | Riastradh}. Ce document décrit aussi les conventions utilisées dans le code |
749 | de Guile. Il est bien pensé et bien écrit, alors n'hésitez pas à le lire. | |
bf5c74e7 JL |
750 | |
751 | Certaines formes spéciales introduites dans Guix comme la macro | |
3cacfa9e | 752 | @code{substitute*} ont des règles d'indentation spécifiques. Elles sont |
bf5c74e7 | 753 | définies dans le fichier @file{.dir-locals.el} qu'Emacs utilise |
3cacfa9e | 754 | automatiquement. Remarquez aussi qu'Emacs-Guix fournit le mode |
bf5c74e7 | 755 | @code{guix-devel-mode} qui indente et colore le code Guix correctement |
ad377c3d | 756 | (@pxref{Développement,,, emacs-guix, The Emacs-Guix Reference Manual}). |
bf5c74e7 JL |
757 | |
758 | @cindex indentation, du code | |
759 | @cindex formatage, du code | |
760 | Si vous n'utilisez pas Emacs, assurez-vous que votre éditeur connaisse ces | |
3cacfa9e | 761 | règles. Pour indenter automatiquement une définition de paquet, vous pouvez |
bf5c74e7 JL |
762 | aussi lancer : |
763 | ||
764 | @example | |
765 | ./etc/indent-code.el gnu/packages/@var{file}.scm @var{package} | |
766 | @end example | |
767 | ||
768 | @noindent | |
769 | Cela indente automatiquement la définition de @var{package} dans | |
3cacfa9e | 770 | @file{gnu/packages/@var{file}.scm} en lançant Emacs en mode commande. Pour |
bf5c74e7 JL |
771 | indenter un fichier complet, n'indiquez pas de second argument : |
772 | ||
773 | @example | |
774 | ./etc/indent-code.el gnu/services/@var{file}.scm | |
775 | @end example | |
776 | ||
3cacfa9e LC |
777 | @cindex Vim, édition de code Scheme |
778 | Si vous éditez du code avec Vim, nous recommandons de lancer @code{:set | |
779 | autoindent} pour que votre code soit automatiquement indenté au moment où | |
780 | vous l'entrez. En plus, | |
781 | @uref{https://www.vim.org/scripts/script.php?script_id=3998, | |
782 | @code{paredit.vim}} peut vous aider à gérer toutes ces parenthèses. | |
783 | ||
bf5c74e7 | 784 | Nous demandons que toutes les procédure de premier niveau contiennent une |
15f1bff4 JL |
785 | chaîne de documentation. Ce prérequis peut être relâché pour les procédures |
786 | privées simples dans l'espace de nom @code{(guix build @dots{})} cependant. | |
bf5c74e7 JL |
787 | |
788 | Les procédures ne devraient pas avoir plus de quatre paramètres | |
789 | positionnés. Utilisez des paramètres par mot-clefs pour les procédures qui | |
790 | prennent plus de quatre paramètres. | |
791 | ||
792 | ||
793 | @node Envoyer des correctifs | |
794 | @section Envoyer des correctifs | |
795 | ||
3cacfa9e LC |
796 | Le développement se fait avec le système de contrôle de version Git. Ainsi, |
797 | l'accès au dépôt n'est pas strictement nécessaire. Nous accueillons les | |
bf5c74e7 JL |
798 | contributions sous forme de correctifs produits par @code{git format-patch} |
799 | envoyés sur la liste de diffusion @email{guix-patches@@gnu.org}. | |
800 | ||
801 | Cette liste de diffusion est gérée par une instance Debbugs accessible à | |
802 | l'adresse @uref{https://bugs.gnu.org/guix-patches}, qui nous permet de | |
3cacfa9e | 803 | suivre les soumissions. Chaque message envoyé à cette liste se voit |
bf5c74e7 JL |
804 | attribuer un numéro de suivi ; les gens peuvent ensuite répondre à cette |
805 | soumission en envoyant un courriel à @code{@var{NNN}@@debbugs.gnu.org}, où | |
806 | @var{NNN} est le numéro de suivi (@pxref{Envoyer une série de correctifs}). | |
807 | ||
808 | Veuillez écrire les messages de commit dans le format ChangeLog | |
809 | (@pxref{Change Logs,,, standards, GNU Coding Standards}) ; vous pouvez | |
810 | regarder l'historique des commits pour trouver des exemples. | |
811 | ||
812 | Avant de soumettre un correctif qui ajoute ou modifie la définition d'un | |
813 | paquet, veuillez vérifier cette check-list : | |
814 | ||
815 | @enumerate | |
816 | @item | |
817 | Si les auteurs du paquet logiciel fournissent une signature cryptographique | |
3cacfa9e LC |
818 | pour l'archive, faîtes un effort pour vérifier l'authenticité de l'archive. |
819 | Pour un fichier de signature GPG détaché, cela se fait avec la commande | |
820 | @code{gpg --verify}. | |
bf5c74e7 JL |
821 | |
822 | @item | |
823 | Prenez un peu de temps pour fournir un synopsis et une description adéquats | |
3cacfa9e | 824 | pour le paquet. Voir @xref{Synopsis et descriptions} pour quelques lignes |
bf5c74e7 JL |
825 | directrices. |
826 | ||
827 | @item | |
828 | Lancez @code{guix lint @var{paquet}}, où @var{paquet} est le nom du nouveau | |
829 | paquet ou du paquet modifié, et corrigez les erreurs qu'il rapporte | |
830 | (@pxref{Invoquer guix lint}). | |
831 | ||
832 | @item | |
833 | Assurez-vous que le paquet se construise sur votre plate-forme avec | |
834 | @code{guix build @var{paquet}}. | |
835 | ||
15f1bff4 | 836 | @item |
ad377c3d JL |
837 | Nous vous recommandons aussi d'essayer de construire le paquet sur les |
838 | autres plate-formes prises en charge. Comme vous n'avez pas forcément accès | |
839 | aux plate-formes matérielles, nous vous recommandons d'utiliser le | |
840 | @code{qemu-binfmt-service-type} pour les émuler. Pour cela, ajoutez le | |
841 | service suivant à la liste des services dans votre configuration de système | |
842 | d'exploitation : | |
15f1bff4 JL |
843 | |
844 | @example | |
845 | (service qemu-binfmt-service-type | |
846 | (qemu-binfmt-configuration | |
ad377c3d | 847 | (platforms (lookup-qemu-platforms "arm" "aarch64" "mips64el")) |
15f1bff4 JL |
848 | (guix-support? #t))) |
849 | @end example | |
850 | ||
ad377c3d | 851 | Puis reconfigurez votre système. |
15f1bff4 | 852 | |
ad377c3d JL |
853 | Vous pourrez ensuite construire les paquets pour différentes plate-formes en |
854 | spécifiant l'option @code{--system}. Par exemple pour construire le paquet | |
855 | « hello » pour les architectures armhf, aarch64 ou mips64, vous devrez | |
856 | lancer les commandes suivantes, respectivement : | |
15f1bff4 JL |
857 | @example |
858 | guix build --system=armhf-linux --rounds=2 hello | |
859 | guix build --system=aarch64-linux --rounds=2 hello | |
15f1bff4 JL |
860 | guix build --system=mips64el-linux --rounds=2 hello |
861 | @end example | |
862 | ||
bf5c74e7 JL |
863 | @item |
864 | @cindex construction groupée | |
865 | Assurez-vous que le paquet n'utilise pas de copie groupée d'un logiciel déjà | |
866 | disponible dans un paquet séparé. | |
867 | ||
868 | Parfois, les paquets incluent des copie du code source de leurs dépendances | |
3cacfa9e | 869 | pour le confort de leurs utilisateurs. Cependant, en tant que distribution, |
bf5c74e7 | 870 | nous voulons nous assurer que ces paquets utilisent bien les copient que |
3cacfa9e | 871 | nous avons déjà dans la distribution si elles existent. Cela améliore |
bf5c74e7 JL |
872 | l'utilisation des ressources (la dépendance n'est construite et stockée |
873 | qu'une seule fois) et permet à la distribution de faire des changements | |
874 | transversaux comme appliquer des correctifs de sécurité pour un paquet donné | |
875 | depuis un unique emplacement et qu'ils affectent tout le système, ce | |
876 | qu'empêchent les copies groupées. | |
877 | ||
878 | @item | |
ad377c3d JL |
879 | Regardez le profil rapporté par @command{guix size} (@pxref{Invoquer guix size}). Cela vous permettra de remarquer des références à d'autres paquets |
880 | qui ont été retenus sans que vous vous y attendiez. Il peut aussi aider à | |
881 | déterminer s'il faut découper le paquet (@pxref{Des paquets avec plusieurs | |
882 | résultats}) et quelles dépendances facultatives utiliser. En particulier, | |
883 | évitez d'ajouter @code{texlive} en dépendance : à cause de sa taille | |
884 | extrême, utilisez @code{texlive-tiny} ou @code{texlive-union} à la place. | |
bf5c74e7 JL |
885 | |
886 | @item | |
887 | Pour les changements important, vérifiez que les paquets qui en dépendent | |
888 | (s'ils existent) ne sont pas affectés par le changement ; @code{guix refresh | |
889 | --list-dependant @var{paquet}} vous aidera (@pxref{Invoquer guix refresh}). | |
890 | ||
bf5c74e7 JL |
891 | @c See <https://lists.gnu.org/archive/html/guix-devel/2016-10/msg00933.html>. |
892 | @cindex stratégie de branche | |
893 | @cindex stratégie de planification des reconstructions | |
894 | Suivant le nombre de paquets dépendants et donc le nombre de reconstruction | |
895 | induites, les commits vont vers des branches différentes, suivant ces | |
896 | principes : | |
897 | ||
898 | @table @asis | |
899 | @item 300 paquets dépendants ou moins | |
900 | branche @code{master} (changements non-disruptifs). | |
901 | ||
902 | @item entre 300 et 1 200 paquets dépendants | |
15f1bff4 | 903 | branche @code{staging} (changements non-disruptifs). Cette branche devrait |
3cacfa9e | 904 | être fusionnées dans @code{master} tous les 3 semaines. Les changements par |
bf5c74e7 JL |
905 | thèmes (par exemple une mise à jour de la pile GNOME) peuvent aller dans une |
906 | branche spécifique (disons, @code{gnome-updates}). | |
907 | ||
908 | @item plus de 1 200 paquets dépendants | |
909 | branche @code{core-updates} (peut inclure des changements majeurs et | |
3cacfa9e | 910 | potentiellement disruptifs). Cette branche devrait être fusionnée dans |
bf5c74e7 JL |
911 | @code{master} tous les 2,5 mois environ. |
912 | @end table | |
913 | ||
2cf2c778 JL |
914 | Toutes ces branches sont @uref{https://hydra.gnu.org/project/gnu, gérées par |
915 | notre ferme de construction} et fusionnées dans @code{master} une fois que | |
916 | tout a été construit correctement. Cela nous permet de corriger des | |
917 | problèmes avant qu'ils n'atteignent les utilisateurs et réduit la fenêtre | |
918 | pendant laquelle les binaires pré-construits ne sont pas disponibles. | |
919 | ||
920 | @c TODO: It would be good with badges on the website that tracks these | |
921 | @c branches. Or maybe even a status page. | |
922 | Généralement les autres branches que @code{master} sont considérées comme | |
923 | @emph{gelées} s'il y a eu une évaluation récente ou qu'il y a une branche | |
924 | @code{-next} correspondante. Demandez sur la liste de diffusion ou sur IRC | |
925 | si vous n'êtes pas sûr de savoir où pousser votre correctif. | |
bf5c74e7 JL |
926 | |
927 | @item | |
928 | @cindex déterminisme, du processus de construction | |
929 | @cindex construction reproductibles, vérification | |
3cacfa9e | 930 | Vérifiez si le processus de construction du paquet est déterministe. Cela |
bf5c74e7 JL |
931 | signifie typiquement vérifier qu'une construction indépendante du paquet |
932 | renvoie exactement le même résultat que vous avez obtenu, bit à bit. | |
933 | ||
934 | Une manière simple de le faire est de reconstruire le paquet plusieurs fois | |
935 | à la suite sur votre machine (@pxref{Invoquer guix build}) : | |
936 | ||
937 | @example | |
938 | guix build --rounds=2 mon-paquet | |
939 | @end example | |
940 | ||
941 | Cela est suffisant pour trouver une classe de non-déterminisme commune, | |
942 | comme l'horodatage ou des sorties générées aléatoirement dans le résultat de | |
943 | la construction. | |
944 | ||
ad377c3d JL |
945 | Une autre option consiste à utiliser @command{guix challenge} |
946 | (@pxref{Invoquer guix challenge}). Vous pouvez lancer la commande une fois | |
947 | que les paquets ont été committés et construits par | |
948 | @code{@value{SUBSTITUTE-SERVER}} pour vérifier s'il obtient le même résultat | |
949 | que vous. Mieux encore : trouvez une autre machine qui peut le construire | |
950 | et lancez @command{guix publish}. Puisque la machine distante est sûrement | |
951 | différente de la vôtre, cela peut trouver des problèmes de non-déterminisme | |
952 | liés au matériel — par exemple utiliser une extension du jeu d'instruction — | |
953 | ou du noyau du système d'exploitation — par exemple se reposer sur | |
954 | @code{uname} ou les fichiers de @file{/proc}. | |
bf5c74e7 JL |
955 | |
956 | @item | |
957 | Lorsque vous écrivez de la documentation, utilisez une formulation au genre | |
958 | neutre lorsque vous vous référez à des personnes, comme le | |
959 | @uref{https://fr.wikipedia.org/wiki/They_singulier, ``they''@comma{} | |
960 | ``their''@comma{} ``them'' singulier} (en anglais). | |
961 | ||
962 | @item | |
963 | Vérifiez que votre correctif contienne seulement un ensemble de changements | |
3cacfa9e LC |
964 | liés. Grouper des changements non liés ensemble rend la revue plus |
965 | difficile et plus lente. | |
bf5c74e7 JL |
966 | |
967 | Ajouter plusieurs paquet ou une mise à jour d'un paquet avec des corrections | |
968 | dans ce paquet sont des exemples de changements sans rapport. | |
969 | ||
970 | @item | |
971 | Suivez nos règles de formatage de code, éventuellement en lançant le script | |
972 | @command{et/indent-code.el} pour le faire automatiquement (@pxref{Formatage | |
973 | du code}). | |
974 | ||
adfb167f JL |
975 | @item |
976 | 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 | |
977 | exemple, les archives GitHub ne sont pas nécessairement identiques d'une | |
978 | génération à la suivante, donc il vaut mieux dans ce cas cloner le dépôt. | |
979 | N'utilisez pas le champ @command{name} dans l'URL : ce n'est pas très utile | |
980 | et si le nom change, l'URL sera probablement erronée. | |
981 | ||
bf5c74e7 JL |
982 | @end enumerate |
983 | ||
984 | Lorsque vous envoyez un correctif à la liste de diffusion, utilisez | |
3cacfa9e | 985 | @samp{[PATCH] @dots{}} comme sujet. Vous pouvez utiliser votre client de |
bf5c74e7 | 986 | courriel ou la commande @command{git send-email} (@pxref{Envoyer une série |
3cacfa9e LC |
987 | de correctifs}). Nous préférons recevoir des correctifs en texte brut, soit |
988 | en ligne, soit en pièce-jointe MIME@. Nous vous conseillons de faire | |
bf5c74e7 JL |
989 | attention si votre client de courriel change par exemple les retours à la |
990 | ligne ou l'indentation, ce qui peut casser les correctifs. | |
991 | ||
992 | Lorsqu'un bogue est résolu, veuillez fermer le fil en envoyant un courriel à | |
993 | @email{@var{NNN}-done@@debbugs.gnu.org}. | |
994 | ||
995 | @unnumberedsubsec Envoyer une série de correctifs | |
996 | @anchor{Envoyer une série de correctifs} | |
997 | @cindex série de correctifs | |
998 | @cindex @code{git send-email} | |
999 | @cindex @code{git-send-email} | |
1000 | ||
1001 | @c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html | |
3cacfa9e | 1002 | Lorsque vous envoyez une série de correctifs (p.@@:: ex.@: avec @code{git |
bf5c74e7 JL |
1003 | send-email}), envoyez d'abord une premier message à |
1004 | @email{guix-patches@@gnu.org} puis envoyez le reste des correctifs à | |
1005 | @email{@var{NNN}@@debbugs.gnu.org} pour vous assurer qu'ils seront groupés | |
3cacfa9e | 1006 | ensemble. Voyez @uref{https://debbugs.gnu.org/Advanced.html, la |
bf5c74e7 | 1007 | documentation de Debbugs} pour plus d'informations. |