Lignes de conduite pour les rapports de bogues

Identifier les bogues

Avant de rapporter un bogue, merci de lire et re-lire la documentation pour vérifier que ce que vous essayez de faire est réellement prévu. Si la documentation n'est pas claire sur ce point, faites également remonter cette information ; c'est un bogue dans la documentation. S'il s'avère que le programme se déroule différemment de ce qu'indique la documentation, c'est un bogue. Ceci peut inclure les circonstances suivantes, sans s'y limiter :

• Un programme se termine avec un signal fatal ou un message d'erreur du système d'exploitation indiquant un problème dans le programme. (Un contre-exemple pourrait être le message << disk full >>, disque plein, car vous devez le régler vous-même.)

• Un programme produit une sortie erronnée pour une entrée donnée.

• Un programme refuse d'accepter une entrée valide (c'est-à-dire telle que définie dans la documentation).

• Un programme accepte une entrée invalide sans information ou message d'erreur. Il est toutefois possible que ce que vous estimez être une entrée invalide soit en fait notre idée d'une extension ou d'une compatibilité avec les pratiques traditionnelles.

• PostgreSQL échoue à la compilation, à la construction ou à l'installation suivant les instructions des plateformes supportées.

Ici, << programme >> fait référence à un exécutable, pas uniquement au moteur du serveur.

Une lenteur ou une accaparation des ressources n'est pas nécessairement un bogue. Lisez la documentation ou demandez sur une des listes de discussion de l'aide pour optimiser vos applications. Ne pas se conformer au standard SQL n'est pas nécessairement un bogue sauf si une telle conformité est indiquée explicitement.

Avant de continuer, vérifiez sur la liste des tâches, ainsi que dans la FAQ, pour voir si votre bogue n'est pas déjà connu. Si vous n'arrivez pas à décoder les informations sur la liste des tâches, écrivez un rapport. Le minimum que nous puissions faire est de rendre cette liste plus claire.

Que rapporter ?

