Meu commit favorito do Git (2019)

Meu commit favorito do Git

• O texto enfatiza a importância das mensagens de commit no Git e considera que elas são uma das ferramentas mais poderosas para documentar a base de código.
• Usa como exemplo o commit escrito pelo desenvolvedor Dan Carley, "Convert template to US-ASCII to fix error", para explicar o motivo.
• Com base na experiência no GDS (Government Digital Service), aponta que uma das vantagens de programar em público é poder compartilhar esse tipo de exemplo também com pessoas de fora da organização.

Por que este commit é bom

• A proporção entre a mensagem do commit e as mudanças no código é curiosa, mas esse não é o motivo pelo qual vale a pena compartilhá-lo.
• Em outra organização ou nas mãos de outro desenvolvedor, essa mensagem de commit poderia ter sido resumida simplesmente a change whitespace ou fix bug.
• Em vez disso, Dan dedicou tempo para criar uma mensagem de commit realmente útil para as pessoas ao seu redor.

Explica o motivo da mudança

• As melhores mensagens de commit explicam não apenas o que foi alterado, mas também por que foi alterado.
• Neste commit, ele detalha por que o teste introduzido para corresponder ao conteúdo de /etc/nginx/router_routes.conf falhava com o erro ArgumentError: invalid byte sequence in US-ASCII quando executado com bundle exec rake.
• Esse tipo de informação é extremamente valioso para documentar e pode se perder facilmente quando as pessoas esquecem o contexto original, mudam de equipe ou deixam a organização.

É pesquisável

• A primeira parte da mensagem de commit contém a mensagem de erro que motivou a mudança, então qualquer pessoa pode procurar esse erro na base de código executando git log --grep "invalid byte sequence" ou usando a busca de commits do GitHub.
• De fato, várias pessoas conseguiram pesquisar esse problema e descobrir quem já o havia encontrado antes e como ele foi tratado.

Conta uma história

• A mensagem de commit contém detalhes sobre como o problema se manifestava, como foi o processo de investigação e como a solução foi alcançada.
• Mensagens de commit são muito adequadas não para documentar um arquivo, função ou linha específica, mas para registrar informações adicionais sobre a jornada vivida pela base de código.

Deixa todo mundo um pouco mais inteligente

• O fato de Dan ter documentado os comandos executados em cada etapa pode ser uma forma leve de compartilhar conhecimento dentro da equipe.
• Ao ler essa mensagem de commit, alguém pode aprender algumas dicas úteis sobre o conjunto de ferramentas Unix.
• Tanto quem revisa essa mudança quanto quem encontrar esse commit depois pode aprender essas coisas.

Constrói empatia e confiança

• O último parágrafo acrescenta um contexto humano.
• Ao ler isso, é possível sentir a frustração de Dan por ter passado uma hora rastreando um bug traiçoeiro e a satisfação por tê-lo resolvido.
• Mensagens de commit assim ajudam a lembrar que, por trás de cada mudança, existe uma pessoa tomando a melhor decisão possível.

A importância de bons commits

• Este exemplo é um caso extremo, e não se espera que todo commit tenha esse nível de detalhe.
• Ainda assim, ele é um excelente exemplo de como explicar o contexto por trás de uma mudança, ajudar outras pessoas a aprender e contribuir para o modelo mental coletivo da equipe sobre a base de código.
• Se você quiser saber mais sobre os benefícios de boas mensagens de commit e sobre ferramentas que ajudam a estruturá-las com mais facilidade, são recomendados "Telling stories through your commits", de Joel Chippindale, e "A branch in time", de Tekin Süleyman.

Opinião do GN⁺

• Este artigo destaca a importância das mensagens de commit no Git e mostra como elas podem ser uma ferramenta poderosa para documentar a história da base de código e compartilhar conhecimento.
• A mensagem de commit de Dan Carley apresenta um caso exemplar em vários aspectos, como explicar o motivo da mudança, facilitar a busca, contar uma história, compartilhar conhecimento e construir empatia e confiança.
• Ao entender e praticar a escrita de boas mensagens de commit, desenvolvedores podem experimentar melhor colaboração e manutenção de código, o que pode contribuir para aumentar a produtividade e a eficiência de toda a equipe.

[GN⁺]

Comentários do Hacker News

• Opinião do cofundador do GitHub:

  • Mensagens de commit do Git são uma forma única de documentar código, mas não são otimizadas para isso.
  • A maioria das ferramentas mostra apenas a primeira linha da mensagem de commit.
  • O Git projetou as mensagens de commit para que todos os participantes do projeto pudessem lê-las, como o corpo de um e-mail, mas na prática quase ninguém as vê.
  • Também é difícil encontrar a mensagem de commit relevante usando git blame.
  • As mensagens de commit do projeto Git são muito detalhadas, mas na prática quase não são aproveitadas.
  • Escrever uma ótima documentação via Git é, em grande parte das comunidades, quase uma perda de tempo.

• Importância da mensagem de commit para problemas específicos:

  • A primeira linha da mensagem de commit, explicando claramente o problema, é importante.
  • Se necessário, o restante pode ser lido para obter informações adicionais.

• Sentimento pessoal sobre mensagens de commit:

  • Há orgulho em escrever ótimas mensagens de commit, mas não há certeza de que isso tenha valor para outras pessoas.
  • A maioria das pessoas quase nunca procura mensagens de commit.
  • Mensagens de commit bonitas podem ser vaidade de programador e talvez não tenham valor prático.

• Estratégia para escrever a primeira linha da mensagem de commit:

  • Ao usar git log, a primeira linha é a mais importante.
  • Na primeira linha, deve-se indicar não o que foi feito, mas por que foi feito.
  • Como em uma notícia, é melhor escrever em ordem, da informação mais importante para os detalhes.

• Dificuldade de editar mensagens de commit:

  • É difícil modificar uma mensagem de commit depois de escrita.
  • Documentos como arquivos .md, wikis ou Confluence são fáceis de editar.
  • É melhor resistir à tentação de explicar o design de um componente ali e, se necessário, melhorar a documentação.

• Importância de explicações detalhadas para commits pequenos:

  • Quanto menor o commit, mais ele pode exigir uma explicação relativamente longa.
  • É importante explicar em detalhes o motivo de pequenas mudanças.

• Limites das mensagens de commit e problemas das ferramentas:

  • É preciso escrever a primeira linha da mensagem de commit de forma mais específica.
  • O restante da explicação longa pode não ter muito valor.
  • Aponta-se problemas nas ferramentas de desenvolvimento e que as mensagens de erro deveriam ser mais claras.
  • Questiona-se por que ferramentas de edição de código permitem caracteres de espaço em branco não padronizados.

• A importância da higiene de commits acima das mensagens de commit:

  • Mais importante do que o nível de detalhe da mensagem de commit é uma boa higiene de commits.
  • Commits limpos e independentes facilitam extrair e reutilizar funcionalidades do código.

• Crítica ao autosquash e ao rebase:

  • O autosquash atrapalha a escrita de mensagens de commit significativas.
  • O rebase serve para o desenvolvedor organizar o histórico intencionalmente, e não deveria se tornar o padrão no momento do merge.