Comment rédiger une bonne <i> issue </i>

Lorsque vous rencontrez un problème avec l’une des bibliothèques d’Hugging Face, faites le nous savoir afin que nous puissions le corriger (il en va de même pour toute bibliothèque open source).
Si vous n’êtes pas complètement certain que le bug se trouve dans votre propre code ou dans l’une de nos bibliothèques, le premier endroit à vérifier est le forum. La communauté vous aidera à résoudre votre problème et l’équipe d’Hugging Face y suit de près les discussions qui s’y déroulent.

Lorsque vous êtes sûr d’avoir identifier un bug, la première étape consiste à construire un exemple minimal qui soit reproductible.

Créer un exemple minimal reproductible

Il est très important d’isoler le morceau de code qui produit le bug car personne dans l’équipe d’Hugging Face n’est (encore) un magicien et on ne peut pas réparer ce qu’on ne peut pas voir. Un exemple minimal reproductible doit, comme son nom l’indique, être reproductible. Cela signifie qu’il ne doit pas dépendre de fichiers ou de données externes que vous pourriez avoir. Essayez de remplacer les données que vous utilisez par des valeurs fictives qui ressemblent à vos valeurs réelles et qui produisent toujours la même erreur.

Une fois que vous avez quelque chose d’autonome, essayez de le réduire au moins de lignes de code possible, en construisant ce que nous appelons un exemple reproductible minimal. Bien que cela nécessite un peu plus de travail de votre part, vous serez presque assuré d’obtenir de l’aide et une correction si vous fournissez un exemple reproductible court et agréable.

Si vous vous sentez suffisamment à l’aise, allez inspecter le code source où se trouve votre bug. Vous trouverez peut-être une solution à votre problème (dans ce cas, vous pouvez même suggérer une pull request pour le corriger), mais plus généralement, cela peut aider les mainteneurs à mieux comprendre le code source lorsqu’ils lisent votre message.

Remplir le gabarit de problème

Lorsque vous ouvrerez votre issue vous remarquerez qu’il y a un gabarit à remplir. Nous suivrons ici celui pour la bibliothèque 🤗 Transformers mais le même type d’information sera requis dans un autre dépôt. Ne laissez pas le gabarit vide : prendre le temps de le remplir maximisera vos chances d’obtenir une réponse et de résoudre votre problème.

En général, lorsque vous signalez un problème, restez toujours courtois. Il s’agit d’un projet open source, vous utilisez donc un logiciel libre, et personne n’est obligé de vous aider. Vous pouvez inclure dans votre issue des critiques qui vous semblent justifiées mais les mainteneurs pourraient très bien les prendre mal et ne pas être pressés de vous aider. Assurez-vous de lire le code de conduite du projet.

Inclure les informations sur votre environnement

🤗 Transformers fournit un utilitaire pour obtenir toutes les informations nécessaire concernant votre environnement. Il suffit de taper ce qui suit dans votre terminal :

transformers-cli env

et vous devriez obtenir quelque chose comme :

Copy-and-paste the text below in your GitHub issue and FILL OUT the two last points.

- `transformers` version: 4.12.0.dev0
- Platform: Linux-5.10.61-1-MANJARO-x86_64-with-arch-Manjaro-Linux
- Python version: 3.7.9
- PyTorch version (GPU?): 1.8.1+cu111 (True)
- Tensorflow version (GPU?): 2.5.0 (True)
- Flax version (CPU?/GPU?/TPU?): 0.3.4 (cpu)
- Jax version: 0.2.13
- JaxLib version: 0.1.65
- Using GPU in script?: <fill in>
- Using distributed or parallel set-up in script?: <fill in>

Vous pouvez également ajouter un ! au début de la commande transformers-cli env pour l’exécuter depuis une cellule de notebook puis copier et coller le résultat au début de votre issue.

Taguer des personnes

Taguer des personnes en tapant un @ suivi de leur identifiant GitHub leur enverra une notification afin qu’elles voient votre problème et puissent répondre plus rapidement. Néanmoins utilisez cette fonction avec modération car les personnes que vous taguez peuvent ne pas apprécier d’être notifiées si elles n’ont pas de lien direct avec le problème. Si vous avez regardé les fichiers sources liés à votre bug, vous devriez taguer la dernière personne qui a fait des changements à la ligne que vous pensez être responsable de votre problème (vous pouvez trouver cette information en regardant ladite ligne sur GitHub, en la sélectionnant, puis en cliquant sur « View git blame »).

Sinon, le gabarit propose des suggestions de personnes à taguer. En général, ne marquez jamais plus de trois personnes !

Inclure un exemple reproductible

Si vous avez réussi à créer un exemple autonome qui produit le bug, il est temps de l’inclure ! Tapez une ligne avec trois backticks suivis de python, comme ceci :

```python

puis collez votre exemple minimal reproductible et tapez une nouvelle ligne avec trois backticks. Cela permettra de s’assurer que votre code est correctement formaté.

Si vous n’avez pas réussi à créer un exemple reproductible, expliquez en des étapes claires comment vous êtes arrivé à votre problème. Si vous le pouvez, incluez un lien vers un notebook d’un Google Colab où vous avez trouvé l’erreur. Plus vous partagerez d’informations, plus les mainteneurs seront en mesure de vous répondre.

Dans tous les cas, vous devez copier et coller l’intégralité du message d’erreur que vous obtenez. Si vous travaillez dans Colab, n’oubliez pas que certaines cellules peuvent être automatiquement réduites dans la trace de la pile et veillez donc à les afficher avant de les copier. Comme pour l’exemple de code, placez le message d’erreur entre deux lignes avec trois backticks afin qu’il soit correctement formaté.

Décrire le comportement attendu

Expliquez en quelques lignes ce que vous vous attendiez à obtenir afin que les mainteneurs comprennent bien le problème. Cette partie est généralement assez évidente, elle devrait donc tenir en une seule phrase mais dans certains cas vous pouvez avoir beaucoup à dire.

Et ensuite ?

Une fois que votre problème est classé, vérifiez rapidement que tout est en ordre. Vous pouvez modifier le problème si vous avez fait une erreur ou même changer son titre si vous vous rendez compte que le problème est différent de ce que vous pensiez initialement.

Il est inutile d’envoyer des messages aux personnes concernées si vous n’obtenez pas de réponse. Si personne ne vous aide au bout de quelques jours, il est probable que personne n’a pu donner un sens à votre problème. N’hésitez pas à revenir à l’exemple reproductible. Pouvez-vous le rendre plus court et plus concis ? Si vous n’obtenez pas de réponse au bout d’une semaine, vous pouvez laisser un message demandant gentiment de l’aide, surtout si vous avez modifié votre question pour inclure plus d’informations sur le problème.