Por que citar IDs de bug em notas de correção pode ser considerado uma prática ruim?

Com base em um comentário e upvotes subsequentes de Bug reopen vs. new :

Citar IDs de bug em notas de atualização é simplesmente muito hostil. - Krelp

Parece que pelo menos algumas pessoas acham que fazer referência a IDs de bug nas notas de patch não é uma boa ideia. Eu sou um desenvolvedor bastante inexperiente, então estou me perguntando por que esse é o caso.

Na minha opinião, é uma boa prática, supondo que seus usuários tenham acesso de leitura ao seu banco de dados de bugs. Muitas vezes as pessoas esperam que um determinado bug seja corrigido para decidir quando atualizar.

Eu acho que o que é desaprovado é apenas citar o ID do bug e nada mais. Você também deve sempre fornecer uma descrição que seja compreensível sem acessar o rastreador de erros. Isso também permite que você troque os rastreadores de erros no futuro sem invalidar completamente suas notas de versão anteriores.

É, como dito no comentário citado ... hostil.

Hostil consigo mesmo

Imagine o seguinte cenário. Você está visualizando os logs no controle de origem. Você está se perguntando o que um commit mudou. Em vez de explicá-lo em inglês simples, ele diz:

Resolvido # 1307

Você executa o sistema de rastreamento de bugs, esperando ter algo útil. O bug # 1307 é relatado como resolvido. Na descrição, você vê:

Mesmo bug que # 1284

Obrigado, é muito útil. Agora você tem que navegar para o relatório de bug # 1284 para ler que é uma duplicata do bug # 1113, que se refere aos erros # 1112, # 1065 e # 1067.

Cinco minutos depois, você não tem idéia do que está procurando no início.

Uma mensagem de log de controle de versão muito mais útil seria:

Solucionado um problema com o fato de os usuários não conseguirem fazer logon com uma senha com mais de 25 caracteres (consulte o número 1307), removendo a aplicação da mesma política de comprimento de senha na camada de acesso a dados usada na própria página.

Da mesma forma, no sistema de rastreamento de erros, o relatório # 1307 poderia ser mais auto-explicativo , lembrando sobre o que era o relatório de erros # 1284 e como o novo é diferente do antigo.

Não amigável com os clientes

Este não é o único problema de amizade.

Um segundo é que, ao fazer uma referência demais sem informações adicionais, você está tornando os relatórios das notas de correção / logs de controle de versão / sistema de rastreamento de erros inutilizáveis ​​para alguém não familiarizado com esses sistemas . Quando você lida com um sistema de rastreamento de erros diariamente, sabe como navegar rapidamente pelos relatórios, exibir vários relatórios lado a lado etc. Quando você é um cliente sem formação técnica, pode se perder facilmente.

Aqui, novamente, mensagens mais detalhadas são muito úteis do que apenas uma referência. Observe que você ainda deseja manter as referências: nada está mais errado do que um bug que é o mesmo que você encontrou duas semanas atrás, mas não lembre seu ID.

Como nota, o mesmo problema existe em muitas jurisdições. Na França, por exemplo, não é incomum que uma legislação se refira a várias fontes, o que pode mudar enquanto isso. Isso significa que, para entendê-lo completamente, você precisa passar algumas horas em uma biblioteca, pesquisando dezenas de textos referidos, cada um com suas próprias referências a outros.

Não há nada de errado em citar números de problemas nas notas de correção, desde que os usuários possam ler o problema que está sendo citado. Se o seu banco de dados de erros permitir que alguém leia, citar o número do erro pode ser muito útil. (Melhor ainda, se as notas de correção estiverem em um formato que permita links, faça com que os IDs dos problemas sejam links para o problema em questão.) Isso não significa que você deve expor todos os problemas ao público em geral; ainda pode ser útil ter aqueles que estão ocultos (por exemplo, onde eles têm senhas ativas!)

Citar um número de problema em que a pessoa que está lendo não pode ir e procurar os detalhes e o histórico do bug, isso é bastante hostil. Não que citar esses problemas sem o ID do problema seja muito mais amigável.

Obviamente, depende de quem são as pessoas que lerão as notas do patch e os usuários-alvo do software.

Mas na maioria dos casos, a grande maioria dos usuários simplesmente não se importa com o que é o ID do bug. Eles não se importam com o motivo da falha, qual é a correção ou qualquer outra coisa - eles só querem saber o que mudou com uma descrição textual muito sucinta, sem precisar ir para outra página para cada alteração.

Citar os IDs de bugs me faz parar e pensar, e eu - como usuário - não quero pensar. É uma questão de usabilidade.

Dê uma olhada por exemplo, no log de alterações de Visual Assist X . Todos esses IDs de bug vinculados são apenas ruídos que me distraem da compreensão do que mudou. E este é um complemento para o Visual Studio, direcionado a programadores. E eu sou um programador. Se isso me incomoda, imagine o usuário médio que nem sabe o que é um rastreador de erros.

PS: Eu fui o autor do comentário que provocou a pergunta

Um ID de bug é obrigatório para um ponto de referência . As razões:

• Evitar ambiguidade: dois ou mais bugs podem ter descrições semelhantes. Então, seria preciso alguma âncora para distinguir entre eles.
• Conveniência : ao discutir um bug, seja com um cliente ou internamente, o ID do bug é frequentemente usado como um formato abreviado. Se o ID for omitido nas notas do patch, será difícil discutir sobre elas:

3052 já estava corrigido, ainda trabalhando no 3077

é mais conveniente do que:

A "falha do aplicativo no botão Aplicar" foi corrigida, ainda trabalhando na "NullReferenceException ao clicar em alterar usuário"

Eu diria que depende do seu sistema: tenho sorte que o que eu uso detecta automaticamente essas referências nas mensagens de confirmação e adiciona um link ao ticket armazenado no rastreador de erros, por isso não é um problema.

Mas se eu estivesse em um sistema em que ele não estivesse disponível, ainda mencionaria o ID do ticket (dessa forma, você pode pesquisar rapidamente nos logs por ID do ticket ), juntamente com uma breve descrição do que é o erro.