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

94

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?

rjzii
fonte
60
Parece que seu projeto tem problemas de comunicação bastante sérios.
tzerb
82
Você precisa de novas contratações para percorrer todo o histórico de consolidação?
Steven Evers
3
Novas contratações não devem estar rolando pela base de códigos e alterando dependências sem instruções específicas para isso.
Midnotion 29/07
28
@ Midnotion Então, em algum lugar do caminho do novo contratado ao desenvolvedor principal, você leva um tempo para percorrer todo o histórico de consolidação? Fascinante.
Nathan Cooper
6
Ainda não é uma boa ideia colocar informações críticas apenas no histórico de confirmação.
17 de 26

Respostas:

143

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.

17 de 26
fonte
52
De fato, o histórico de consolidação é o histórico do projeto. Assim como seria estúpido ter informações cruciais na história das edições do wiki, e não na própria página. O histórico (seja código ou wiki) é para referência sobre o que aconteceu anteriormente, não sobre o que deve acontecer agora.
Ordous 29/07
48
Se possível para o SDK fictício, eu adicionaria um teste de unidade projetado especificamente para passar no V2 e falhar no V3 com uma declaração de declaração explícita, dando o motivo para não atualizar para o V3. O histórico de consolidação é um bom lugar para indicar por que você está fazendo essa alteração para revisores de código, não para documentar as práticas recomendadas.
Klors
3
@Klors Desde que você não se restrinja às definições mais pedantes de testes de unidade e se recuse a fazer outros tipos de testes automatizados, um teste baseado na verificação do sistema de arquivos / etc para o nome das bibliotecas (se a versão estiver codificada) nele) ou um hash / soma de verificação do arquivo em si pode ser usado para lançar uma bandeira vermelha para quem quiser atualizar a biblioteca, mesmo nos casos em que as falhas das novas versões sejam difíceis / impossíveis de capturar em um teste. (por exemplo, condições de corrida com vários segmentos)
Dan Neely 30/07
18
@ Klors Eu estava pensando a mesma coisa, mas na minha opinião, o teste de unidade deve demonstrar o motivo do uso de v2 sobre v3, assim, se o teste de unidade for aprovado com v4, você não terá um teste de unidade que exija v2 sem Razão, motivo.
30514 Matthew
9
Outro motivo para não usar o histórico de consolidação para isso: o histórico de consolidação é um registro permanente. Se o motivo da não atualização desaparecer, o histórico de confirmação ainda conterá o aviso de não atualização, o que pode ser confuso. Você precisa de algum lugar onde listas de requisitos como essa sejam mantidas atualizadas, para que os desenvolvedores não precisem verificar novamente se as coisas ainda são relevantes.
Jules
69

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.

Daenyth
fonte
11
Eu concordo: a melhor localização para informações críticas é "no maior número possível de lugares". Talvez o pom.xmlarquivo de projeto ou equivalente, um leia-me etc., mas o histórico de consolidação ainda seja bom. Se eu estiver olhando para atualizar uma biblioteca, posso verificar o histórico da versão existente para ver quando ela foi atualizada, bem como quaisquer notas sobre problemas que o committer teve. Mas eu não gostaria de vasculhar a história para reunir toda a documentação. É uma boa fonte suplementar .
35

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.

Jeffery Thomas
fonte
7
Sim, o comentário precisa ser colocado "no caminho" da alteração. Portanto, é tecnicamente impossível executar a ação sem ver o aviso. É muito parecido com controles de segurança.
dss539
+1 na sugestão de criar uma história / ticket para a atualização no rastreador de problemas, defina como "Em espera" com uma explicação de por que ainda não pode ser feito. O rastreador de problemas é um lugar que você realmente pode exigir que as pessoas procurem antes de trabalhar em algo.
Andrew Spencer
+1 Citando Jeff Attwood (embora ele fale sobre, ugh, "usuários"): "Na próxima vez que você estiver projetando [X], considere a miopia [cliente]. Você pode se surpreender com o quão míope seus [clientes] podem ser. Pense muito sobre colocar as coisas diretamente na frente delas, onde elas não são apenas visíveis, mas inevitáveis. Caso contrário, elas podem não ser vistas. " blog.codinghorror.com/treating-user-myopia
heltonbiker
17

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.

