Comment rapporter un bogue ou un

Ecrire un bon rapport de bogue requiert de la patience, et le faire d`es le d´ebut ´epargnera votre temps et le notre. Un bon rapport de bogue qui contient un cas de test complet am´eliorera vos chances de voir le bogue corrig´e `a la prochaine version. Cette section vous aidera `a ´ecrire correctement un rapport de bogue, de mani`ere `a ce que vous ne gaspillez pas votre temps `a faire des textes qui ne nous aideront que peu ou pas.

Nous vous recommandons d’utiliser le script mysqlbug pour g´en´erer un rapport de bogue (ou rapporter un probl`eme), dans la mesure du possible. mysqlbug est situ´e dans le dossier ‘scripts’ de la distribution, ou, pour les distributions binaire, dans le dossier ‘bin’ du

dossier d’installation de MySQL. Si vous ˆetes dans l’incapacit´e d’utiliser mysqlbug, vous devez tout de mˆeme inclure toutes les informations n´ecessaires list´ees dans cette section. Le script mysqlbug vous aide `a g´en´erer un rapport en d´eterminant automatiquement les informations suivantes, mais si quelque chose d’important lui ´echappe, ajoutez le dans votre message! Lisez cette section avec attention, et assurez vous que toutes les informations d´ecrites ici sont pr´esentes dans votre message.

Pour rapporter un bogue ou un probl`eme, il faut le soumettre `a la liste mysql@lists.mysql.com. Si vous pouvez r´ediger un cas de test qui d´emontre clairement le bogue, il faut le poster sur la liste bugs@lists.mysql.com. Notez que sur cette liste, vous ne devez poster qu’un rapport complet de bogue reg´en´erable, avec le script mysqlbug. Si vous travaillez sous Windows, vous devez ajouter une description de votre syst`eme d’exploitation et de votre version de MySQL. De pr´ef´erence, il vaut mieux utiliser la derni`ere version de MySQL, version stable ou de d´eveloppement, avant d’envoyer un message. Tout le monde doit ˆetre capable de reproduire le bogue en utilisant simplement la ligne de commande “mysql test < script”, avec le cas de bogue fourni, ou bien d’ex´ecuter un script shell ou Perl qui est inclut dans le rapport de bogue. Tous les bogues post´es sur la liste bogues seront corrig´es ou document´es dans la prochaine version de MySQL. Si seul de petits changements sont n´ecessaires, nous publierons aussi un patch. Si vous avez d´ecouvert un probl`eme de s´ecurit´e sensible dans MySQL, il faut envoyer un email `a security@mysql.com.

Sachez qu’il est toujours possible de r´epondre `a un message qui contient trop d’informations, alors qu’il est impossible de r´epondre `a um message qui contient trop peu d’informations. Souvent, il est facile d’omettre des faits parce que vous pensez connaˆitre la cause du probl`eme et supposez que ces d´etails ne sont pas importants. Un bon principe `a suivre est : si vous avez un doute `a propos de quelque chose, faites nous en part. Il est bien plus rapide et bien moins frustrant d’´ecrire quelques lignes de plus dans un rapport plutˆot que d’ˆetre oblig´e de demander une nouvelle fois et d’attendre une r´eponse parce que vous avez oubli´e une partie des informations la premi`ere fois.

L’erreur la plus commune est de ne pas indiquer le num´ero de la version de MySQL qui est utilis´e, ou de ne pas indiquer le syst`eme d’exploitation que vous utilisez (y compris le num´ero de version de ce syst`eme d’exploitation). Ce sont des informations de premi`ere importance, et dans 99% d4es cas, le rapport de bogue est inutilisable sans ces informations. Souvent, nous recevons des questions telles que “Pourquoi est ce que cela ne fonctionne pas pour moi?”. Puis nous nous aper¸cevons que la fonctionnalit´es en question n’est mˆeme pas programm´ee dans la version de MySQL utilis´ee, ou que le bogue d´ecrit est d´ej`a corrig´e dans une nouvelle version de MySQL. Parfois aussi, les erreurs sont d´ependantes des plate-formes. Dans ce cas, il est presque impossible de les corriger sans savoir quel syst`eme d’exploitation et quelle version exacte est utilis´ee.

Pensez aussi `a fournir des informations concernant votre compilateur, si c’est pertinent. Souvent, les d´eveloppeurs trouvent des bogues dans les compilateurs, et pensent que c’est li´es `a MySQL. La plupart des compilateurs sont en constant d´eveloppement, et s’am´eliorent de version en version. Pour d´eterminer si votre probl`ee d´epend de votre compilateur, nous avons besoin de savoir quel compilateur est utilis´e. Notez que les probl`emes de compilations sont des bogues, et doivent ˆetre trait´es avec un rapport de bogues.

Il est particuli`erement utile de fournir une bonne description du bogue dans le rapport de bogue. Cela peut ˆetre un exemple de ce que vous avez fait qui a conduit au probl`eme, ou une description pr´ecise. Les meilleurs rapports sont ceux qui incluent un exemple complet permettant de reproduire le bogue. Voir Section E.1.6 [Reproduceable test case], page 819. Si un programme produit un message d’erreur, il est tr`es important d’inclure ce message dans votre rapport. Il est pr´ef´erable que le message soit le message exact, car il est alors pos- sible de le retrouver en utilisant les archives : mˆeme la casse doit ˆetre respect´ee. N’essayez jamais de vous rappeler d’un message d’erreur, mais faites plutˆot un copier/coller du mes- sage complet dans votre rapport.

