Pourquoi la citation d'ID de bogue dans les notes de mise à jour peut-elle être considérée comme une mauvaise pratique?

28

Sur la base d' un commentaire et des votes positifs ultérieurs de Bug ropen vs. new :

Citer les identifiants de bogues dans les notes de mise à jour est tout simplement ... très hostile. - Krelp

Il semble qu'au moins certaines personnes pensent que référencer les ID de bogues dans les notes de mise à jour n'est pas une bonne idée. Je suis un développeur assez inexpérimenté, alors je me demande pourquoi c'est le cas.

issue-tracking bug-report software-patches

— Travis Northcutt
source

27

ne pas citer d' ID de bogue dans les notes de mise à jour est juste ... très peu professionnel. Sorte de la corbeille le point d'avoir un tracker de problème

— gnat

La même raison pour laquelle publier uniquement des liens en tant que réponses StackExchange est désapprouvée - si vous ne publiez qu'un lien, sur SE c'est mauvais car il (1) nécessite de suivre pour obtenir une explication et (2) peut devenir invalide à l'avenir si le lien meurt ou le contenu change. De même, ne mettre que des ID de bogue dans les notes de mise à jour (1) nécessite d'aller au dépisteur de bogues pour obtenir une explication et (2) peut devenir invalide à l'avenir si un système de suivi des bogues change. L'inclusion d'un lien dans une réponse SE ou d'un ID de bogue dans une note de patch est une bonne chose (et en fait une bonne pratique) en complément d'une explication régulière.

— Ben Lee

51

À mon avis, c'est une bonne pratique, en supposant que vos utilisateurs ont un accès en lecture à votre base de données de bogues. Il y a de nombreuses fois où les gens attendent qu'un bug particulier soit corrigé pour décider quand mettre à jour.

Je pense que ce qui est mal vu ne cite que l'identifiant du bug et rien d'autre. Vous devez également toujours fournir une description compréhensible sans passer par le suivi des bogues. Cela vous permet également de changer de suivi des bogues à l'avenir sans invalider entièrement vos notes de version précédentes.

— Karl Bielefeldt
source

Vous pouvez citer via un résolveur de référence abstrait, ou redirection d'URL.

— Donal Fellows

Comme vous le dites, la section "Bogues corrigés" (ou similaire) doit inclure l'ID et le titre afin que le lecteur n'ait pas à rechercher le bogue pour comprendre exactement ce qui est inclus et ce qui ne l'est pas.

— StuperUser

5

@StuperUser - Identifiant et titre, au minimum .

— Odé

Ce qui est ennuyeux, c'est de trouver uniquement des notations d'ID de bogue dans les commentaires lorsque le système d'ID de bogue / d'exigence référencé n'est plus utilisé.

— jfrankcarr

14

Il est, comme dit dans le commentaire cité ... hostile.

Peu amical avec vous-même

Imaginez le scénario suivant. Vous consultez les journaux dans le contrôle de code source. Vous vous demandez ce qu'un changement a changé. Au lieu de l'expliquer en anglais simple, il vous dit:

Résolu # 1307

Vous exécutez le système de suivi des bogues, en espérant avoir quelque chose d'utile. Le bogue n ° 1307 est signalé comme résolu. Dans la description, vous voyez:

Même bug que # 1284

Merci, c'est très utile. Vous devez maintenant accéder au rapport de bogue # 1284 pour lire qu'il s'agit d'un doublon du bogue # 1113 qui fait référence aux bogues # 1112, # 1065 et # 1067.

Cinq minutes plus tard, vous n'avez aucune idée de ce que vous recherchez au début.

Un message de journal de contrôle de version beaucoup plus utile serait:

Résolution d'un problème empêchant les utilisateurs de se connecter avec un mot de passe de plus de 25 caractères (voir # 1307), en supprimant l'application de la même politique de longueur de mot de passe à la couche d'accès aux données que celle utilisée dans le site Web lui-même.

De la même manière, dans le système de suivi des bogues, le rapport # 1307 pourrait être plus explicite , rappelant en quoi consistait le rapport de bogue # 1284 et en quoi le nouveau est différent de l'ancien.

Peu amical avec les clients

Ce n'est pas le seul problème de convivialité.

Un deuxième est qu'en faisant trop de références sans informations supplémentaires, vous rendez les notes de patch / journaux de contrôle de version / rapports de système de suivi des bogues inutilisables pour quelqu'un qui n'est pas très familier avec ces systèmes . Lorsque vous traitez quotidiennement avec un système de suivi des bogues, vous savez comment naviguer rapidement dans les rapports, afficher plusieurs rapports côte à côte, etc. Lorsque vous êtes un client sans expérience technique, vous pouvez facilement vous perdre.

Là encore, des messages plus détaillés sont très utiles qu'une simple référence. Notez que vous souhaitez toujours conserver les références: rien n'est plus faux qu'un bug qui est le même qu'un bug que vous avez rencontré il y a deux semaines, mais ne vous souvenez pas de son ID.

À noter que le même problème existe dans de nombreuses juridictions. En France par exemple, il n'est pas rare qu'une législation fasse référence à de multiples sources, qui peuvent évoluer entre-temps. Cela signifie que pour le comprendre complètement, vous devez parfois passer des heures dans une bibliothèque, à rechercher des dizaines de textes référencés, chaque texte ayant ses propres références aux autres.

