Chapitre 8. Mise à jour de paquet

# Chapitre 8. Mise à jour de paquet

La réécriture de ce tutoriel avec des contenus à jour et des exemples pratiques supplémentaires est disponible sur Guide du responsable Debian. Veuillez utiliser ce nouveau tutoriel comme document principal.

Après la publication d'un paquet, il sera rapidement nécessaire de le mettre à jour.

## 8.1. Nouvelle révision Debian

Soit un rapport de bogue numéroté `#654321`, concernant votre paquet et décrivant un problème que vous pouvez résoudre. Voici ce que vous devez faire pour créer une nouvelle révision du paquet :

- pour un nouveau correctif :

  - configurer le nom du correctif : `dquilt new `nomdubogue.patch``,

  - déclarer le fichier à modifier : `dquilt add `fichier-bogué``,

  - corriger le problème dans le paquet source pour le bogue amont,

  - l'enregistrer en ``nomdubogue.patch`` : `dquilt refresh`,

  - ajouter sa description : `dquilt header -e` ;

- pour la mise à jour d'un correctif :

  - rappeler le correctif ``toto.patch`` existant : `dquilt pop `toto.patch``,

  - corriger le problème dans l'ancien ``toto.patch``,

  - mettre à jour ``toto.patch`` : `dquilt refresh`,

  - mettre à jour sa description : `dquilt header -e`,

  - appliquer tous les correctifs en enlevant les approximations (fuzz) : `while dquilt push; do dquilt refresh; done` ;

- ajouter une nouvelle révision au début du fichier `changelog` Debian, par exemple avec `dch -i`, ou explicitement avec `dch -v `version`-`révision``, et ajoutez ensuite les commentaires en utilisant votre éditeur favori ;[76]

- ajouter une courte description du bogue et de la solution dans l'entrée du changelog, suivie par `Closes: #654321`. De cette manière, le rapport de bogue sera automagiquement fermé par le logiciel de maintenance des archives une fois le paquet accepté dans l'archive Debian ;

- répéter les opérations précédentes pour corriger plus de bogues tout en mettant à jour le fichier `changelog` avec `dch` selon votre besoin ;

- recommencer ce qui a été fait en Section 6.1, « Reconstruction complète » et Chapitre 7, Contrôle des erreurs du paquet ;

- une fois satisfait, modifier la valeur de distribution dans `changelog` d'`UNRELEASED` à la valeur de distribution cible `unstable` (ou même `experimental`) ; [77]

- envoyer le paquet comme en Chapitre 9, Envoi de paquet. La différence est que cette fois, l'archive source originale ne sera pas incluse, car elle n'a pas été modifiée et est déjà dans l'archive Debian.

Un cas délicat peut se produire quand vous faites un paquet local pour expérimenter l'empaquetage avant d'envoyer la version normale vers l'archive officielle, par exemple ``1.0.1`-`1``. Pour des mises à niveau plus en douceur, il vaut mieux créer une entrée de `changelog` avec une chaîne de version comme ``1.0.1`-`1~rc1``. Vous pouvez nettoyer le `changelog` en fusionnant ces entrées de modification en une unique entrée pour le paquet officiel. Consultez Section 2.6, « Nom et version de paquet » pour l'ordre des chaînes de version.

## 8.2. Examen d'une nouvelle version amont

Lors de la préparation de paquets d'une nouvelle version amont pour l'archive Debian, vous devez commencer par vérifier la nouvelle version amont.

Commencez par lire les `changelog` et `NEWS` amonts, ainsi que toute autre documentation distribuée avec la nouvelle version.

Examinez ensuite les modifications entre les anciennes et nouvelles sources amont, pour guetter tout changement suspect :

    $ diff -urN toto-ancienneversion toto-nouvelleversion

Les modifications de certains fichiers automatiquement créés par Autotools comme `missing`, `aclocal.m4`, `config.guess`, `config.h.in`, `config.sub`, `configure`, `depcomp`, `install-sh`, `ltmain.sh` et `Makefile.in` peuvent être ignorées. Vous pouvez les effacer avant d'exécuter diff pour examiner les sources.

## 8.3. Nouvelle version amont

Si un paquet ``toto`` est correctement empaqueté au nouveau format `3.0 (native)` ou `3.0 (quilt)`, empaqueter une nouvelle version amont consiste essentiellement à déplacer l'ancien répertoire `debian` dans les nouvelles sources. Ce peut être réalisé en exécutant `tar xvzf /`chemin`/`vers`/`toto`_`ancienneversion`.debian.tar.gz` depuis la nouvelle arborescence source décompressée. [78] Bien sûr, vous devez vous occuper de quelques routines évidentes :

