O histórico de commits deve ser usado para transmitir informações críticas aos desenvolvedores?

Se eu fosse analisar a atualização para uma versão mais recente de um SDK de terceiros, o último lugar que eu veria está no histórico do sistema de controle de origem.

Se o seu produto estiver usando a versão 2.0 de um SDK e alguém estiver interessado em atualizar para o 3.0, não acho razoável pensar que eles devam olhar para trás no tempo no sistema de controle de origem para descobrir que não é um boa ideia.

Aqui, temos um wiki de equipe com um punhado de páginas com informações interessantes que todo desenvolvedor lê (convenções de codificação, como configurar um ambiente de desenvolvimento para construir o produto, quais coisas de terceiros você precisa instalar, etc) . Este é o tipo de lugar que seria apropriado para um aviso contra a atualização de uma biblioteca de terceiros.

Deve-se notar no histórico de commits, mas o melhor lugar para colocar o aviso é no mesmo lugar em que você define a dependência. Se você tiver, por exemplo, um arquivo .pom maven que declare suas dependências de artefato, eu faria algo como:

<!-- Do not change the SDK version because it causes Foo crashes. For more detail see Issue #123 -->

Diretamente acima da sua linha <dependency> .

O problema # 123 inclui detalhes sobre como ele trava, a versão atualizada para o que causou as falhas e, provavelmente, deve ser adicionado à sua lista de pendências novamente para revisão posterior. É possível que haja uma versão mais recente que corrija o problema. Seja editando o ticket automaticamente ou manualmente, ele enviará um e-mail à equipe para informá-los sobre o problema atual e, ao estar no rastreador, permite que as pessoas o encontrem novamente mais tarde.

A razão para colocá-lo com a declaração de dependência é porque quem quiser mudar a versão, a verá no momento em que quiser alterá-la e entender por que não deveria.

Eu não gostaria de comentar no código-fonte porque posso facilmente imaginar uma situação em que alguém executa uma verificação nas suas dependências e começa a atualizá-las. Eles não devem precisar vasculhar a base de código para cada comentário TODO para fazer isso.

Vincular ao ticket de problema permite que um desenvolvedor curioso saiba como ele falhou e possivelmente o revisite mais tarde. Sem isso, pode se tornar bastante estático e nunca mais ser atualizado novamente.

As informações críticas e não intuitivas devem ser documentadas para onde as pessoas procurarão quando considerarem as informações.

Para as equipes e projetos em que trabalhei, eu enviaria a reversão com o comentário sobre por que a nova versão falhou. Eu adicionaria uma história de backlog para tentar novamente a atualização se a nova versão fosse corrigida. Eu adicionaria comentários ao sistema de compilação / scripts de construção em que a biblioteca está vinculada.

A reversão fornecerá aos futuros desenvolvedores um contexto ao analisarem o histórico do projeto. A história do backlog mantém a necessidade desse upgrade como parte ativa do projeto. Os comentários do sistema de compilação estão exatamente onde as alterações precisarão estar quando a biblioteca for finalmente atualizada.

Eu não o comentaria no código e não o adicionaria a um README. Os desenvolvedores que estão pensando em experimentar a atualização não estarão olhando para essas peças. Se você adicioná-lo lá, quando o problema com a biblioteca for eventualmente corrigido e uma atualização for concluída, será necessário removê-lo. Este passo é muitas vezes esquecido: resultando em notas que são contraproducentes para o projeto.

Se o seu projeto tiver uma configuração diferente ou um fluxo diferente, sua resposta poderá ser diferente. Eu acho que a chave é colocar a informação correta se o desenvolvedor a ver ao fazer o trabalho para a atualização. Dessa forma, se o momento não for adequado para a atualização, o desenvolvedor verá e parará, e quando for a hora certa, o desenvolvedor verá e removerá a nota para não confundir futuros desenvolvedores.

Eu queria dar Comentário de Matthew mais atenção, destacando sua idéia importante em uma resposta. Há uma razão pela qual você não deseja atualizar seu SDK e esse motivo deve ser capturado em um teste de unidade. Não é uma verificação de um número de revisão, mas o motivo real subjacente.

Por exemplo, digamos que haja um bug na nova versão. Escreva um teste de unidade que verifica esse bug. Se depois corrigirem esse bug no SDK, a atualização ocorrerá sem problemas. Se houver uma alteração de API incompatível, escreva um teste que verifique se o seu código é compatível com a nova API ou se o SDK oferece suporte à API antiga. Isso é mais um teste de integração do que um teste de unidade, mas ainda deve ser factível.

Minha empresa gera mais de 50 commits por dia e não somos exatamente grandes. Mesmo que todos os desenvolvedores leiam cada mensagem de commit, o que é óbvio que não precisamos, toda a razão pela qual precisamos de um histórico de commit gravado é porque as pessoas não conseguem se lembrar. E as pessoas não voltam e leem a história mais tarde, a menos que haja um problema. E eles não têm motivos para suspeitar de um problema em uma atualização que, até onde sabem, ainda não ocorreu.

