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

Durante uma reunião sobre a reversão de um SDK de terceiros da versão mais recente, notou-se que nossos desenvolvedores já sinalizaram no histórico de confirmação que a versão mais recente não deveria ser usada.

Alguns desenvolvedores argumentaram que essa era uma prática ruim e, em vez disso, deveria ter sido observada no arquivo de origem (ou seja // Don't upgrade SDK Version x.y.z, see ticket 1234) ou no READMEarquivo no nível do projeto . Outros argumentaram que, como o histórico de consolidação faz parte da documentação do projeto, é um local aceitável para essas informações, pois todos nós devemos lê-los de qualquer maneira.

O histórico de consolidação deve ser usado para transmitir informações críticas a outros desenvolvedores ou essas informações devem ser duplicadas para outro local, como um projeto READMEou comentários no arquivo de origem relevante?

Se eu gostaria de atualizar para uma versão mais recente de um SDK de terceiros, o último lugar que eu procuraria seria 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 é uma boa ideia.

Aqui, temos um wiki de equipe que possui várias 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, que material de terceiros você precisa instalar, etc.). Esse é o tipo de local que seria apropriado para um aviso contra a atualização de uma biblioteca de terceiros.

Deve ser observado no histórico de consolidação, mas o melhor lugar absoluto para colocar o aviso é no mesmo local em que você define a dependência. Se você tem, por exemplo, um arquivo .pom maven que declara 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 <dependency>linha.

O problema nº 123 incluiria detalhes sobre como falha, a versão que você atualizou para a causa e provavelmente deve ser adicionado ao seu backlog novamente para revisar mais tarde - é possível que exista uma versão mais nova que corrija o problema. Automaticamente, editando o ticket ou manualmente você mesmo, ele enviará um e-mail à equipe para que eles saibam sobre o problema atual agora e, ao estar no rastreador, permite que as pessoas o encontrem novamente mais tarde.

O motivo para colocá-lo com a declaração de dependência é que quem quiser alterar a versão o verá no momento em que deseja alterá-lo e entender por que não deveria.

Eu não comentaria no código-fonte, porque posso imaginar facilmente uma situação em que alguém verifica suas dependências e começa a atualizá-las. Eles não precisam vasculhar a base de código para todos os comentários do TODO para fazer isso.

A vinculação ao ticket de emissão permite que um desenvolvedor curioso saiba como ele falhou e o revise potencialmente mais tarde. Sem isso, pode ficar bastante estático e nunca mais ser atualizado.

Informações críticas e não intuitivas devem ser documentadas para onde as pessoas estarão olhando ao considerar as informações.

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

A reversão fornecerá aos futuros desenvolvedores um contexto ao analisar o histórico do projeto. A história da lista de pendências mantém a necessidade dessa atualização como parte ativa do projeto. Os comentários do sistema de construção estão exatamente onde as alterações precisarão estar quando a biblioteca for finalmente atualizada.

Eu não comentaria no código e não o adicionaria a um README. Os desenvolvedores que pensam em tentar a atualização não analisarão essas peças. Se você o adicionar lá, quando o problema com a biblioteca for resolvido e a atualização for concluída, será necessário removê-lo. Esta etapa é frequentemente esquecida: 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. Acho que a chave é colocar as informações corretamente, caso o desenvolvedor as veja ao fazer o trabalho para a atualização. Dessa forma, se não for o momento certo para a atualização, o desenvolvedor o verá e parará. Quando for o momento certo, o desenvolvedor o verá e removerá a nota para não confundir futuros desenvolvedores.

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

Por exemplo, digamos que haja um erro na nova versão. Escreva um teste de unidade que verifique esse bug. Se, posteriormente, eles corrigirem esse bug no SDK, a atualização ocorrerá sem problemas. Se houver uma alteração incompatível da API, escreva um teste que verifique se o seu código suporta a nova API ou o SDK suporta a API antiga. Isso é mais um teste de integração do que um teste de unidade, mas ainda deve ser possível.

Minha empresa gera mais de 50 confirmações por dia e não somos exatamente enormes. Mesmo que todos os desenvolvedores leiam todas as mensagens de confirmação, e sejamos francos, eles não sabem, toda a razão pela qual precisamos de um histórico de confirmação registrado é porque as pessoas não conseguem se lembrar. E as pessoas não voltam a ler 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.

De qualquer forma, envie um email para evitar duplicação de trabalho no curto prazo e anote-o nos scripts de construção e em um README ou errata. No entanto, especialmente se o problema com a nova versão for sutil e demorado para solucionar problemas, você precisará 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 ao restante da equipe apenas por meio da mensagem de confirmação?" Porque acho que isso torna óbvio que não, você não deveria. Tento me comunicar muito (isso é algo em que a maioria das equipes de desenvolvimento, em minha experiência, precisa se esforçar ativamente) e certamente faço tudo o que posso para evitar criar armadilhas ou deixá-las mentir.

Se a cadeia de ações que me levou a essa descoberta fosse acionada por um ticket, eu atualizaria o ticket (e garantiria que as pessoas que deveriam saber disso tenham visibilidade), provavelmente o mencionaria cara a cara (esperando para pelo menos deixar alguém com uma sensação incômoda de que "Nossa, acho que Damon disse algo sobre a atualização disso") e, é claro, deixaria um comentário no código no momento em que o SDK foi incluído para que ninguém pudesse atualizar sem ter a chance de vê-lo. Eu posso ver se eu também poderia colocar isso em algum lugar do nosso wiki de desenvolvimento, embora isso tenha feito mais com os olhos para futuras contratações, não para a equipe atual.