— Arseni Mourzenko
source

5

Ce n'est pas un problème avec le document de sortie; c'est un problème avec le niveau de détail des bugs. Un titre doit décrire le problème réel et le corps de chaque bogue a le résultat attendu et le résultat réel. Les bogues comme vous l'avez décrit ne devraient-ils pas être fermés en tant que doublons?

— StuperUser

Basé sur votre modification. Vous avez cité l'ID dans votre message beaucoup plus utile. Vouliez-vous dire dans votre commentaire original que citer UNIQUEMENT les identifiants sans autre information est inutile, alors qu'une explication appropriée ET l'identifiant sont utiles?

— StuperUser

1

@StuperUser: exactement. Fournir des explications aide les personnes qui veulent simplement savoir de quoi parle le journal de validation / la note de patch / le rapport de bogue, sans passer dix minutes à lire le contenu référencé. Les identifiants sont toujours nécessaires pour le suivi et les personnes qui ont besoin d'informations très détaillées, précises et complètes.

— Arseni Mourzenko

2

Il n'y a rien de mal à citer les numéros de problème dans les notes de mise à jour, à condition que les utilisateurs puissent lire le problème cité. Si votre base de données de bogues permet à quiconque de lire, citer le numéro de bogue peut être très utile. (Mieux encore, si vos notes de mise à jour sont dans un format qui autorise les liens, faites que ces ID de problème soient des liens vers le problème en question.) Cela ne signifie pas que vous devez exposer tous les problèmes au grand public; il peut toujours être utile d'en avoir des qui sont enveloppés (par exemple, où ils ont des mots de passe en direct!)

Citer un numéro de problème où la personne qui lit ne peut pas aller chercher les détails et l'historique du bogue, c'est assez hostile. Ce n'est pas que citer de tels problèmes sans l'ID du problème est beaucoup plus convivial.

— Associés Donal
source

"là où la personne qui lit ne peut pas aller chercher les détails" comme quelqu'un qui a été une telle personne , je n'appellerais pas cela vraiment hostile. J'ai utilisé l'ID de problème pour communiquer avec l'équipe de support / développement qui à son tour avait accès au suivi des problèmes. Le fait qu'il était invisible pour moi personnellement n'était qu'une gêne mineure

— moucher

2

Cela dépend évidemment de qui sont les personnes qui liront les notes de mise à jour et les utilisateurs cibles du logiciel.

Mais dans la plupart des cas, la grande majorité de vos utilisateurs ne se soucient tout simplement pas de l'ID du bogue. Ils ne se soucient pas de la raison pour laquelle il a été cassé, de la nature du correctif ou de toute autre chose - ils veulent seulement savoir ce qui a changé avec une description textuelle très succincte sans avoir à aller sur une autre page pour chaque changement.

Citer les ID de bogue me fait arrêter et réfléchir, et moi, en tant qu'utilisateur, je ne veux pas penser. C'est en quelque sorte un problème de convivialité.

Jetez un oeil par exemple au journal des modifications de Visual Assist X . Tous ces ID de bogue liés ne sont que du bruit qui me distrait de comprendre ce qui a changé. Et ceci est un module complémentaire pour Visual Studio, ciblant les programmeurs. Et je suis programmeur. Si cela me dérange, imaginez l'utilisateur moyen qui ne sait même pas ce qu'est un traqueur de bogues.

PS: j'étais l'auteur du commentaire qui a déclenché la question

— Thomas Bonini
source

1

Honnêtement, je trouve la documentation à la fin de ce lien utile. Il commence par un résumé puis me dirige vers les détails. Microsoft fait souvent un lien similaire dans les articles de la base de connaissances, non pas que le faire soit une bonne pratique, mais il est certainement répandu et offre apparemment de la valeur à de nombreux utilisateurs.

— Joshua Drake

1

Un ID de bogue est obligatoire pour un point de référence . Les raisons:

Empêchez toute ambiguïté: deux bogues ou plus peuvent avoir des descriptions similaires. Il faudrait donc un ancrage pour les distinguer.
Commodité : lorsque vous discutez d'un bogue, soit avec un client, soit en interne, l'ID de bogue est souvent utilisé sous forme abrégée. Si l'ID sera omis des notes de mise à jour, il sera difficile d'en discuter:

3052 était déjà réparé, fonctionnait toujours sur 3077

est plus pratique que:

Le «blocage de l'application sur le bouton Appliquer» a été corrigé, fonctionnant toujours sur «NullReferenceException en cliquant sur changer d'utilisateur»

— KMoraz
source

(1) Qu'est-ce qui vous empêche de le combiner, comme l'a suggéré MainMa? (2) Pourquoi commettez-vous un bogue et demi corrigé? Pourquoi ne vous engagez-vous pas après la correction de 3052, avant même de commencer à travailler sur 3077?

— JensG

0

Je dirais que cela dépend de votre système: j'ai de la chance que celui que j'utilise détecte automatiquement ces références dans les messages de commit et ajoute un lien vers le ticket stocké dans le bug tracker, donc ce n'est pas un problème.

Mais si j'étais sur un système où il n'est pas disponible, je mentionnerais toujours l'ID du ticket (de cette façon, vous pouvez rechercher rapidement dans les journaux par ID de ticket ) ainsi qu'une brève description de ce qu'est le bogue.

— pics sauvages
source