Por todos os meios, envie um email para evitar a duplicação de trabalho a curto prazo e anote-o nos seus scripts de construção e num README ou errata. No entanto, especialmente se o problema com a nova versão for sutil e consome tempo para solucionar problemas, você precisa de uma maneira de torná-la óbvia. Isso significa um teste de unidade.

Estou reformulando a pergunta como "Devo comunicar informações críticas que descubro para o restante da equipe somente por meio de mensagens de confirmação?" Porque acho que isso torna óbvio que não, você não deveria. Eu tento me comunicar muito (isso é algo que a maioria das equipes de desenvolvimento, na minha experiência, precisa colocar um esforço ativo) e certamente faço tudo que posso para evitar criar armadilhas ou deixá-las mentir.

Se a cadeia de ações que me leva a tal descoberta fosse acionada por um ticket, eu atualizaria o ticket (e garanta que as pessoas que deveriam saber isso tenham visibilidade), eu provavelmente o mencionaria de cara a cara. face (na esperança de, pelo menos, deixar alguém com alguma sensação incômoda de que "Puxa, eu acho que Damon disse algo sobre atualizar isso"), e eu naturalmente deixaria um comentário no código no ponto em que o SDK foi incluído para que ninguém poderia atualizá-lo sem ter a chance de vê-lo. Eu poderia ver se eu poderia colocar isso em algum lugar em nossa wiki de desenvolvimento, também, embora isso seja feito mais com um olho para futuras contratações, não com a equipe atual.

Leva apenas mais alguns minutos em comparação com o tempo que provavelmente demorou a encontrar e a descobrir o problema. Eu certamente não decidi que uma das partes menos usadas e de baixo sinal da nossa documentação deixaria por aqui.

Ele deve estar no histórico de commits, mas não deve estar apenas no histórico de commits, imagine por um momento você contratar um novo desenvolvedor. Você espera que o novo desenvolvedor leia todas as mensagens de commit dos últimos 10 anos do seu projeto, porque alguns deles serão críticos para entender sua base de código?

Em segundo lugar, a situação, mas não o código muda, você vai fazer "documentação" commits para que você possa adicionar mensagens de commit ao longo das linhas de "commit message da revisão 5432 está incorreta agora, aqui está a situação atual."

Não sei ao certo como sua equipe se comunica, mas acredito que a maneira mais eficaz de dizer isso é primeiro enviar e enviar e-mail para o grupo de e-mail da equipe, marcado como "URGENTE" com o corpo dizendo

Guys, we can't use SDK v x.y.z because it causes the Foo buffer to overflow and the Bar service will crash. Stick with version x.y.y

Foi o que fizemos aqui e é a maneira mais confiável de divulgar a mensagem. Se você realmente quiser ser exigente (e se o seu sistema de e-mail permitir), solicite um "recibo de leitura" no e-mail.

Uma vez que você tenha contado a toda a equipe, uma documentação mais detalhada deve ser colocada em um wiki da equipe. Isso irá variar, dependendo de como você estrutura sua documentação. Se você tiver uma seção específica para suas dependências e requisitos, isso seria um bom lugar para adicioná-la.

Um local adicional para documentar esse tipo de problema pode estar no próprio código-fonte, embora isso nem sempre funcione. Se SDK version ... for referenciado apenas em um ou dois lugares óbvios, você poderá incluir uma observação sobre não atualizar.

O histórico de arquivos no controle de origem pode ser muito longo e, dependendo dos desenvolvedores, pode ter várias entradas por dia. Alguém que tenha saído de férias por uma semana pode não ter tempo para ler o histórico de uma semana de commits. O arquivo README é um lugar melhor, já que é um pouco mais central e as pessoas podem estar mais inclinadas a lê-lo, mas você não pode garantir que todos realmente lerão o README. Bem, suponho que eles possam se virem que foi alterado ...

Algo como isso deveria ter sido colocado nos comentários de commit, mas também será beneficiado por estar em outros lugares.

Quem quer que tome a decisão de atualizar, precisa ter os fatos. Essa pessoa não pode viver no controle de origem. E se alguém tivesse lido sobre esse problema em SO e nunca o colocasse na base de código?

É necessário haver algum tipo de documento sobre esse SDK de terceiros.

• Qual problema isso resolve?
• Por que esse em particular foi escolhido?
• Quais considerações precisam ser feitas em relação a: versões, upgrades, testes, etc.
• Quem toma essa decisão?

