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

28

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.

Travis Northcutt
fonte
27
não citar IDs de bug nas notas de atualização é apenas ... muito pouco profissional. Tipo de lixo o ponto inteiro de ter um rastreador de problemas #
30612
O mesmo motivo pelo qual a postagem de links apenas como respostas do StackExchange é desaprovada - se você postar apenas um link, o SE é ruim porque (1) exige o seguinte para obter uma explicação e (2) pode se tornar inválido no futuro se o link morre ou o conteúdo muda. Da mesma forma, colocar apenas IDs de bug nas notas do patch (1) requer que o rastreador de erros obtenha uma explicação e (2) pode se tornar inválido no futuro se um sistema do rastreador de erros mudar. Incluir um link em uma resposta do SE ou um ID de bug em uma nota de patch é bom (e realmente é uma boa prática) como um complemento a uma explicação regular.
21712 Ben Lee

Respostas:

51

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.

Karl Bielefeldt
fonte
You can cite via an abstract reference resolver, a.k.a. URL redirect.
Donal Fellows
Como você diz, a seção "Bugs corrigidos" (ou similar) deve incluir o ID e o título para que o leitor não precise procurar o bug para entender exatamente o que está incluído e o que não está.
StuperUser
5
@StuperUser - ID e título, no mínimo .
Oded
O que é irritante é encontrar apenas notações de ID de bug nos comentários quando o sistema de ID de requisito de bug / requisito não estiver mais em uso.
jfrankcarr
14

É, 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.

Arseni Mourzenko
fonte
5
Isso não é um problema com o documento de lançamento; isso é um problema com o nível de detalhe nos bugs. Um título deve descrever o problema real e o corpo de cada erro tem Resultado Esperado e Resultado Real. Os bugs que você descreveu não devem ser fechados como duplicados?
StuperUser
Com base na sua edição. Você citou o ID na sua mensagem muito mais útil. Você quis dizer em seu comentário original que citar SOMENTE os IDs sem informações adicionais não ajuda, enquanto uma explicação adequada E o ID são úteis?
StuperUser
11
@StuperUser: exatamente. Fornecer explicação ajuda as pessoas que querem apenas saber do que se trata o relatório de registro / nota de correção / relatório de erros, sem gastar dez minutos lendo o conteúdo referenciado. Os códigos ainda são necessários para o rastreamento e as pessoas que precisam de informações muito detalhadas, precisas e completas.
Arseni Mourzenko 30/03/12
2

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.

Donal Fellows
fonte
"onde a pessoa que lê não pode procurar os detalhes" como alguém que foi uma pessoa assim , eu não consideraria isso hostil. Usei o ID do problema para me comunicar com o suporte / equipe de desenvolvimento que, por sua vez, tinha acesso ao rastreador de problemas. O fato de que ele era invisível para mim, pessoalmente, foi apenas um menor incómodo
mosquito
2

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

Thomas Bonini
fonte
11
Honestamente, acho a documentação no final desse link útil. Começa com um resumo e depois me direciona para os detalhes. A Microsoft geralmente faz um vínculo semelhante nos artigos da base de conhecimento, não que isso a torne uma boa prática, mas certamente é generalizada e, aparentemente, agrega valor a muitos usuários.
27412 Joshua Drake
1

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"

KMoraz
fonte
(1) O que impede você de combiná-lo, como sugerido pela MainMa? (2) Por que você está cometendo um erro e meio de correção? Por que você não confirma após 3052 ter sido corrigido, antes mesmo de começar a trabalhar no 3077?
JensG
0

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.

picos selvagens
fonte