Le point le plus important lors d'un rapport de bogues est de se souvenir de rapporter tous les faits et seulement les faits. Ne spéculez pas sur ce que vous pensez être le dysfonctionnement, sur ce qu'<< il semblait faire >> ou sur la partie du programme qui contient une erreur. Si vous n'êtes pas familier de l'implémentation, vous vous tromperez probablement et vous ne nous aiderez pas. Même si vous aviez raison, des explications complètes sont un bon complément mais elles ne doivent pas se substituer aux faits. Si nous décidons de corriger le bogue, nous devons toujours le reproduire nous-même. Rapporter les faits stricts est relativement simple (vous pouvez probablement les copier/coller à partir de l'écran) mais, trop souvent, des détails importants sont oubliés parce que quelqu'un a pensé qu'ils n'avaient pas d'importance ou que le rapport serait compris.

Les éléments suivants devraient être fournis avec chaque rapport de bogue :

• La séquence exacte des étapes nécessaires pour reproduire le problème à partir du lancement du programme. Ceci doit se suffire ; si la sortie doit dépendre des données contenues dans les tables, il n'est pas suffisant d'envoyer une simple instruction SELECT sans les commandes CREATE TABLE et INSERT qui ont précédé. Nous n'avons pas le temps de comprendre le schéma de votre base de données et si nous sommes supposés créer nos propres données, nous allons probablement passer à côté du problème.

  Le meilleur format de jeu de test pour les problèmes relatif au SQL est un fichier qui peut être lancé via l'interface psql et qui montrera le problème. (Assurez-vous de ne rien avoir dans votre fichier de lancement ~/.psqlrc.) Un bon début pour ce fichier est d'utiliser pg_dump pour récupérer les déclarations des tables ainsi que les données nécessaires pour mettre en place la scène. Il ne reste plus qu'à ajouter la requête posant problème. Vous êtes encouragé à minimiser la taille de votre exemple mais ce n'est pas une obligation. Si le bogue est reproductible, nous le trouverons de toute façon.

  Si votre application utilise une autre interface client, telle que PHP, essayez alors d'isoler les requêtes posant problème. Nous n'allons certainement pas mettre en place un serveur web pour reproduire votre problème. Dans tous les cas, n'oubliez pas de fournir les fichiers d'entrée exacts ; n'essayez pas de deviner que le problème se pose pour les << gros fichiers >> ou pour les << bases de données de moyenne taille >>, etc. car cette information est trop inexacte, voire subjective, pour être utile.

• La sortie que vous obtenez. Merci de ne pas dire que cela << ne fonctionne pas >> ou s'est << arrêté brutalement >>. S'il existe un message d'erreur, montrez-le, même si vous ne le comprenez pas. Si le programme se termine avec une erreur du système d'exploitation, dites-le. Même si le résultat de votre test est un arrêt brutal du programme ou un autre soucis évident, il pourrait ne pas survenir sur notre plateforme. Le plus simple est de copier directement la sortie du terminal quand cela est possible.

  Note : Si vous rapportez un message d'erreur, merci d'obtenir la forme la plus verbeuse de ce message. Avec psql, exécutez avant tout \set VERBOSITY verbose. Si vous récupérez le message des traces du serveur, positionnez la variable d'exécution log_error_verbosity à verbose pour que tous les détails soient tracés.

  Note : Dans le cas d'erreurs fatales, le message d'erreur rapporté par le client pourrait ne pas contenir toutes les informations disponibles. Jetez aussi un œil aux traces du serveur de la base de données. Si vous ne conservez pas les traces de votre serveur, c'est peut-être le bon moment pour commencer à le faire.

• La sortie que vous attendez est une information très importante à donner. Si vous écrivez uniquement << Cette commande m'a donné cette réponse. >> ou << Ce n'est pas ce que j'attendais. >>, nous pourrions le lancer nous-même, analyser la sortie et penser que tout est correct car cela correspond exactement à ce que nous attendions. Nous ne devrions pas avoir à passer du temps pour décoder la sémantique exacte de vos commandes. En particulier, ne vous contentez pas de dire que << Ce n'est pas ce que SQL spécifie/Oracle fait. >> Rechercher le comportement correct à partir de SQL n'est pas amusant et nous ne connaissons pas le comportement de tous les autres serveurs de base de données relationnels (Si votre problème est un arrêt brutal du serveur, vous pouvez évidemment omettre cet élément.)

• Toutes les options en ligne de commande ainsi que les autres options de lancement incluant les variables d'environnement ou les fichiers de configuration que vous avez modifié. Encore une fois, soyez précis. Si vous utilisez une distribution pré-empaquetée qui lance le serveur au démarrage, vous devriez essayer de retrouver ce que cette distribution fait.

• Tout ce que vous avez fait différement des instructions d'installation.

• La version de PostgreSQL. Vous pouvez lancer la commande SELECT version(); pour trouver la version du serveur sur lequel vous êtes connecté. La plupart des exécutables dispose aussi d'une option --version ; postmaster --version et psql --version au moins devraient fonctionner. Si la fonction ou les options n'existent pas, alors votre version est bien trop ancienne et vous devez la mettre à jour. Si vous avez lancé une version préparée sous forme de paquets, tels que des RPM, dites-le en incluant la sous-version que le paquet aurait éventuellement. Si vous travaillez avec une version CVS, mentionnez-le en indiquant la date et l'heure de la capture CVS.

  Si votre version est antérieure à 7.4.29, nous allons certainement vous demander de la mettre à jour. Il existe des tonnes de corrections à chaque mise à jour, ce qui explique pourquoi nous faisons de nouvelles versions.

• Informations sur la plate-forme. Ceci inclut le nom du noyau et sa version, bibliothèque C, processeur, mémoires. Dans la plupart des cas, il est suffisant de rapporter le vendeur et la version mais ne supposez pas que tout le monde sait ce que << Debian >> contient ou que tout le monde utilise des Pentiums. Si vous avez des problèmes à l'installation, les informations concernant le compilateurs, make, etc. seront aussi nécessaires.

Ne vous inquiétez pas si votre rapport de bogue devient assez long. C'est un fait. Il est préférable de tout rapporter la première fois plutôt que de nous obliger à vous demander tous les faits. D'un autre côté, si vos fichiers en entrée sont trop gros, il est préférable de demander si quelqu'un souhaite s'y plonger.

Ne passez pas tout votre temps à vous demander quelles modifications apporter aux données en entrée pour faire disparaître le problème. Ceci ne nous aidera probablement pas à le résoudre. S'il se trouve que le bogue ne puisse pas être corrigé instantanément, vous aurez toujours le temps de chercher et de partager vos trouvailles. Encore une fois, ne perdez pas votre temps à deviner pourquoi le bogue existe. Nous trouverons cela assez rapidement.

Lors de la rédaction d'un rapport de bogue, merci de choisir une terminologie qui ne laisse pas de place à l'ambiguité. Le paquet logiciel dans sa totalité est appelé << PostgreSQL >>, parfois << Postgres >> en abrégé. Si vous parlez spécifiquement du serveur, mentionnez-le mais ne dites pas seulement << PostgreSQL a planté >>. Un arrêt brutal d'un seul processus serveur est assez différent de l'arrêt brutal du << postmaster >> père ; merci de ne pas dire que << le postmaster a planté >> lorsque vous voulez dire qu'un seul processus s'est arrêté, et vice versa. De plus, les programmes clients tels que l'interface interactive << psql >> sont complètement séparés du moteur. Essayez d'être précis sur la provenance du problème : client ou serveur.

Où rapporter des bogues ?

En général, envoyez vos rapports de bogue à la liste de discussion des rapports de bogue (<pgsql-bugs@postgresql.org>). Il est recommandé d'utiliser un sujet descriptif pour votre courriel, pourquoi pas une partie du message d'erreur.

Une autre méthode consiste à remplir le formulaire web disponible sur le site web du projet http://www.postgresql.org/. Saisir un rapport de bogue de cette façon implique son envoi à la liste de discussion <pgsql-bugs@postgresql.org>.

Si votre rapport de bogue a des implications sur la sécurité et que vous préfériez qu'il ne soit pas immédiatement visible dans les archives publiques, ne l'envoyez pas sur pgsql-bugs. Les problèmes de sécurité peuvent être rapportés en privé sur <security@postgresql.org>.

N'envoyez pas de rapports de bogue aux listes de discussion d'utilisateurs, comme <pgsql-sql@postgresql.org> ou <pgsql-general@postgresql.org>. Ces listes de discussion servent à répondre aux questions des utilisateurs et les abonnés ne souhaitent pas, en général, recevoir de rapports de bogues. Plus important, il y a peu de chance qu'ils les corrigent.

De même, n'envoyez pas vos rapports de bogue à la liste de discussion des développeurs <pgsql-hackers@postgresql.org>. Cette liste sert aux discussions concernant le développement de PostgreSQL et il serait bon de conserver les rapports de bogue séparément. Nous pouvons toujours décider de discuter de votre rapport de bogue sur pgsql-hackers si le problème nécessite plus de personnes pour s'en occuper.

Si vous avez un problème avec la documentation, le meilleur endroit pour le rapporter est la liste de discussion pour la documentation <pgsql-docs@postgresql.org>. Soyez précis sur la partie de la documentation qui vous déplaît.

Si votre bogue concerne un problème de portabilité sur une plate-forme non supportée, envoyez un courrier électronique à <pgsql-hackers@postgresql.org>, pour que nous puissions travailler sur le portage de PostgreSQL sur votre plate-forme.