Você tem um caso em que algo assim entrou no controle de versão e recomendamos que todos usem essas informações o máximo possível. Apenas sua equipe pode decidir onde alguém fará uma pesquisa em qualquer documentação, controle de origem ou rastreador de bugs para obter o máximo de informações possível sobre o assunto. Caso contrário, você esquecerá, alguém fará isso de qualquer maneira, e você terá sorte se isso fizer com que a memória de alguém aconteça e volte rapidamente.

A história é um ótimo lugar para colocar dados destinados a um leitor que está conscientemente procurando por ele, e tem um senso geral de onde deveria estar. É um lugar muito ruim para colocar dados que devem ser oferecidos a um usuário, em vez de pesquisados.

Histórias são corpos muito grandes de texto relativamente não classificado. Eles geralmente destinam-se a fornecer ao desenvolvedor informações detalhadas sobre o que mudou e por que ele foi alterado. Isso pode ser uma sobrecarga de informações, a menos que se saiba o que eles estão procurando.

Se um usuário não souber o que está procurando, as informações serão rapidamente armazenadas em centenas de logs de confirmação e não haverá ferramentas para remover a pilha de informações à sua frente.

Eu interpreto essa situação como tendo dois problemas básicos, possivelmente três.

• Um upgrade de SDK indesejado chegou à origem, onde poderia afetar negativamente o produto.
• Da pergunta: o colaborador que realizou o upgrade indesejado não sabia sobre uma decisão específica anterior de não fazer upgrade.

O primeiro deles, na minha opinião, é o mais sério. Se uma atualização indesejada do SDK puder ser incluída no código, outros problemas também podem ocorrer.

Alguém sugeriu adicionar um caso de teste de unidade que falhará se detectar a atualização. Embora isso impeça a atualização, creio que esse é um caminho perigoso, levando a fluxo de lava Tempo. Parece inevitável que, em algum momento no futuro, o SDK será atualizado, para trazer novos recursos ou correções de bugs, ou porque a versão antiga não é mais suportada. Imagine os arranhões na cabeça, talvez até os argumentos, que ocorrerão quando esse teste de unidade falhar.

Acho que a solução mais geral é ajustar o processo de desenvolvimento. Para git, use o processo de solicitação de pull . Para ferramentas do Subversion e mais antigas, use ramificações e diff. Mas tem algum processo que permite aos desenvolvedores seniores pegar esses tipos de problemas antes eles entrarem na base de código e afetar outros desenvolvedores.

Se o processo de solicitação pull tiver sido usado em sua situação e se cada solicitação de recebimento for restrita e específica, pouco tempo teria sido desperdiçado. Um pedido de pull para atualizar o SDK teria sido enviado e recusou com comentários que a atualização não é desejada. Ninguém mais teria sido afetado e não haveria necessidade de reverter a atualização do SDK.

Mas para responder diretamente a pergunta original, eu concordo com outros que esperar que todos os desenvolvedores leiam completamente o histórico de revisão do código, notas de versão, etc. para avisos como este é um desperdício de tempo valioso. O que há de errado com um e-mail curto da equipe?

Possível terceira questão: por que a atualização não é desejada em primeiro lugar? Claramente, pelo menos, um desenvolvedor pensou que a atualização seria uma coisa boa. Há muitas boas razões para atrasar uma atualização, mas também muitas más. Tome cuidado para evitar o fluxo de lava (código desnecessário de compatibilidade retroativa) e cult de carga ("não podemos atualizar isso, mas eu não sei porque ") antipadrões!

Eu diria que adicionar esse tipo de informação a um histórico de commits é ok, mas ainda precisa ser documentado corretamente. Recentemente, começamos a usar a confluência (pelo atlasiano). É pesquisável, você pode definir determinadas páginas como favoritos, etc.

Algumas outras ferramentas podem ser um bloco de anotações público no evernote ou no google docs.

Expandindo a resposta de Karl , eu escolheria uma abordagem que impõe automaticamente a restrição como parte do check-in processo em si. Você precisa de algo que não requer nenhuma ação proativa em nome do desenvolvedor, como ler um doc / wiki / README e não pode ser substituído secretamente.

No terreno de controle de origem do TFS, você pode codificar as políticas de entrada personalizadas que executam as regras de check-in. Por exemplo, você poderia definir uma política que avalia a versão em um arquivo de configuração com um check-in pendente e falhará se não for igual a x.y.z. Essas regras, na verdade, impedem que o desenvolvedor execute o check-in e pode fornecer uma mensagem descritiva. As políticas podem ser substituídas, mas é possível gerar alertas quando isso acontece.

Uma alternativa pode ser um check-in bloqueado que falhará com alguma forma de teste unitário que avalie direta ou indiretamente a versão do SDK, como Karl mencionou.

Aprecio que esta resposta seja muito centrada no TFS, mas possivelmente existem recursos similares nos sistemas de controle de versão / CI que se aplicam à sua situação (se não no TFS).