Meu commit git favorito

Nota perev. : Esta publicação de um programador britânico, que se tornou um verdadeiro sucesso na Internet de língua inglesa, refere-se a um compromisso do Git há 6 anos. Foi gravado em um dos repositórios abertos do Serviço Digital do governo - um serviço dedicado ao desenvolvimento de serviços digitais no Reino Unido e ao apoio ao projeto GOV.UK. O commit em si é interessante, não tanto com as alterações no código como com a descrição que os acompanha ...


Imagem de xkcd # 1296

Adoro descrever descrições no Git. Quando usadas corretamente, elas podem ser chamadas de uma das ferramentas mais poderosas para documentar a evolução da base de código durante sua existência. Quero ilustrar meu ponto de vista com o exemplo da minha descrição favorita.

Esse compromisso data de quando trabalhei no Government Digital Service. Seu autor é um desenvolvedor chamado Dan Carley , e possui um título bastante normal: " Convertido o modelo em US-ASCII para corrigir o erro ".

“Eu implementei vários testes no ramo de recursos para corresponder ao conteúdo de` / etc / nginx / router_routes.conf`. Eles funcionaram bem se executados com os comandos `bundle exec rake spec 'ou` bundle exec rspec modules / router / spec`. Mas ao executar o `bundle exec rake`, cada bloco deveria falhar:

ArgumentError: invalid byte sequence in US-ASCII 

No final, descobri que, após a exceção da expressão `.with_content (//)`, todos os erros desaparecem. Que não há caracteres estranhos no arquivo de especificação. E também que pode ser tocado chamando Puppet no mesmo intérprete:

  rake -E 'require "puppet"' spec 

Este modelo parece ser o único arquivo em nossa base de código codificado com 'utf-8'. Todos os outros arquivos em 'us-ascii':

  dcarley-MBA:puppet dcarley$ find modules -type f -exec file --mime {} \+ | grep utf modules/router/templates/routes.conf.erb: text/plain; charset=utf-8 

Uma tentativa de transcodificá-lo para US-ASCII falhou devido a um único caractere que se parece com um espaço:

  dcarley-MBA:puppet dcarley$ iconv -f UTF8 -t US-ASCII modules/router/templates/routes.conf.erb 2>&1 | tail -n5 proxy_intercept_errors off; # Set proxy timeout to 50 seconds as a quick fix for problems # iconv: modules/router/templates/routes.conf.erb:458:3: cannot convert 

Depois de substituí-lo (manualmente), o arquivo tornou-se novamente 'US-ASCII':

  dcarley-MBA:puppet dcarley$ file --mime modules/router/templates/routes.conf.erb modules/router/templates/routes.conf.erb: text/plain; charset=us-ascii 

Agora os testes funcionam! A hora inteira da minha vida não pode ser devolvida ... "

Uma pequena digressão: um dos benefícios do desenvolvimento de código aberto praticado no GDS é que você pode compartilhar exemplos como esse fora da organização que os criou. Não sei quem propôs esse conceito ao GDS - quando ingressei na organização, ele já era amplamente usado -, mas sou infinitamente grato a essa pessoa.

Por que eu gosto desse commit

Inúmeras vezes eu citei isso como um exemplo do que as descrições de commit são capazes. É um pouco engraçado por causa da proporção de alterações no código e no tamanho da descrição, mas não gosto nada disso.

Em outra empresa, com outro desenvolvedor, toda a mensagem do commit pode ser reduzida a frases como "substituiu o espaço", "corrigiu o erro" ou (dependendo da cultura da equipe) a ataques contra o inventor de espaços inextricáveis. Em vez disso, Dan dedicou um tempo para criar uma descrição detalhada útil para outras pessoas. Gostaria de me debruçar sobre as razões pelas quais considero esse comprometimento um bom exemplo.

Divulga o motivo das alterações

As melhores descrições de confirmações não apenas informam o que mudou, mas também explicam o porquê . No nosso caso:

Eu implementei vários testes no ramo de recursos para corresponder ao conteúdo de `/ etc / nginx / router_routes.conf`. Eles funcionaram bem se executados com os comandos `bundle exec rake spec 'ou` bundle exec rspec modules / router / spec`. Mas ao executar o `bundle exec rake`, cada bloco deveria falhar:

  ArgumentError: invalid byte sequence in US-ASCII 

Sem esse nível de detalhe, podemos assumir que a confirmação corrigiu o erro de análise em uma ferramenta específica. Graças à descrição do commit, sabemos que tipo de ferramenta era.

Esse tipo de informação pode se tornar realmente valioso e é muito fácil de perder, pois as pessoas tendem a esquecer os meandros de seu trabalho, mudar para outras equipes e, finalmente, deixar a empresa.

Bom para pesquisar

Um dos elementos principais desta descrição é o próprio erro, com o qual novas pesquisas começaram:

ArgumentError:
sequência de bytes inválida em US-ASCII

Qualquer pessoa que encontre esse erro pode pesquisar a base de código executando o git log --grep "invalid byte sequence" ou usando o GitHub confirma a pesquisa . De fato, a julgar pelos resultados da pesquisa, muitos já o fizeram e descobriram quem e quando se deparou com esse problema e como ele foi finalmente resolvido.

Fornece uma imagem completa

A mensagem de confirmação detalha como o problema parecia, como foi investigado e resolvido. Por exemplo:

No final, descobri que, após a exceção da expressão `.with_content (//)`, todos os erros desaparecem. Que não há caracteres estranhos no arquivo de especificação. E também que pode ser tocado chamando Puppet no mesmo intérprete.

Essa é uma das áreas nas quais as mensagens confirmadas são realmente capazes de se mostrar, porque descrevem a alteração em si, e não algum arquivo, função ou linha de código. Isso os torna um ótimo local para armazenar esse tipo de informações adicionais de aventura com base em código.

Torna todos um pouco mais inteligentes

Dan fez uma coisa aqui, que eu realmente aprecio: trouxe todas as equipes que eu desempenhei em cada etapa. Essa é uma maneira excelente e acessível de compartilhar conhecimento em equipe. Lendo sua descrição do commit, você pode aprender muito sobre as ferramentas Unix:

• você pode passar o argumento -exec para find para executar um comando com cada arquivo encontrado;
• adicionar \+ no final do comando faz algo muito interessante (passa vários nomes de arquivo para o comando file e não executa o comando uma vez para cada arquivo);
• file --mime permite descobrir o tipo MIME do arquivo;
• existe um utilitário iconv .

Uma pessoa que visualiza uma descrição pode aprender sobre todas essas coisas. Quem se deparar com esse comprometimento mais tarde também aprenderá sobre essas coisas. Se você multiplicar essa abordagem para confirmar por um longo tempo e um número suficiente delas, ela poderá se tornar um poderoso incentivo para a equipe.

Desenvolve empatia e confiança

Agora os testes funcionam! A hora inteira da minha vida não pode ser devolvida ...

O último parágrafo acrescenta um pouco de humanidade. Lendo essas palavras, é difícil não sentir a decepção de Dan, que passou uma hora inteira procurando por um erro oculto e a satisfação de corrigi-lo.

Agora imagine uma mensagem semelhante anexada a um hack ou fragmento temporário do código do protótipo que entrou em produção e "criou raiz" (como costuma acontecer com esses fragmentos). Essa descrição do commit lembra a todos que, por trás de cada mudança, há uma pessoa que toma a melhor decisão possível, considerando as informações disponíveis naquele momento.

Bom compromete a matéria

Admito que este é um exemplo extremo e não espero que todos os commits (especialmente com esse escopo) ostentem o mesmo nível de detalhe. No entanto, ainda acho que este é um ótimo exemplo de explicação do motivo da mudança, ajudando outras pessoas a aprender coisas novas e contribuindo para o modelo mental coletivo associado à base de código.

Se você quiser saber um pouco mais sobre os profissionais de boas descrições de confirmações e algumas ferramentas que facilitam a estruturação de edições, recomendo os seguintes materiais:

• “ Contando histórias através de seus commits ”, de Joel Chippindale;
• " Uma filial no tempo ", de Tekin Süleyman.

PS do tradutor

Leia também em nosso blog:

• “ Git acontece! 6 erros típicos do Git e como corrigi-los ";
• “Um truque maravilhoso para tornar um mantenedor de projeto de código aberto por dia ”;
• “ O que grandes projetos de código aberto de sucesso têm em comum? "