Linux Certif

Toute la documentation sur la certification Linux LPI

dch

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, voir ci-dessous). 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. Notez 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 debian/NEWS peut être créé à partir de rien en utilisant l'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, http://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 (voir leurs descriptions ci-dessous). 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 types différents 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 (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 avec succès n'y est enregistré. C'est peut-être parce l'envoi précédent a été exécuté avec une version de dupload inférieure à 2.1 ou parce que l'envoi a échoué. L'autre heuristique (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 alors la distribution sera changée en UNRELEASED dans les nouvelles entrées du journal des modifications, et l'option --mainttrailer décrite ci-dessus sera activée automatiquement. Ceci peut être utile si un paquet peut être distribué par différents responsables, ou si vous ne voulez pas garder les journaux d'envoi.

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 positionnée, sa valeur est utilisée comme nom complet du responsable. Si la variable d'environnement DEBEMAIL est positionnée, 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 positionnée. Si cette variable d'environnement n'est pas positionnée, le même test est réalisé sur EMAIL. Puis, si le nom complet n'est toujours pas 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 positionner les variables d'environnement DEBEMAIL et DEBFULLNAME lorsque ce script est utilisé.

Les changelogs 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 courante, et que le responsable est différent du responsable qui est mentionné comme ayant créé les entrées précédentes, alors les lignes seront ajoutées au changelog pour indiquer quel responsable a fait quelle modification. Pour le moment, seulement un des différents styles d'enregistrement de ces informations est supporté, dans lequel le nom du responsable qui a fait quelques modifications apparaît sur une ligne avant les modifications, entre crochets. Ceci 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. Ceci 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 courante. Ceci 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 :

0

Ne vérifie jamais le nom du répertoire.

1

Ne vérifie le nom du répertoire que s'il a fallu changer de répertoire pour trouver le fichier debian/changelog. C'est le comportement par défaut.

2

Vérifie toujours le nom du répertoire.

Le nom du répertoire est vérifié en testant si le nom du répertoire courant (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, ceci peut être changé en utilisant les options --changelog ou --news, ou la variable d'environnement CHANGELOG, comme décrit plus bas.

OPTIONS

--append, -a

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

--increment, -i

Incrémente le numéro de version Debian ou, dans le cas d'un paquet Debian natif, le numéro de version. Cela crée une nouvelle section au début du fichier changelog 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.

--newversion version, -v version

Permet de spécifier explicitement le numéro de version (avec la partie relative à la version Debian) et 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é.

--edit, -e

Édite le journal des modifications dans un éditeur.

--release, -r

Finaliser le fichier changelog pour un envoi. Ceci 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.

--force-save-on-release

Quand l'option --release est utilisée et qu'un éditeur a été ouvert pour permettre de vérifier le journal des modifications, l'utilisateur doit enregistrer le journal de modifications ouvert par l'éditeur. Sinon, le journal d'origine ne sera pas modifié. (option par défaut)

--no-force-save-on-release

Inverse de --force-save-on-release. Notez 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

Ceci 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ées 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 journal des modifications généré. 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 journal des modifications généré.

--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). Notez que dpkg-parsechangelog générera des avertissements du fait de l'absence de description de modifications.

--package paquet

Spécifie 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émente 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. Ceci 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émente 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 ajoute un commentaire « binNMU » dans le changelog.

--rebuild, -R

Increment the Debian release number for a no-change rebuild by appending a "build1" or by incrementing a rebuild version number.

--qa, -q

Incrémente le numéro de publication de Debian pour un envoi par l'équipe QA de Debian, et ajoute un commentaire « QA upload » dans le changelog.

--security, -s

Incrémente le numéro de publication de Debian pour un envoi par l'équipe Sécurité de Debian, et ajoute un commentaire « Security Team upload » dans le changelog.

--team

Incrémente le numéro de publication de Debian pour un envoi par l'équipe, et ajoute un commentaire « Team upload » dans le changelog.

--bpo

Incrémente le numéro de publication de Debian pour un envoi d'un rétroportage pour Lenny, et ajoute un commentaire pour l'envoi du rétroportage dans le changelog.

--local, -lsuffix

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

--force-bad-version, -b

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

--allow-lower-version

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 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 à un NMU (« 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

Le numéro de version amont sera déterminé en fonction 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,...]

Ajoute des entrées au fichier changelog pour fermer les bogues indiqués. Un éditeur est également invoqué après avoir ajouté ces entrées. Il générera 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

Spécifie si le BTS doit être interrogé lorsqu'une fermeture de bogue est générée.

--preserve, -p

Préserve 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 des variables de configuration ci-dessous.

--no-preserve, --nopreserve

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

--distribution dist, -D dist

Utilise 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

Utilise 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 bas (« low ») par défaut ou de la valeur courante pour les entrées existantes.

--changelog fichier, -c fichier

Ceci éditera 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]

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

--[no]multimaint

Précise s'il faut indiquer que différentes parties du journal des modifications ont été faites par différents responsables. L'option par défaut est --multimaint, regardez la discussion ci-dessus ainsi que les explications ci-dessous à propos de la variable DEBCHANGE_MULTIMAINT du fichier de configuration.

--[no]multimaint-merge

Should all changes made by the same author be merged into the same changelog section? Default is no; see the discussion above and also the DEBCHANGE_MULTIMAINT_MERGE configuration file option below.

--maintmaint, -m

Ne modifie pas 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 changelog. Notez 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 ces cas.

--[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 multi-responsables 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 lit 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ô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.

--help, -h

Affiche un message d'aide et quitte avec succès.

--version

Affiche la version et le copyright, puis quitte 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 neutraliser les paramètres des fichiers de configuration. Les variables d'environnement sont ignorées à cette fin. Les variables actuellement identifiées sont :

DEBCHANGE_PRESERVE

Si elle est positionnée à yes, équivaut à utiliser l'option --preserve.

DEBCHANGE_QUERY_BTS

Si elle est positionnée à 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. Notez 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 positionné à 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 positionnée à yes, lors de l'ajout de modifications dans le mode multi-responsables, 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

Si elle est positionnée à no, alors c'est comme si l'option --nomainttrailer était utilisée.

DEBCHANGE_TZ

Use this timezone for changelog entries. Default is the user/system timezone as shown by `date -R` and affected by the environment variable TZ.

DEBCHANGE_LOWER_VERSION_PATTERN

Si elle est positionnée, équivaut à utiliser l'option --allow-lower-version sur la ligne de commande.

DEBCHANGE_AUTO_NMU

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

DEBCHANGE_FORCE_SAVE_ON_RELEASE

Si elle est positionnée à « no », alors c'est comme si l'option --no-force-save-on-release était utilisée.

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

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

AUTEUR

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

TRADUCTION

Ce document est une traduction, réalisée par Nicolas François, Guillaume Delacour, Cyril Brulebois et Thomas Huriaux.

L'équipe de traduction a fait le maximum pour réaliser une adaptation française de qualité.

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

N'hésitez pas à signaler à l'auteur ou à la liste de traduction <debian-l10-french@lists.debian.org>, selon le cas, toute erreur dans cette page de manuel.