Manpages

NOM

debchange - Outil pour la maintenance du fichier debian/changelog d’un paquet source

SYNOPSIS

debchange [options] [texte ...]
dch [options] [texte ...]

DESCRIPTION

debchange ou son alias dch ajoute une nouvelle ligne de commentaire au fichier debian/changelog dans le répertoire des sources. Cette commande doit être exécutée depuis ce répertoire. Si le texte décrivant le changement est donné en ligne de commande, debchange s’exécutera de façon automatique et ajoutera simplement le texte, avec les passages à la ligne qui s’imposent et à l’emplacement approprié, dans le fichier debian/changelog (ou le fichier indiqué par les options décrites ci-après). Si le texte donné sur la ligne de commande est une chaîne NULL, debchange s’exécutera de façon automatique sans ajouter de texte. Si le texte donné sur la ligne de commande est une chaîne d’espaces, debchange s’exécutera de façon automatique et ajoute une entrée de changelog vide. Si aucun texte n’est renseigné, alors debchange exécute un éditeur (déterminé par sensible-editor) pour que vous éditiez le fichier. (Les variables d’environnement VISUAL et EDITOR sont utilisées dans cet ordre pour déterminer l’éditeur à utiliser.) Pour les éditeurs qui acceptent l’option +n pour démarrer l’édition à une ligne donnée, cette option sera utilisée pour positionner l’édition à la bonne ligne. Si l’éditeur est quitté sans avoir modifié le fichier temporaire, debchange quittera sans modifier le fichier changelog. Remarquez que les fichiers changelog sont supposés être codés en UTF-8. Dans le cas contraire, des problèmes peuvent se produire. Veuillez consulter la page de manuel de iconv(1) pour trouver comment convertir les fichiers changelog codés autrement. Enfin, un fichier changelog ou NEWS peut être créé à partir de rien en utilisantl’option --create décrite ci-dessous.