- création d'une copie des sources amont dans un fichier `toto_`nouvelleversion`.orig.tar.gz` ;

- mise à jour du ficher `changelog` Debian avec `dch -v `nouvelleversion`-`1`` :

  - ajout d'une entrée avec `New upstream release.` (nouvelle version amont),

  - description succincte des modifications dans la nouvelle version amont qui corrigent des bogues et ferment les rapports associés en ajoutant `Closes: #`numéro_de_bogue``,

  - description succincte des modifications à la nouvelle version amont par le responsable qui corrigent des bogues et ferment les rapports associés en ajoutant `Closes: #`numéro_de_bogue`` ;

- application de tous les correctifs en enlevant les approximations (« fuzz ») : `while dquilt push; do dquilt refresh; done`.

Si la fusion des correctifs ne s'applique pas proprement, examinez la situation (des indices sont laissés dans les fichiers `.rej`) :

- si un correctif appliqué aux sources a été intégré aux sources amont :

  - `dquilt delete` pour l'enlever ;

- si un correctif appliqué aux sources entre en confit avec les nouvelles modifications des sources amont :

  - `dquilt push -f` pour appliquer les anciens correctifs tout en forçant les rejets comme ``truc`.rej` ;

  - édition manuelle du fichier ``truc`` pour obtenir le résultat attendu de ``truc`.rej` ;

  - `dquilt refresh` pour mettre à jour le correctif ;

- continuer comme d'habitude avec `while dquilt push; do dquilt refresh; done`.

Cette méthode peut être automatisée avec uupdate(1) :

    $ apt-get source toto
    ...
    dpkg-source: info: extraction de toto dans toto-ancienneversion
    dpkg-source: info: extraction de toto_ancienneversion.orig.tar.gz
    dpkg-source: info: extraction de toto_ancienneversion-1.debian.tar.gz
    $ ls -F
    toto-ancienneversion/
    toto_ancienneversion-1.debian.tar.gz
    toto_ancienneversion-1.dsc
    toto_ancienneversion.orig.tar.gz
    $ wget http://example.org/toto/toto-nouvelleversion.tar.gz
    $ cd toto-ancienneversion
    $ uupdate -v nouvelleversion ../toto-nouvelleversion.tar.gz
    $ cd ../toto-nouvelleversion
    $ while dquilt push; do dquilt refresh; done
    $ dch
    ... documentation des modifications réalisées

Si le fichier `debian/watch` est configuré comme décrit en Section 5.21, « `watch` », la commande wget est inutile. Exécutez simplement uscan(1) dans le répertoire ``toto`-`ancienneversion`` à la place de la commande uupdate. Les sources mises à jour seront automagiquement recherchées, téléchargées, et la commande uupdate sera exécutée. [79]

Vous pouvez publier ces sources mises à jour en recommençant ce qui a été fait en Section 6.1, « Reconstruction complète », Chapitre 7, Contrôle des erreurs du paquet et Chapitre 9, Envoi de paquet.

## 8.4. Mise à jour du style d'empaquetage

La mise à jour du style d'empaquetage n'est pas nécessaire lors de la mise à jour d'un paquet. Néanmoins, le faire permet de profiter de tout le potentiel du système `debhelper` moderne et du format source `3.0` : [80]

- si vous devez, pour quelque raison que ce soit, recréer des fichiers modèles qui avaient été effacés, vous pouvez exécuter dh_make à nouveau depuis le répertoire des sources Debian, avec l'option `--addmissing`. Puis modifiez-les de façon adéquate ;

- si le paquet n'a pas été mis à jour pour utiliser la syntaxe dh de `debhelper` v7+ dans le fichier `debian/rules`, mettez-le à jour pour utiliser dh. Mettez à jour le fichier `debian/control` en conséquence ;

- si vous voulez mettre à jour le fichier `rules` créé avec le mécanisme d'héritage `Makefile` du système de compilation usuel Debian (`cdbs`) vers la syntaxe dh, consultez les documents suivants pour comprendre ses variables de configuration `DEB_*` :

  - copie locale de `/usr/share/doc/cdbs/cdbs-doc.pdf.gz`,

  - le système de compilation usuel Debian (CDBS), FOSDEM 2009 ;