Si vous avez un probl`eme avec MyODBC, essayez de g´en´erer un fichier de trace MyODBC. Voir Section 8.3.7 [MyODBC bug report], page 608.

Pensez aussi que de nombreux personnes qui liront votre rapport utilisent un formatage de 80 colonnes. Lorsque vous g´en´erez votre rapport et vos exemples avec l’outil de ligne de commande, utilisez une largeur de 80 colonnes. Utilisez l’option --vertical (ou la fin de commande \G) pour les affichages qui exc`edent une telle largeur (par exemple, avec la commande EXPLAIN SELECT; voyez l’exemple un peu plus tard dans cette section.

Voici un pense-bˆete des informations `a fournir dans votre rapport :

• Le num´ero de version de la distribution de MySQL que vous utilisez (par exemple

MySQL Version 3.22.22). Vous pouvez connaitre cette version en excutant la commande mysqladmin version. mysqladmin est situ´e dans le dossier ‘bin’ de votre distribution MySQL.

• Le fabricant et le mod`ele de votre serveur.

• Le syst`eme d’exploitation et la version que vous utilisez. Pour la plupart des syst`emes

d’exploitation, vous pouvez obtenir cette information en utilisant la commande Unix command uname -a.

• Parfois, la quantit´e de m´emoire (physique et virtuelle) est important. Si vous h´esitez,

ajoutez la.

• Si vous utilisez une version de MySQL sous forme de source, le nom et le num´ero de

version du compilateur sont n´ecessaires. Si vous utilisez une version ex´ecutable, le nom de la distribution est important.

• Si le probl`eme intervient lors de la compilation, incluez le message d’erreur exact et les

quelques lignes de contexte autour du code en question dans le fichier o`u il est situ´e.

• Si mysqld s’est arr´et´e, il est recommand´e d’inclure la requˆete qui a men´e `a cet arrˆet de

mysqld. Vous pouvez g´en´eralement la trouver en ex´ecutant mysqld en ayant activ´e les logs. Voir Section E.1.5 [Using log files], page 818.

• Si une table ou une base sont li´es au probl`eme ajoutez le r´esultat de la commande

mysqldump --no-data db_name tbl_name1 tbl_name2 .... C’est tr`es simple `a faire, et c’est un moyen efficace d’obtenir un descriptif de table, qui nous permettra de recr´e´eer une situation comparable `a la votre.

• Pour les probl`emes li´es `a la vitesse, ou des probl`emes li´es `a la commande SELECT, pensez

`a inclure le r´esultat de la commande EXPLAIN SELECT ..., et au moins le nombre de ligne que la commande SELECT doit produire. Vous devriez aussi inclure le r´esultat de la commande SHOW CREATE TABLE table_name pour chaque table impliqu´ee. Plus vous nous fournirez d’informations, plus nous aurons de chance de vous aider efficacement.

Par exemple, voici un excellent rapport de bogue (post´e avec le script mysqlbug, et effectivement r´edig´e en ANGLAIS) :

Exemple r´ealis´e avec mysql en ligne de commande (notez l’utilisation de la fin de commande \G, pour les r´esultats qui pourraient d´epasser les 80 colonnes de large) :

mysql> SHOW VARIABLES;

mysql> SHOW COLUMNS FROM ...\G <output from SHOW COLUMNS> mysql> EXPLAIN SELECT ...\G

<output from EXPLAIN> mysql> FLUSH STATUS;

mysql> SELECT ...;

<A short version of the output from SELECT, including the time taken to run the query> mysql> SHOW STATUS;

<output from SHOW STATUS>

• Si un bogue ou un probl`eme survient lors de l’ex´ecution de mysqld, essayez de fournir

un script qui reproduit l’anomalie. Ce script doit inclure tous les fichiers sources n´ecessaires. Plus votre script reproduira fid`element votre situation, le mieux ce sera. Si vous pouvez r´ealiser un cas de test postez le sur la liste bugs@lists.mysql.com pour un traitement en priorit´e!

Si vous ne pouvez pas fournir de script, fournissez tout au moins le r´esultat de la com- mande mysqladmin variables extended-status processlist dans votre mail pour fournir des informations sur les performances de votre syst`eme.

• Si vous ne pouvez pas reproduire votre situation en quelques lignes, ou si une table de

test est trop grosse `a ˆetre envoy´ee par mail (plus de 10 lignes), exportez vos tables sous forme de fichier avec la commande mysqldump et cr´eez un fichier ‘README’ qui d´ecrit votre probl`eme.

Cr´eez une archive compress´ee de votre fichier en utilisant tar et gzip ou zip, et placez le via ftp sur le site de ftp://support.mysql.com/pub/mysql/secret/. Puis, envoyez une courte description de votre probl`eme `a bugs@lists.mysql.com.

• Si vous pensez que le serveur MySQL fournit des r´esultats ´etranges pour une requˆete,

incluez non seulement le r´esultat, mais aussi votre propre explication sur ce que le r´esultat devrait ˆetre, et un diagnostic de la situation.

• Lorsque vous donnez un exemple du probl`eme, il est mieux d’utiliser des noms de

variables et de tables qui existent dans votre situation, plutˆot que d’inventer de nou- veaux noms. Le probl`eme peut ˆetre li´e au noms des variables ou tables que vous utilisez! Ces cas sont rares, mais il vaut mieux ´eviter les ambiguit´es. Apr`es tout, il est plus facile pour vous de fournir un exemple qui utilise votre situation r´eelle, et c’est bien mieux pour nous aussi. Si vous avez des donn´ees que vous ne souhaitez pas divulguer, vous pouvez utiliser le site ftp pour les transf´erer dans le dossier secret ftp://support.mysql.com/pub/mysql/secret/. Si les donn´ees sont vraiment ultra secr`etes et que vous ne souhaitez mˆeme pas nous les montrer, alors utilisez d’autres noms et donn´ees pour votre rapport, mais consid´erez cela comme un dernier recours.

• Incluez toutes les options utilis´ees, si possible. Par exemple, indiquez les options que

comme mysqld et mysql, et le script configure, qui sont souvent primordiaux et pertinents. Ce n’est jamais une mauvaise id´ee que de les inclure. Si vous utilisez des modules, comme Perl ou PHP, incluez aussi les versions de ces logiciels.

• Si votre question porte sur le syst`eme de droits, incluez le r´esultat de l’utilitaire

mysqlaccess, celui de mysqladmin reload et tous les messages d’erreurs que vous obtenez lors de la connexion. Lorsque vous testez votre syst`eme de droits, il faut com- mencer par utiliser la commande mysqladmin reload version et de vous connecter avec le proramme qui vous pose probl`eme. mysqlaccess est situ´e dans le dossier ‘bin’ de votre installation de MySQL.

• Si vous avez un patch pour un bogue, c’est une excellente chose. Mais ne supposez pas

que nous n’avons besoin que du patch, ou mˆeme que nous allons l’utiliser, si vous ne fournissez pas les informations n´ecessaires pour le tester. Nous pourrions trouver des probl`emes g´en´er´es par votre patch, ou bien nous pourrions ne pas le comprendre du tout. Si tel est le cas, nous ne l’utiliserons pas.

Si nous ne pouvons pas v´erifier exactement ce pourquoi est fait le patch, nous ne l’utiliserons pas. Les cas de tests seront utiles ici. Montrez nous que votre patch va g´en´erer toutes les situations qui pourraient arriver. Si nous trouvons un cas limite dans lequel votre patche ne fonctionne pas, mˆeme si il est rare, il risque d’ˆetre inutile.

• Les diagnostics sur la nature du bogue, la raison de son d´eclenchement ou les effets

de bords sont g´en´eralement faux. Mˆeme l’´equipe MySQL ne peut diagnostiquer sans commencer par utiliser un d´ebogueur pour d´eterminer la cause v´eritable.

• Indiquez dans votre mail que vous avez v´erifi´e le manuel de r´ef´erence et les archives

de courrier, de fa¸con `a avoir ´epuiser les solutions que d’autres avant vous auraient pu trouver.

• Si vous obtenez un message parse error, v´erifiez votre syntaxe avec attention. Si vous

ne pouvez rien y trouvez `a redire, il est tr`es probable que votre version de MySQL ne supporte pas encore cette fonctionnalit´e que vous essayez d’utiliser. Si vous utilisez la version courante de mySQL et que le manuel http://www.mysql.com/doc/ ne couvre pas la syntaxe que vous utilisez, c’est que MySQL ne supporte pas votre syntaxe. Dans ce cas, vos seules options sont d’impl´ementer vous mˆeme la syntaxe ou d’envoyez un message `a licence@mysql.com pour proposer de l’impl´ementer.

Si le manuel pr´esente la syntaxe que vous utilisez, mais que vous avez une ancienne version du serveur MySQL, il est recommand´e de v´erifier l’historique d’´evolution de MySQL pour savoir quand la syntaxe a ´et´e support´ee. Dans ce cas, vous avez l’option de mettre `a jour votre MySQL avec une version plus r´ecente. Voir Annexe D [News], page 726.

• Si vous avez un probl`eme tel que vos donn´ees semblent corrompues, ou que vous re-

cevez constamment des errors lors d’acc`es `a une table, vous devriez commener par essayer de r´eparer votre table avec l’utilitaire de ligne de commande myisamchk ou les syntaxes SQL CHECK TABLE et REPAIR TABLE. Voir Chapitre 4 [MySQL Database Administration], page 192.

• Si vous avez des tables qui se corrompent facilement, il vous faut es- sayer de trouver quand et pourquoi cela arrive. Dans ce cas, le fichier ‘mysql-data-directory/’hostname’.err’ peut contenir des informations pertinentes qu’il est bon d’inclure dans votre rapport de bogues. Normalement, mysqld ne doit

jamais corrompre une table si il a ´et´e interrompu au milieur d’une mise `a jour. Si vous pouvez trouvez la cause de l’arrˆet de mysqld, il est bien plus facile pour nous de fournir un correctif. Voir Section A.1 [What is crashing], page 684.

• Si possible, t´el´echargez et installez la version la plus r´ecente du serveur MySQL, et

v´erifiez si cela r´esoud votre probl`eme. Toutes les versions de MySQL sont test´ees `a fond, et doivent fonctionner sans probl`eme. Nous croyons `a la compatibilit´e ascendante, et vous devriez pouvoir passer d’une version `a l’autre facilement. Voir Section 2.2.4 [Which version], page 76.

Si vous disposez de l’acc`es au support client, contactez aussi le support client `a mysql-support@mysql.com, en plus de la liste de rapport de bogues, pour un traitement prioritaire.

Pour des informations sur les rapports de bogues avec MyODBC, voyez Section 8.3.4 [ODBC Problems], page 602.

Pour des solutions aux probl`emes les plus courants, voyez Annexe A [Problems], page 684. Lorsque des solutions vous sont envoy´ees individuellement et non pas `a la liste, il est con- sid´er´e comme bien vu de rassembler ces r´eponses et d’en envoyer un r´esum´e sur le liste, de mani`ere `a ce que les autres en profitent aussi.