Leva apenas mais alguns minutos em comparação com o tempo que levou para encontrar e descobrir o problema. Eu certamente não decidiria que uma das partes menos utilizadas e de baixo sinal da nossa documentação e a deixaria assim.

Ele deve estar no histórico de consolidação, mas não deve estar apenas no histórico de consolidação, imagine por um momento que você contrata um novo desenvolvedor. Você espera que o novo desenvolvedor leia todas as mensagens de confirmação nos últimos 10 anos do seu projeto, porque algumas delas serão críticas para entender sua base de código?

Em segundo lugar, diga que a situação, mas não o código muda, você fará confirmações de "documentação" para poder adicionar mensagens de confirmação ao longo das linhas "mensagem de confirmação da revisão 5432 agora está incorreta, eis a situação atual".

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

Pessoal, não podemos usar o SDK v xyz porque faz com que o buffer Foo transborde e o serviço Bar travar. Ficar com a versão xyy

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

Depois que você informar toda a equipe, documentação mais detalhada deverá ser colocada no wiki da equipe. Isso varia, dependendo de como você estrutura sua documentação. Se você tiver uma seção específica para as Dependências e Requisitos de seus aplicativos, esse seria um bom local para adicioná-lo.

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 mencionado apenas em um ou dois lugares óbvios, você poderá incluir uma observação sobre a não atualização.

O histórico do arquivo no controle de origem pode ser muito longo e, dependendo dos desenvolvedores, pode ter várias entradas por dia. Alguém que está de férias há uma semana pode não ter tempo para ler o histórico de uma semana. O arquivo README é um lugar melhor, pois é um pouco mais central e as pessoas podem estar mais inclinadas a lê-lo, mas você não pode garantir que todos realmente leiam o README. Bem, acho que eles poderiam se ver que tem sido mudado ...

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

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

Precisa haver algum tipo de documento sobre esse SDK de terceiros.

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

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

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

Histórias são corpos muito grandes de texto relativamente não classificado. Eles geralmente pretendem 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 enterradas em centenas de logs de confirmação e eles não terão nenhuma ferramenta para remover a pilha de informações à sua frente.

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

• Uma atualização indesejada do SDK chegou à origem, onde isso poderia afetar negativamente o produto.
• Da pergunta: o colaborador que executou a atualização indesejada não sabia sobre uma decisão específica anterior para não atualizar.

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

Alguém sugeriu a adição de um caso de teste de unidade que falhará se detectar a atualização. Embora isso impeça a atualização, acredito que este seja um caminho perigoso, levando ao fluxo de lava ao longo do tempo. Parece inevitável que em algum momento no futuro o SDK seja atualizado, para trazer novos recursos ou correções, ou porque a versão antiga não é mais suportada. Imagine o coçar a cabeça, talvez até os argumentos, que ocorrerão quando um teste de unidade falhar.

Eu acho que a solução mais geral é ajustar o processo de desenvolvimento. Para o git, use o processo de solicitação de recebimento. Para o Subversion e ferramentas mais antigas, use branches e diff. Mas tenha algum processo que permita aos desenvolvedores seniores capturar esses tipos de problemas antes de entrarem na base de código e afetar outros desenvolvedores.

Se o processo de solicitação de recebimento tivesse sido usado em sua situação e se cada solicitação de recebimento fosse restrita e específica, não seria desperdiçado muito tempo. Uma solicitação de recebimento para atualizar o SDK teria sido enviada e recusada com comentários de que a atualização não é desejada. Ninguém mais teria sido impactado e não haveria necessidade de reverter a atualização do SDK agora.

Mas, para responder diretamente à pergunta original, concordo com outras pessoas que esperam que todos os desenvolvedores leiam completamente todo o histórico de revisões do código, notas de versão, etc. O que há de errado com um email 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 adiar uma atualização, mas também muitas ruins. Tome cuidado para evitar os padrões de fluxo de lava (código desnecessário de compatibilidade com versões anteriores) e culto à carga ("não podemos atualizar isso, mas não sei por quê")!

Eu diria que adicionar esse tipo de informação a um histórico de confirmação é aceitável, mas ainda precisa ser documentado corretamente. Recentemente, começamos a usar confluência (por atlassian). É pesquisável, você pode definir determinadas páginas como favoritas, 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 adotaria uma abordagem que impõe automaticamente a restrição como parte do próprio processo de check-in. Você precisa de algo que não exija nenhuma ação proativa em nome do desenvolvedor, como ler um documento / wiki / README, e não possa ser substituído secretamente.

No território de controle de origem do TFS, você pode codificar políticas de check-in personalizadas que executam regras no check-in. Por exemplo, você pode definir uma política que avalie a versão em um arquivo de configuração com um check-in pendente e falhará se não for igual a xyz. Essas regras impedem o desenvolvedor de executar o check-in e podem fornecer uma mensagem descritiva. As políticas podem ser substituídas, mas é possível gerar alertas quando isso acontecer.

Uma alternativa pode ser o check-in fechado que falhar com alguma forma de teste de unidade que avalia direta ou indiretamente a versão do SDK, como Karl mencionou.

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