Mensagens de confirmação do Git: 50/72 Formatação

Tim Pope defende um estilo de mensagem de confirmação do Git específico em seu blog: http://www.tpope.net/node/106 .

Aqui está um rápido resumo do que ele recomenda:

• A primeira linha tem 50 caracteres ou menos.
• Então uma linha em branco.
• O texto restante deve ter quebra de 72 caracteres.

Sua postagem no blog fornece a justificativa para essas recomendações (que chamarei de "formatação 50/72" por questões de concisão):

• Na prática, algumas ferramentas tratam a primeira linha como uma linha de assunto e o segundo parágrafo como um corpo (semelhante ao email).
• git log não lida com quebra automática, por isso é difícil ler se as linhas são muito longas.
• git format-patch --stdout converte confirmações em e-mail - portanto, para jogar bem, ajuda se suas confirmações já estiverem bem agrupadas.

Gostaria de acrescentar que acho que Tim concordaria com:

• O ato de resumir sua confirmação é uma boa prática inerente a qualquer sistema de controle de versão. Ajuda outras pessoas (ou mais tarde você) a encontrar confirmações relevantes mais rapidamente.

Então, tenho alguns ângulos para minha pergunta:

• Que parte (mais ou menos) dos "líderes de pensamento" ou "usuários experientes" do Git adotam o estilo de formatação 50/72? Eu pergunto isso porque, em algum momento, os usuários mais novos não sabem ou não se importam com as práticas da comunidade.
• Para aqueles que não usam essa formatação, existe uma razão de princípios para usar um estilo de formatação diferente? (Observe que estou procurando uma discussão sobre o mérito, não “nunca ouvi falar disso” ou “não me importo”.)
• Empiricamente falando, qual porcentagem de repositórios Git adotam esse estilo? (Caso alguém queira fazer uma análise nos repositórios do GitHub ... dica, dica.)

Meu ponto aqui não é recomendar o estilo 50/72 ou abater outros estilos. (Para ser aberto sobre isso, prefiro, mas estou aberto a outras idéias.) Eu só quero entender o porquê as pessoas gostam ou se opõem a vários estilos de mensagens de confirmação do Git. (Sinta-se à vontade para mencionar pontos que também não foram mencionados.)

Em relação à linha "resumo" (os 50 na sua fórmula), a documentação do kernel do Linux tem o seguinte a dizer :

For these reasons, the "summary" must be no more than 70-75
characters, and it must describe both what the patch changes, as well
as why the patch might be necessary.  It is challenging to be both
succinct and descriptive, but that is what a well-written summary
should do.

Dito isso, parece que os mantenedores do kernel realmente tentam manter as coisas em torno de 50. Aqui está um histograma dos comprimentos das linhas de resumo no log git para o kernel:

( ver em tamanho normal )

Há um número considerável de confirmações que possuem linhas de resumo que são mais longas (algumas muito mais longas) do que esse gráfico pode conter sem fazer com que a parte interessante pareça uma única linha. (Provavelmente existe alguma técnica estatística sofisticada para incorporar esses dados aqui, mas tudo bem… :-)

Se você deseja ver os comprimentos brutos:

cd /path/to/repo
git shortlog  | grep -e '^      ' | sed 's/[[:space:]]\+\(.*\)$/\1/' | awk '{print length($0)}'

ou um histograma baseado em texto:

cd /path/to/repo
git shortlog  | grep -e '^      ' | sed 's/[[:space:]]\+\(.*\)$/\1/' | awk '{lens[length($0)]++;} END {for (len in lens) print len, lens[len] }' | sort -n

Com relação aos “líderes de pensamento”: Linus defende enfaticamente o empacotamento de linha para a mensagem de confirmação completa:

[…] Usamos colunas de 72 caracteres para quebra de linha, exceto para o material citado que possui um formato de linha específico.

As exceções referem-se principalmente ao texto “sem prosa”, ou seja, texto que não foi digitado por um humano para o commit - por exemplo, mensagens de erro do compilador.

A separação de apresentação e dados direciona minhas mensagens de confirmação aqui.

Sua mensagem de confirmação não deve ser contida em nenhum número de caracteres e, em vez disso, as quebras de linha devem ser usadas para separar pensamentos, parágrafos etc. como parte dos dados, não da apresentação. Nesse caso, os "dados" são a mensagem que você está tentando transmitir e a "apresentação" é como o usuário vê isso.