- si vous avez un paquet source `1.0` sans fichier ``toto`.diff.gz`, vous pouvez le mettre à jour au récent format source `3.0 (native)` en créant `debian/source/format` contenant `3.0 (native)`. Le reste des fichiers `debian/*` peut être simplement copié ;

- si vous avez un paquet source `1.0` avec un fichier ``toto`.diff.gz`, vous pouvez le mettre à jour au récent format source `3.0 (quilt)` en créant `debian/source/format` contenant `3.0 (quilt)`. Le reste des fichiers `debian/*` peut être simplement copié. Importez le fichier `gros.diff` créé par la commande `filterdiff -z -x '*/debian/*' `toto`.diff.gz > gros.diff` dans votre système quilt, au besoin ; [81]

- si l'empaquetage a été créé en utilisant un autre système de correctif comme `dpatch`, `dbs` ou `cdbs` avec `-p0`, `-p1` ou `-p2`, convertissez-le à `quilt` avec `deb3` disponible en http://bugs.debian.org/581186 ;

- si l'empaquetage a été créé avec la commande dh et le paramètre `--with quilt` ou les commandes dh_quilt_patch et dh_quilt_unpatch, supprimez-le et utilisez le nouveau format source `3.0 (native)`.

Vous devriez consulter les propositions d'améliorations Debian (DEP — Debian Enhancement Proposals) et adopter les propositions marquées « ACCEPTED ».

Les autres tâches décrites en Section 8.3, « Nouvelle version amont » sont aussi à effectuer.

## 8.5. Conversion en UTF-8

Si les documents amonts sont encodés avec d'anciens jeux de caractères, les convertir en UTF-8 peut être utile :

- avec iconv(1) pour convertir l'encodage de fichiers texte :

      iconv -f latin1 -t utf8 truc_entrée.txt > truc_sortie.txt

- avec w3m(1) pour convertir les fichiers HTML en fichier texte UTF-8. Assurez-vous d'exécuter cette commande avec des paramètres régionaux en UTF-8 :

      LC_ALL=en_US.UTF-8 w3m -o display_charset=UTF-8 \
              -cols 70 -dump -no-graph -T text/html \
              < truc_entrée.html > truc_sortie.txt

## 8.6. Rappels pour la mise à jour de paquets

Voici quelques rappels pour la mise à jour de paquets :

- préservez les anciennes entrées `changelog` (cela va de soi, mais des personnes ont parfois utilisé `dch` au lieu de `dch -i`) ;

- les modifications Debian existantes doivent être réévaluées ; jetez tout ce qui a été incorporé en amont (sous une forme ou une autre), et souvenez-vous de garder ce qui ne l'a pas été, à moins qu'il n'y ait une bonne raison de ne pas le faire ;

- si le système de construction a été modifié (avec un peu de chance, vous êtes au courant depuis l'inspection des modifications amont), mettez à jour les dépendances de construction `debian/rules` et `debian/control`, si besoin est ;

- vérifiez dans le système de gestion de bogues (BTS) que personne n'a fourni de correctifs aux bogues ouverts ;

- vérifiez le contenu du fichier `.changes` pour vous assurer que vous envoyez vers la bonne distribution, que les rapports de bogue refermés sont correctement listés dans les champs `Closes`, que les champs `Maintainer` et `Changed-By` correspondent, que le fichier est signé avec GPG, etc.

[76] Pour obtenir la date au format voulu, utilisez `LANG=C date -R`.

[77] Si vous utilisez la commande `dch -r` pour faire cette dernière modification, n'oublier pas de sauver le fichier `changelog` explicitement dans l'éditeur.

[78] Si un paquet ``toto`` est empaqueté avec l'ancien format `1.0`, ce peut plutôt être réalisé en exécutant `zcat /`chemin`/`vers`/`toto`_`ancienneversion`.diff.gz|patch -p1` depuis la nouvelle arborescence source décompressée.

[79] Si la commande uscan télécharge les sources mises à jour mais n'exécute pas la commande uupdate, vous devriez corriger le fichier `debian/watch` pour avoir `debian uupdate` après l'URL.

[80] Si votre parrain ou d'autres responsables s'opposent à la mise à jour du style d'empaquetage existant, ne vous embêtez pas à argumenter. Il y a des choses plus importantes à faire.

[81] vous pouvez découper `gros.diff` en plusieurs petits correctifs incrémentaux avec la commande splitdiff.

Chapitre 7. Contrôle des erreurs du paquet |  | Chapitre 9. Envoi de paquet