Karl Bielefeldt
fonte
1
Esta é a única resposta verdadeira. Capturar a falha em um teste de unidade impede que ocorra a atualização incorreta. Período.
Dirk Bester
15

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.

Damon
fonte
4
+1 A palavra-chave real é apenas . Certamente não faz mal se as informações forem armazenadas em uma mensagem de confirmação , além de outros locais mais adequados. Ele atingiu o OP, pois o log de confirmação era a única documentação disponível.
JensG
13

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".

pedregoso
fonte
11

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

FrustratedWithFormsDesigner
fonte
4
Eu gosto da ideia do grupo de email. Muitos lugares em que trabalhei dependem de endereços individuais e as coisas não são repassadas aos novos membros.
Jeffo
20
O que acontece se alguém novo aparecer na sua equipe? Quem é responsável por fornecer a eles esse tipo de conhecimento pseudo-institucional?
ABMagil
3
@ABMagil: A informação entra em um wiki. Os desenvolvedores que são novos na equipe geralmente são iniciados a partir daí, em algumas páginas introdutórias. Depois, eles chegam a indivíduos específicos (que disponibilizaram tempo para ajudar o novo desenvolvedor) quando têm perguntas específicas (e sempre o fazem). Para nós, isso provavelmente acabaria no "Guia de Configuração do Desenvolvedor para ApplicationX", NOTE: Do not use SDK vers. x.y.z because...mas a comunicação inicial deve ser um email.
FrustratedWithFormsDesigner
16
-1 e-mails não funcionam bem como documentação
BlueRaja - Danny Pflughoeft
6
@ BlueRaja-DannyPflughoeft: O email fornece um método simples e fácil de usar, para que todos na equipe saibam imediatamente que um problema foi descoberto ao usar uma versão específica de uma biblioteca específica e que esta versão não deve ser usada. Como afirmado, a documentação de longo prazo é melhor feita no wiki de uma equipe ou em algum outro tipo de base de conhecimento.
FrustratedWithFormsDesigner
5

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.

JeffO
fonte
2

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.

Cort Ammon
fonte
isso parece mais um comentário do que uma resposta. Veja: Como responder
gnat
Bom ponto, eu ampliei. Espero que isso atenda melhor aos critérios do StackExchange.
Cort Ammon
Eu acho que esta resposta melhor aborda o tópico da pergunta. O histórico de confirmação é bom para salvar informações, se uma pessoa souber que deve procurar uma nota. Se não houver motivo para examinar a 'culpa' de uma determinada linha, como a inclusão de um SDK, essa documentação não será lida.
Seth Battin
1

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ê")!

amora
fonte
Enquanto a atualização do SDK, que era um número de versão menor e não principal, foi o que levou a essa pergunta, essa linha de raciocínio está surgindo no grupo há algum tempo.
rjzii
Por que a solicitação de recebimento foi recusada? Como a pessoa responsável por essa decisão deve descobrir (ou lembrar) a restrição de versão?
Ben Voigt
@BenVoigt Bem, ou os líderes da equipe sabiam sobre a restrição ou ninguém se lembrava disso e isso foi redescoberto depois de encontrar problemas. De qualquer maneira, usando solicitações de pull, não há culpando os humildes novo desenvolvedor de aluguer, como os idosos iria aprovar a alteração antes de ser permitido em.
wberry
@wberry: Ou outro desenvolvedor sênior processou a solicitação de recebimento daquele que sabia sobre a restrição de versão. A menos que todas as solicitações pull tenham que ser aprovadas por todos os desenvolvedores, o que parece ser um gasto duvidoso de recursos.
Ben Voigt
0

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.

JimS
fonte
0

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).

Pero P.
fonte