Uso uma única linha de resumo na parte superior e tento mantê-la curta, mas não me limite a um número arbitrário. Seria muito melhor se o Git realmente fornecesse uma maneira de armazenar mensagens de resumo como uma entidade separada da mensagem, mas como não tenho que invadir uma delas e usar a primeira quebra de linha como delimitador (felizmente, muitas ferramentas suportam isso significa separar os dados).

Para a própria mensagem, novas linhas indicam algo significativo nos dados. Uma única nova linha indica um início / interrupção em uma lista e uma nova linha dupla indica um novo pensamento / idéia.

This is a summary line, try to keep it short and end with a line break.
This is a thought, perhaps an explanation of what I have done in human readable format.  It may be complex and long consisting of several sentences that describe my work in essay format.  It is not up to me to decide now (at author time) how the user is going to consume this data.

Two line breaks separate these two thoughts.  The user may be reading this on a phone or a wide screen monitor.  Have you ever tried to read 72 character wrapped text on a device that only displays 60 characters across?  It is a truly painful experience.  Also, the opening sentence of this paragraph (assuming essay style format) should be an intro into the paragraph so if a tool chooses it may want to not auto-wrap and let you just see the start of each paragraph.  Again, it is up to the presentation tool not me (a random author at some point in history) to try to force my particular formatting down everyone else's throat.

Just as an example, here is a list of points:
* Point 1.
* Point 2.
* Point 3.

Aqui está a aparência de um visualizador que envolve o texto com suavidade.

Esta é uma linha de resumo, tente mantê-la curta e termine com uma quebra de linha.

Este é um pensamento, talvez uma explicação do que fiz em formato legível por humanos. Pode ser complexo e longo, consistindo de várias frases que descrevem meu trabalho em formato de ensaio. Não cabe a mim decidir agora (no momento do autor) como o usuário consumirá esses dados.

Duas quebras de linha separam esses dois pensamentos. O usuário pode estar lendo isso em um telefone ou em um monitor de tela ampla. Você já tentou ler um texto com 72 caracteres em um dispositivo que exibe apenas 60 caracteres? É uma experiência verdadeiramente dolorosa. Além disso, a sentença de abertura deste parágrafo (assumindo o formato do estilo de ensaio) deve ser uma introdução ao parágrafo; portanto, se uma ferramenta escolher, pode não querer quebrar automaticamente e permitir que você veja apenas o início de cada parágrafo. Novamente, cabe à ferramenta de apresentação não a mim (um autor aleatório em algum momento da história) tentar forçar minha formatação particular na garganta de todos os outros.

Apenas como exemplo, aqui está uma lista de pontos:
* Ponto 1.
* Ponto 2.
* Ponto 3.

Minha suspeita é que o autor do Git comprometa a recomendação de mensagens que você vinculou nunca escreveu um software que será consumido por uma grande variedade de usuários finais em dispositivos diferentes antes (ou seja, um site), já que neste momento na evolução do software / computação é sabido que armazenar seus dados com informações de apresentação codificadas é uma má idéia no que diz respeito à experiência do usuário.

Concordo que é interessante propor um estilo particular de trabalho. No entanto, a menos que eu tenha a chance de definir o estilo, geralmente sigo o que foi feito para garantir a consistência.

Dando uma olhada no Linux Kernel Commits, o projeto que iniciou o git, se você preferir , http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h = bca476139d2ded86be146dae09b06e22548b67f3 , eles não seguem a regra 50/72. A primeira linha tem 54 caracteres.

Eu diria que a consistência é importante. Configure meios adequados para identificar usuários que fizeram confirmações (nome do usuário, usuário.e-mail - especialmente em redes internas. O usuário @ OFFICE-1-PC-10293982811111 não é um endereço de contato útil). Dependendo do projeto, disponibilize os detalhes apropriados no commit. É difícil dizer o que deveria ser; pode ser tarefas concluídas em um processo de desenvolvimento e detalhes do que mudou.

Não acredito que os usuários devam usar o git de uma maneira, porque certas interfaces para o git tratam os commits de determinadas maneiras.

Também devo observar que existem outras maneiras de encontrar confirmações. Para começar, git diffdirá o que mudou. Você também pode fazer coisas como git log --pretty=format:'%T %cN %ce'formatar as opções de git log.

O comprimento máximo recomendado do título é realmente 50?

Eu acredito nisso há anos, mas como acabei de notar, a documentação do "git commit" realmente afirma

$ git help commit | grep -C 1 50
      Though not required, it’s a good idea to begin the commit message with
      a single short (less than 50 character) line summarizing the change,
      followed by a blank line and then a more thorough description. The text

$  git version
git version 2.11.0

Alguém poderia argumentar que "menos de 50" só pode significar "não mais que 49".