Updated workflow

HowtoDebian/Packaging.md

@@ -68,7 +68,112 @@ EOF
 
 ## Création d’un paquet
 
-### Génération de l'arborescence _debian/_
+### Génération de l'arborescence _debian/_ – Méthode facile
+
+Quand c’est possible, s’inspirer d’un paquet existant permet de
+faciliter l’étape d’initialisation.
+Il faut donc d’abord trouver un paquet du même genre que le nouveau
+paquet.
+Par exemple, pour créer un nouveau paquet
+[`php-sqlsrv`](https://bugs.debian.org/900572), qui a ses sources dans
+le [dépôt d’extensions PECL](https://pecl.php.net/), l’idée est de
+s’inspirer d’un paquet (récemment mis à jour) de l’[équipe PHP
+PECL](https://qa.debian.org/developer.php?email=team%2Bphp-pecl%40tracker.debian.org)
+comme [`php-igbinary`](https://tracker.debian.org/php-igbinary).
+
+Passons en revue les fichiers et points importants.
+
+#### debian/changelog
+
+Ne garder qu’une entrée (la première, tout en bas) suffit. Changer le
+nom du paquet, et s’assurer que la version est inférieure à la version
+amont cible (pour pouvoir télécharger la dernière version amont plus
+tard dans le processus).
+
+Adapter éventuellement l’entrée principale (après l’astérisque), mais
+pas la peine de s’embêter avec la dernière ligne contenant l’auteur et
+la date : elle sera mise à jour par
+([gbp](https://packages.debian.org/unstable/git-buildpackage))
+[dch](https://packages.debian.org/unstable/devscripts).
+
+#### debian/compat
+
+Fichier rendu obsolète par debhelper-compat, à supprimer.
+
+#### debian/control
+
+Pour les paquets PECL, ce fichier est mis à jour automatiquement à
+partir de `debian/control.in`, il est donc inutile d’éditer ce fichier,
+passons directement à `debian/control.in`.
+
+Modifier le nom du paquet source (`Source`) et binaire (`Package`), les
+champs `Maintainer` et `Uploaders`, les champs de dépôt (`Vcs-Git` et
+`Vcs-Browser`), la page d’accueil amont (`Homepage`), et surtout la
+description (`Description`), courte (synopsys) et longue (suivre les
+[conseils de la référence du
+développeur](https://www.debian.org/doc/manuals/developers-reference/best-pkging-practices#the-package-synopsis-or-short-description).
+
+Pour les dépendances de construction `Build-Depends`, préférer
+`debhelper-compat (= 13)` à `debhelper` (et fichier `debian/compat` pour
+la version).
+`dh-php (>= 4~)` et `php-all-dev` sont les dépendances nécessaires pour
+ce type de paquets.
+Adapter ensuite les dépendances spécifiques (`php-apcu-all-dev` est ici
+nécessaire à `php-igbinary`, alors que `unixodbc-dev` est nécessaire à
+`php-sqlsrv`).
+
+#### debian/copyright
+
+Adaptation nécessaire (mais généralement légère si le paquet pris en
+point de départ est du même auteur que le nouveau paquet).
+
+#### debian/gbp.conf
+
+Fichier utile à l’utilisation de
+[git-buildpackage](https://honk.sigxcpu.org/piki/projects/git-buildpackage/).
+
+#### debian/`$paquet`.php, debian/`$extension`.ini
+
+Ce sont des spécificités aux paquets PECL, peu d’adaptation est
+nécessaire (attention tout de même au nom des fichiers).
+
+#### debian/rules
+
+Rien à adapter dans ce cas, en fonction du type de paquet, les équipes
+en charge ont généralement des habitudes et outillages permettant de
+réduire les modifications.
+
+#### debian/source/format
+
+Devrait toujours contenir `3.0 (quilt)`.
+
+#### debian/watch
+
+Adapter en fonction de la distribution des sources amont, c’est ce qui
+permet d’[importer la dernière version](#nouvelle-version-amont).
+
+### Nouvelle version amont
+
+Il faut récupérer la nouvelle version amont (lors des mises à jour
+amont, et lors de la création du nouveau paquet.
+Si tout a été configuré correctement (cf. supra pour un nouveau paquet),
+`gbp import-orig --uscan` (ou `uscan(1)` pour un simple téléchargement)
+permet d’importer la dernière version amont.
+
+Les correctifs spécifiques (dans `debian/patches`) peuvent nécessiter
+une mise à jour s’ils existent (`gbp pq rebase` et `gbp pq export`
+permettent d’utiliser le workflow Git usuel).
+
+Il faut enfin mettre à jour le fichier `debian/changelog`, de préférence
+avec `gbp dch --multimaint-merge -R --commit` qui mets à jour la
+version, l’auteur, la date et propose des entrées à adapter.
+
+### Construction du paquet
+
+`gbp buildpackage` doit fonctionner avec `sbuild` si les étapes de
+configuration précédentes ont été suivies.
+
+### Génération de l'arborescence _debian/_ – Méthode traditionnelle
 
 Cette étape consiste à créer une arborescence qui constituera le paquet Debian. On peut l'automatiser simplement avec la commande _dh_make_ :
 
@@ -88,7 +193,7 @@ En utilisant dh_make sans options, il essayera de deviner les informations dont
 
 Le type de paquet vous sera demandé lors de l'exécution.
 
-### Édition de certains fichiers importants
+#### Édition de certains fichiers importants
 
 _dh_make_ a créé de nombreux fichiers dans le répertoire _debian/_. Certains sont indispensables, d'autres moins.
 Par exemple (si vous ne vous en servez pas) vous pouvez supprimer tous les *.ex, des templates servant d'exemple.
@@ -120,16 +225,6 @@ Si l'on simplement copier un script, on peut par exemple rajouter ceci à la fin
     install    -m 0755 -o root -g root nom-du-script $(CURDIR)/debian/futur-paquet
 ~~~
 
-### Construction du paquet
-
-Maintenant nous pouvons construire le paquet à l'aide de la commande :
-
-~~~
-$ debuild -us -uc
-~~~
-
-Si aucune erreur n'est apparue, votre paquet est prêt à être installé et/ou poussé sur un dépôt non officiel.
-
 ## Manipulation d'un paquet (binaire)
 
 Pour certaines (mauvaises) raisons, on peut être amené à vouloir modifier un paquet binaire... notamment un maintainer script par exemple.