debchange peut également créer des entrées de changelog permettant de fermer des bogues, en utilisant l’option --closes. Le BTS, ou Debian Bug Tracking System (système de suivi de bogues Debian, https://bugs.debian.org/), est interrogé pour déterminer le titre du bogue et le paquet dans lequel il apparaît. Ce comportement peut être modifié en utilisant l’option --noquery ou en positionnant la variable de configuration DEBCHANGE_QUERY_BTS à no, comme décrit ci-dessus. Dans tous les cas, l’éditeur (voir ci-dessus) est toujours appelé pour permettre une modification de l’entrée, mais le fichier changelog est créé, que des modifications aient été faites ou non. Une entrée supplémentaire peut être fournie en ligne de commande en plus de l’entrée fermant le bogue.

Au plus une des options --append, --increment, --edit, --release, et --newversion doit être utilisée conformément à leurs descriptions ci-après. Si aucune option n’est fournie, debchange devra utiliser des heuristiques pour deviner si le paquet a bien été distribué ou non, et se comporte comme si --increment avait été utilisée si le paquet a été distribué, ou autrement comme si --append avait été utilisée.

Deux différents types d’heuristiques peuvent être utilisés, contrôlés par l’option --release-heuristic ou la variable de configuration DEBCHANGE_RELEASE_HEURISTIC. L’heuristique par défaut (changelog) suppose que le paquet a été distribué à moins que le journal des modifications ne contienne UNRELEASED dans le champ de la distribution. Si cette heuristique est activée, la distribution sera modifiée en UNRELEASED dans les nouvelles entrées du journal des modifications, et l’option --mainttrailer décrite ci-dessous sera activée automatiquement. Cela peut être utile si un paquet peut être distribué par différents responsables, ou si vous ne voulez pas garder les journaux d’envoi. L’autre heuristique (log) détermine si un paquet a été distribué en cherchant un journal dupload(1) ou dput(1) approprié. Un message d’alerte sera affiché si le fichier du journal est détecté mais qu’aucun envoi réussi n’y est enregistré. Cela peut arriver si l’envoi précédent a été exécuté avec une version de dupload inférieure à 2.1 ou s’il a échoué.

Si les options --increment ou --newversion sont utilisées, le nom et l’adresse électronique pour la nouvelle version sont déterminés de la façon suivante. Si la variable d’environnement DEBFULLNAME est définie, sa valeur est utilisée comme nom complet du responsable. Si la variable d’environnement DEBEMAIL est définie, elle est utilisée comme adresse électronique. Si cette variable est de la forme "nom <adresse>", alors le nom est pris dans cette variable si la variable d’environnement DEBFULLNAME n’est pas définie. Si cette variable d’environnement n’est pas définie, le même test est réalisé sur EMAIL. Puis, si le nom complet n’est pas encore déterminé, getpwuid(3) est utilisé pour déterminer le nom grâce au fichier des mots de passe. En cas d’échec, l’entrée précédente du fichier changelog est utilisée. Pour l’adresse électronique, si elle n’a pas été déterminée avec DEBEMAIL ou EMAIL, /etc/mailname est utilisé, puis il tente de la construire à partir du nom d’utilisateur et du FQDN, sinon, l’adresse de l’entrée précédente du fichier changelog est utilisée. Pour simplifier, il est préférable de définir les variables d’environnement DEBEMAIL et DEBFULLNAME lorsque ce script est utilisé.

Les journaux de modification qui enregistrent les modifications des différents coresponsables d’un paquet sont gérés. Si une entrée est ajoutée à celles de la version actuelle et que le responsable est différent du responsable qui est mentionné comme ayant créé les entrées précédentes, alors des lignes seront ajoutées au journal pour indiquer le responsable ayant fait cette modification. Pour le moment, seul un des différents styles d’enregistrement de ces informations est géré, dans lequel le nom du responsable ayant fait quelques modifications apparaît sur une ligne avant les modifications, entre crochets. Cela peut-être activé ou désactivé en utilisant l’option --[no]multimaint ou la variable de configuration DEBCHANGE_MULTIMAINT ; le comportement par défaut est de l’activer. À noter : si une entrée a déjà été marquée dans ce but, alors cette option sera ignorée de façon silencieuse.

Si le nom du répertoire de l’arborescence des sources est sous la forme paquet-version, debchange cherchera également à le renommer si le numéro de version (amont) change. Cela peut être empêché en utilisant l’option --preserve en ligne de commande ou avec un paramètre du fichier de configuration, comme décrit ci-dessous.

Si --force-bad-version ou --allow-lower-version est utilisée, debchange ne s’arrêtera pas si une nouvelle version est inférieure à la version actuelle. C’est particulièrement utile lors de la conception de rétroportages.

Vérification du nom du répertoire

Comme certains autres scripts du paquet devscripts, debchange parcourt une arborescence de répertoires jusqu’à ce qu’il trouve un fichier debian/changelog. Pour éviter les problèmes posés par les fichiers égarés, il examine le nom du répertoire parent une fois le fichier debian/changelog trouvé, et vérifie que le nom du répertoire correspond au nom du paquet. La méthode précise utilisée est contrôlée par les deux variables du fichier de configuration DEVSCRIPTS_CHECK_DIRNAME_LEVEL et DEVSCRIPTS_CHECK_DIRNAME_REGEX, et les options en ligne de commande associées --check-dirname-level et --check-dirname-regex.

DEVSCRIPTS_CHECK_DIRNAME_LEVEL peut prendre les valeurs suivantes :

Le nom du répertoire est vérifié en testant si le nom du répertoire actuel (donné par pwd(1)) correspond à l’expression rationnelle donnée par la variable DEVSCRIPTS_CHECK_DIRNAME_REGEX du fichier de configuration ou par l’option --check-dirname-regex regex. Il s’agit d’une expression rationnelle Perl (voir perlre(1)), qui sera ancrée à son début et à sa fin. Si elle contient un "/", alors elle doit correspondre au chemin complet. Si elle contient la chaîne "PACKAGE", cette chaîne sera remplacée par le nom du paquet source déterminé par le fichier changelog. La valeur par défaut de cette expression rationnelle est "PACKAGE(-.+)?", ce qui correspond aux répertoires nommés PACKAGE ou PACKAGE-version.

Le journal des modifications par défaut à éditer est debian/changelog ; cependant, cela peut être changé en utilisant les options --changelog ou --news, ou la variable d’environnement CHANGELOG, comme décrit plus bas.

OPTIONS

--append, -a

Ajouter une nouvelle entrée au fichier changelog à la fin des entrées de la version actuelle.

--increment, -i

Incrémenter le numéro de version Debian ou, dans le cas d’un paquet Debian natif, le numéro de version. Sur Ubuntu ou Tanglu, cela modifiera aussi le suffixe buildX en ubuntu1 ou tanglu1. Utiliser -R, --rebuild pour un incrément de reconstruction sans modification. Cela crée une nouvelle section au début du journal de modifications avec le bon en-tête et la signature. De plus, dans le cas d’une nouvelle version d’un paquet natif Debian, le nom du répertoire est modifié de manière à refléter ce changement de version. Si DEBCHANGE_RELEASE_HEURISTIC est changelog (par défaut) et que la version actuelle est UNRELEASED, cela ne modifiera que la version du paragraphe actuel du journal de modifications. Sinon, cela créera un nouveau paragraphe du journal de modifications avec la nouvelle version.

--newversion version, -v version

Indiquer explicitement le numéro de version (avec la partie relative à la version Debian). Cette option se comporte comme l’option --increment pour les autres aspects. Le nom du répertoire sera également modifié si le numéro de version amont a changé. Si DEBCHANGE_RELEASE_HEURISTIC est changelog (par défaut) et que la version actuelle est UNRELEASED, cela ne modifiera que la version du paragraphe actuel du journal de modifications. Sinon, cela créera un nouveau paragraphe du journal de modifications avec la nouvelle version.

--edit, -e

Éditer le journal des modifications dans un éditeur.

--release, -r

Finaliser le fichier changelog pour un envoi. Cela met à jour l’horodatage du fichier changelog. Si la distribution vaut UNRELEASED, elle prend la valeur de l’entrée précédente du fichier (ou de la distribution indiquée par l’option --distribution). S’il n’y a pas d’entrée précédente, et qu’aucune distribution n’a été indiquée explicitement, la distribution sera unstable (ou le nom de la version en cours de développement lorsqu’utilisé avec Ubuntu).

--force-save-on-release

Quand l’option --release est utilisée, un éditeur est ouvert pour permettre de vérifier le journal des modifications. L’utilisateur doit enregistrer le journal de modifications pour accepter les modifications du fichier, sinon l’original sera conservé (option par défaut).

--no-force-save-on-release

Inverse de --force-save-on-release. Remarquez qu’une fausse entrée de journal peut être fournie pour obtenir le même résultat - par exemple avec debchange --release "". L’entrée ne sera pas ajoutée au journal des modifications, mais sa présence évite l’ouverture de l’éditeur.

--create

Cela créera un nouveau fichier debian/changelog (ou debian/NEWS si l’option --news est utilisée). Vous devez être dans le répertoire de plus haut niveau pour l’utiliser ; aucune vérification sur le nom du répertoire ne sera faite. Le nom du paquet et sa version peuvent être indiqués en utilisant les options --package et --newversion, déterminés grâce au nom du répertoire en utilisant l’option --fromdirname ou entrés manuellement dans le fichier changelog créé. Le nom du responsable est déterminé grâce aux variables d’environnement si cela est possible, et la distribution est indiquée soit en utilisant l’option --distribution soit dans le fichier changelog créé.

--empty

Quand elle est utilisée avec l’option --create, elle permet de supprimer l’ajout automatique d’une entrée "initial release" (de telle sorte que le prochain appel à debchange ajoutera la première entrée). Remarquez que dpkg-parsechangelog produira des avertissements du fait de l’absence de description de modifications.

--package paquet

Indiquer le nom du paquet qui devra être utilisé dans le nouveau journal des modifications ; doit être utilisé seulement en conjonction avec les options --create, --increment, et --newversion.

--nmu, -n

Incrémenter le numéro de version Debian pour un envoi d’un non-responsable soit en ajoutant ".1" à une version non-NMU (à moins qu’il s’agisse d’un paquet Debian natif, auquel cas "+nmu1" est ajouté), soit en incrémentant un numéro de NMU et ajouter un commentaire NMU au journal des modifications. Cela se produit automatiquement si l’auteur du paquet n’est pas dans les champs Maintainer ou Uploaders de debian/control, à moins que DEBCHANGE_AUTO_NMU soit définie à no ou que l’option --no-auto-nmu soit utilisée.

--bin-nmu

Incrémenter le numéro de version Debian pour un envoi binaire d’un non-responsable soit en ajoutant "+b1" à une version non-binNMU soit en incrémentant un numéro de binNMU, et ajouter un commentaire "binNMU" dans le journal des modifications.

--qa, -q

Incrémenter le numéro de publication de Debian pour un envoi par l’équipe QA de Debian, et ajouter un commentaire "QA upload" dans le journal des modifications.

--rebuild, -R

Incrémente le numéro de version Debian pour une reconstruction sans modification en ajoutant "build1" ou en incrémentant un numéro de reconstruction.

--security, -s

Incrémenter le numéro de publication de Debian pour un envoi par l’équipe Sécurité de Debian, et ajouter un commentaire "Security Team upload" dans le journal des modifications.

--upstream, -U

Ne pas ajouter nom-de-distribution1 à la version d’une distribution dérivée. Incrémenter le numéro de publication de Debian.

--stable

Incrémenter le numéro de publication de Debian pour un envoi pour la publication stable actuelle.

--local, -lsuffixe

Ajouter un suffixe au numéro de version Debian pour une construction locale.

--force-bad-version, -b

Forcer un numéro de version à être moins élevé que le numéro de version actuel (comme c’est le cas par exemple dans le cas d’un rétroportage).

--allow-lower-version modèle

Permettre à un numéro de version d’être inférieur à la version en cours si la nouvelle version satisfait le modèle indiqué.

--force-distribution

Forcer l’utilisation de la distribution indiquée, même si elle ne correspond à aucune distribution connue (par exemple pour une distribution non officielle).

--auto-nmu

Essayer de déterminer automatiquement si une modification dans le journal des modifications correspond à une NMU (mise à jour indépendante ou "Non Maintainer Upload"). Il s’agit du comportement par défaut.

--no-auto-nmu

Désactiver la détection automatique des NMU. C’est équivalent à configurer DEBCHANGE_AUTO_NMU avec la valeur no.

--fromdirname, -d

Déterminer le numéro de version amont à partir du nom du répertoire, qui devra être de la forme paquet-version. Si le numéro de version amont a augmenté depuis l’entrée la plus récente du fichier changelog, la nouvelle entrée sera ajoutée avec pour numéro de version version-1 (ou version dans le cas d’un paquet Debian natif), avec le même temps absolu ("epoch") que le paquet précédent. Si le numéro de version amont est le même, cette option se comporte de la même façon que -i.

--closes nnnnn[,nnnnn ...]

Ajouter des entrées au fichier changelog pour fermer les bogues indiqués. Un éditeur est également lancé après avoir ajouté ces entrées. Il produira des avertissements si le BTS ne peut pas être contacté (et que l’option --noquery n’a pas été utilisée) ou s’il y a un problème avec un rapport de bogue.

--[no]query

Doit-on interroger le BTS lorsqu’une fermeture de bogue est produite ?

--preserve, -p

Conserver le nom du répertoire de l’architecture source si le numéro de version amont (ou le numéro de version d’un paquet Debian natif) change. Veuillez également consulter la section sur les variables de configuration ci-dessous.

--no-preserve, --nopreserve

Ne pas conserver le nom du répertoire de l’arborescence des sources (comportement par défaut).

--vendor éditeur

Écraser l’identifiant de distributeur dont la valeur par défaut est renvoyée par dpkg-vendor. Ce nom est utilisé pour les heuristiques appliquées aux nouvelles versions de paquet et aux vérifications de distribution cible.

--distribution dist, -D dist

Utiliser la distribution indiquée dans la nouvelle entrée du fichier changelog au lieu d’utiliser la distribution de la dernière entrée ou de l’entrée en cours d’édition.

--urgency urgence, -u urgence

Utiliser le niveau d’urgence indiqué dans la nouvelle entrée du fichier changelog, s’il y en a une, au lieu du niveau d’urgence moyen ("medium") par défaut ou de la valeur actuelle pour les entrées existantes.

--changelog fichier, -c fichier

Éditer le journal des modifications fichier au lieu de debian/changelog. Cette option remplace la valeur définie par la variable d’environnement CHANGELOG. De plus, aucune traversée ou contrôle de répertoire ne sera fait quand cette option est utilisée.

--news [newsfile]

Éditer newsfile (debian/NEWS par défaut) au lieu du journal des modifications. Une recherche sur le répertoire sera faite. Le journal des modifications sera analysé pour déterminer la version actuelle du paquet.

--[no]multimaint

Préciser s’il faut indiquer que les différents points du journal des modifications sont l’œuvre de différents responsables. L’option par défaut est --multimaint. Veuillez consulter la discussion ci-dessus ainsi que les explications ci-dessous à propos de la variable DEBCHANGE_MULTIMAINT du fichier de configuration.

--[no]multimaint-merge

Préciser si toutes les modifications réalisées par le même auteur doivent être fusionnées dans la même section du journal des modifications. L’option par défaut est --nomultimaint-merge. Veuillez consulter la discussion ci-dessus ainsi que les explications ci-dessous à propos de la variable DEBCHANGE_MULTIMAINT_MERGE du fichier de configuration.

--maintmaint, -m

Ne pas modifier les informations sur le responsable listées précédemment dans le journal des modifications. C’est particulièrement utile pour les parrains qui souhaitent ajouter un message automatiquement sans perturber les informations du journal des modifications. Remarquez qu’il peut y avoir des interactions intéressantes quand le mode multiresponsable est utilisé : vous voudrez probablement vérifier le journal des modifications manuellement avant d’envoyer le paquet à l’archive dans ce cas.

--controlmaint, -M

Utiliser les données du champ Maintainer du fichier debian/control plutôt que les variables d’environnements habituelles (DEBFULLNAME, DEBEMAIL, etc.). Cette option peut servir à rétablir les données du responsable principal dans la dernière ligne de l’entrée du journal de modifications après un problème d’édition (par exemple quand on voulait utiliser l’option -m et qu’on a oublié) ou lors de la publication d’un paquet au nom du responsable principal (par exemple l’équipe).

--[no]mainttrailer, -t

Si l’option mainttrailer est activée, elle évitera la modification de la ligne de fin des entrées du journal des modifications (c’est-à-dire les détails sur le responsable et l’horodatage), à moins qu’une option qui nécessite la modification de cette ligne de fin soit utilisée (par exemple, --create, --release, -i, --qa, etc.). Cette option diffère de --maintmaint puisque le mode multiresponsable sera utilisé s’il se justifie, à l’exception de l’édition de la ligne de fin. Consultez aussi l’option du fichier de configuration DEBCHANGE_MAINTTRAILER ci-dessous.

--check-dirname-level N

Veuillez consulter la section ci-dessus "Vérification du nom du répertoire" pour une explication de cette option.

--check-dirname-regex regex

Veuillez consulter la section ci-dessus "Vérification du nom du répertoire" pour une explication de cette option.

--no-conf, --noconf

Ne lire aucun fichier de configuration. L’option ne peut être utilisée qu’en première position de la ligne de commande.

--release-heuristic log|changelog

Contrôler comment debchange détermine si le paquet a été distribué, pour décider s’il faut créer une nouvelle entrée ou rajouter dans une entrée existante du journal des modifications.

--help, -h

Afficher un message d’aide et quitter avec succès.

--version

Afficher la version et le copyright, puis quitter avec succès.

VARIABLES DE CONFIGURATION

Les deux fichiers de configuration /etc/devscripts.conf et ~/.devscripts sont évalués dans cet ordre pour régler les variables de configuration. Des options de ligne de commande peuvent être utilisées pour écraser les paramètres des fichiers de configuration. Les variables d’environnement sont ignorées à cette fin. Les variables actuellement identifiées sont :
DEBCHANGE_PRESERVE

Lui attribuer la valeur yes équivaut à utiliser l’option --preserve.

DEBCHANGE_QUERY_BTS

Lui attribuer la valeur no équivaut à utiliser l’option --noquery.

DEVSCRIPTS_CHECK_DIRNAME_LEVEL, DEVSCRIPTS_CHECK_DIRNAME_REGEX

Veuillez consulter la section "Vérification du nom du répertoire" ci-dessus pour une explication de ces variables. Remarquez que ce sont des variables de configuration pour tous les outils du paquet devscripts ; elles impacteront tous les scripts qui les utilisent, comme indiqué dans leurs pages de manuel respectives et dans devscripts.conf(5).

DEBCHANGE_RELEASE_HEURISTIC

Contrôle comment debchange détermine si le paquet a été distribué, pour décider s’il faut créer une nouvelle entrée ou rajouter dans une entrée existante du journal des modifications. Peut être soit log soit changelog.

DEBCHANGE_MULTIMAINT

Si elle est définie à no, debchange n’introduira pas de distinction multiresponsable lorsqu’un responsable différent ajoutera une entrée à un journal des modifications existant. Regardez la discussion ci-dessus. La valeur par défaut est yes.

DEBCHANGE_MULTIMAINT_MERGE

Si elle est définie à yes, lors de l’ajout de modifications en mode multiresponsable, debchange vérifiera si des modifications précédentes ont été réalisées par le responsable actuel et ajoutera les modifications au bloc existant plutôt que de créer un nouveau bloc. La valeur par défaut est no.

DEBCHANGE_MAINTTRAILER

Lui attribuer la valeur no équivaut à utiliser l’option --nomainttrailer.

DEBCHANGE_TZ

Utiliser ce fuseau horaire pour les entrées de journal des modifications. Par défaut, le fuseau horaire de l’utilisateur sur le système est utilisé, comme avec "date -R" avec prise en compte de la variable d’environnement TZ.

DEBCHANGE_LOWER_VERSION_PATTERN

Lui attribuer une valeur équivaut à utiliser cette valeur avec l’option --allow-lower-version sur la ligne de commande.

DEBCHANGE_AUTO_NMU

Si elle est définie à no alors debchanges n’essaiera pas de déterminer automatiquement si la modification en cours représente une NMU. La valeur par défaut est yes. Consultez la discussion sur l’option --nmu ci-dessus.

DEBCHANGE_FORCE_SAVE_ON_RELEASE

Lui attribuer la valeur no équivaut à utiliser l’option --no-force-save-on-release.

DEBCHANGE_VENDOR

Utiliser cet éditeur à la place de celui par défaut (sortie de dpkg-vendor). Consultez --vendor pour plus de précisions.

ENVIRONNEMENT

DEBEMAIL, EMAIL, DEBFULLNAME, NAME

Reportez-vous à la description précédente de l’utilisation de ces variables d’environnement.

CHANGELOG

Cette variable indique le journal des modifications à éditer en remplacement de debian/changelog. Aucune traversée ou contrôle de répertoire ne sera fait si cette variable est utilisée. Cette variable est remplacée par l’option de la ligne de commande --changelog.

VISUAL, EDITOR

Ces variables d’environnement déterminent (dans cet ordre) quel sera l’éditeur invoqué par sensible-editor.

VOIR AUSSI

debc(1), debclean(1), dput(1), dupload(1), devscripts.conf(5)

AUTEUR

L’auteur initial est Christoph Lameter <clameter [AT] debian.org>. Beaucoup de changements substantiels et d’améliorations ont été apportés par Julian Gilbey <jdg [AT] debian.org>.

TRADUCTION

Ce document est une traduction, maintenue à l’aide de l’outil po4a <https://po4a.org/> par l’équipe de traduction francophone du projet Debian.

Nicolas François, Guillaume Delacour, Cyril Brulebois, Thomas Huriaux et David Prévot ont réalisé cette traduction.

L’équipe de traduction a fait le maximum pour réaliser une adaptation française de qualité. Veuillez signaler toute erreur de traduction en écrivant à <debian-l10n-french [AT] lists.org> ou par un rapport de bogue sur le paquet devscripts.

La version anglaise la plus à jour de ce document est toujours consultable en ajoutant l’option « -L C » à la commande man.