Devo usar o tempo passado ou presente nas mensagens de confirmação do git? [fechadas]

531

Eu li uma vez que git commit mensagens deve ser no imperativo presente, por exemplo, "Adicionar testes para x". Eu sempre me pego usando o tempo passado, por exemplo, "Adicionamos testes para x", o que me parece muito mais natural.

Aqui está um commit recente de John Resig mostrando os dois em uma mensagem:

Ajuste mais alguns resultados do conjunto jQuery nos testes de manipulação. Também foi corrigida a ordem dos resultados esperados do teste.

Isso importa? Qual devo usar?

Skilldrick
fonte
12
Portanto, essa questão precisa ser encerrada como primariamente baseada em opiniões . Basta olhar para as diferenças de opinião entre imperativo e pretérito ! Dito isto, voto pelo tempo imperativo, porque realmente ajuda a esclarecer o que você está fazendo ao reescrever sua história, escolher a cereja, aplicar patches, etc!
Pergunta semelhante: stackoverflow.com/questions/1753808/…
wip 9/09/13
3
@Eonil, se estiver fechado por ser baseado em opiniões aqui, será fechado por ser também baseado em opiniões.
catraca aberração

Respostas:

601

A preferência por mensagens de confirmação no presente e no estilo imperativo vem do próprio Git. Em Documentation / SubmittingPatches no repositório Git:

Descreva suas alterações no humor imperativo, por exemplo, "faça xyzzy do frotz" em vez de "[Este patch] faz xyzzy do frotz" ou "[eu] mudei xyzzy para frotz", como se você estivesse dando ordens à base de código para alterar sua comportamento.

Então você verá muitas mensagens de confirmação do Git escritas nesse estilo. Se você estiver trabalhando em equipe ou em software de código aberto, é útil que todos sigam esse estilo para obter consistência. Mesmo se você estiver trabalhando em um projeto particular e for o único a ver seu histórico do git, é útil usar o clima imperativo, pois estabelece bons hábitos que serão apreciados quando você estiver trabalhando com outras pessoas.

mipadi
fonte
90
Eu acho que essa é uma excelente escolha. Pense no que é um commit, na forma diff: um conjunto de instruções sobre como passar de um estado anterior para um novo estado. Assim como o diff diz "adicione esta linha aqui, remova esta linha aqui", a mensagem de confirmação diz em termos qualitativos "faça essa alteração". (Sim, git faz armazenar a cometer simplesmente como uma árvore com metadados, mas a um ser humano, a parte mais importante de um commit é o diff.)
Cascabel
124
Você pode ver um commit como um conjunto de instruções sobre como ir do estado anterior para o novo estado; mas vejo isso mais como um ponto de verificação na evolução do código. Para mim, a mensagem de confirmação é um log do que foi feito no código desde a confirmação anterior; e, para um registro, o tempo passado faz muito mais sentido. Se você realmente acha que a mensagem de confirmação deve ser um conjunto de instruções, o tempo imperativo é o caminho a percorrer. Eu realmente não penso nisso dessa maneira.
karadoc
10
@oschrenk: Versões posteriores do arquivo deram um motivo: "Descreva suas alterações no humor imperativo, por exemplo, 'faça xyzzy do frotz' em vez de '[Este patch] faz xyzzy do frotz' 'ou' [eu] mudei xyzzy para fazer frotz ', como se você estivesse dando ordens à base de código para alterar seu comportamento. "
Mipadi
44
A mensagem de confirmação deve ser imperativa, no tempo presente, porque com o git você ou outra pessoa pode acabar fazendo rebaseou cherry-pick, nesse caso, o commit pode ser usado fora do seu contexto original. Como resultado, a mensagem de confirmação deve ser gravada de forma independente, sem esperar que o leitor visualize as mensagens de confirmação ao redor. Quando você escolhe os patches, faz mais sentido aplicar "Corrigir algoritmo de classificação rápida" ou "Classificação: melhorar o desempenho" em vez de "Correção do bug # 124" ou "Classificação modificada para melhorar o desempenho".
Mikko Rantalainen
5
A maneira como penso sobre isso é que a mensagem deve me dizer o que mudará se eu optar por aplicar esse commit ao meu ramo. Não penso nisso como um log, mas como estados para os quais posso mudar e preciso saber o que acontecerá quando escolher um estado específico.
steinybot
357

Seu projeto quase sempre deve usar o tempo passado . De qualquer forma, o projeto deve sempre usar o mesmo tempo para consistência e clareza.

Entendo alguns dos outros argumentos que argumentam para usar o tempo presente, mas eles geralmente não se aplicam. Os seguintes tópicos são argumentos comuns para escrever no tempo presente e minha resposta.

  • Escrever no tempo presente diz a alguém o que a aplicação do commit fará , e não o que você fez.

Essa é a razão mais correta para se querer usar o tempo presente, mas apenas com o estilo certo de projeto. Essa maneira de pensar considera todos os commits como aprimoramentos ou recursos opcionais, e você é livre para decidir quais commits manter e quais rejeitar em seu repositório específico.

Esse argumento funciona se você estiver lidando com um projeto verdadeiramente distribuído. Se você está lidando com um projeto distribuído, provavelmente está trabalhando em um projeto de código aberto. E provavelmente é um projeto muito grande se for realmente distribuído. De fato, provavelmente é o kernel do Linux ou o Git. Como o Linux é provavelmente o que causou a disseminação e o ganho de popularidade do Git, é fácil entender por que as pessoas consideram seu estilo a autoridade. Sim, o estilo faz sentido nesses dois projetos. Ou, em geral, ele trabalha com projetos grandes, de código aberto e distribuídos .

Dito isto, a maioria dos projetos em controle de origem não funciona assim. Geralmente, está incorreto para a maioria dos repositórios. É uma maneira moderna de pensar em um commit: os repositórios Subversion (SVN) e CVS mal suportam esse estilo de check-ins de repositório. Geralmente, uma ramificação de integração lidava com a filtragem de check-ins inválidos, mas esses geralmente não eram considerados recursos "opcionais" ou "interessantes de se ter".

Na maioria dos cenários, ao fazer confirmações em um repositório de origem, você está escrevendo uma entrada no diário que descreve o que foi alterado com esta atualização, para facilitar para que outras pessoas no futuro entendam por que uma alteração foi feita. Geralmente, não é uma alteração opcional - outras pessoas no projeto precisam mesclar ou refazer o projeto. Você não escreve uma entrada no diário como "Querido diário, hoje eu conheço um garoto e ele me diz olá.", Mas, em vez disso, você escreve "Eu conheci um garoto e ele me cumprimentou".

Finalmente, para esses projetos não distribuídos, 99,99% do tempo em que uma pessoa estará lendo uma mensagem de confirmação é para a leitura do histórico - o histórico é lido no pretérito. 0,01% do tempo decidirá se eles devem ou não aplicar esse commit ou integrá-lo em sua filial / repositório.

  • Consistência. É assim que acontece em muitos projetos (incluindo o próprio git). Também as ferramentas git que geram confirmações (como git merge ou git revert) fazem isso.

Não, garanto que a maioria dos projetos já registrados em um sistema de controle de versão teve seu histórico no passado (não tenho referências, mas provavelmente isso é certo, considerando que o argumento do presente é novo desde o Git). As mensagens de "revisão" ou confirmação de mensagens no tempo presente só começaram a fazer sentido em projetos verdadeiramente distribuídos - veja o primeiro ponto acima.

  • As pessoas não apenas leem a história para saber "o que aconteceu com essa base de código", mas também para responder a perguntas como "o que acontece quando escolho este commit", ou "que tipo de coisas novas acontecerão à minha base de código por causa dessas confirmações" Eu posso ou não mesclar no futuro ".

Veja o primeiro ponto. 99,99% do tempo que uma pessoa lê uma mensagem de confirmação é para a leitura do histórico - o histórico é lido no pretérito. 0,01% do tempo decidirá se eles devem ou não aplicar esse commit ou integrá-lo em sua filial / repositório. 99,99% bate 0,01%.

  • Geralmente é mais curto

Eu nunca vi um bom argumento que diz usar tempo / gramática impróprios porque é mais curto. Você provavelmente salvará apenas 3 caracteres em média para uma mensagem padrão de 50 caracteres. Dito isto, o tempo presente, em média, provavelmente será alguns caracteres mais curto.

  • Você pode nomear confirmações de forma mais consistente com os títulos dos tickets no rastreador de problemas / recursos (que não usam o tempo passado, embora às vezes futuro)

Os tickets são gravados como algo que está acontecendo no momento (por exemplo, o aplicativo mostra o comportamento errado quando clico neste botão) ou algo que precisa ser feito no futuro (por exemplo, o texto precisará de uma revisão pelo editor).

A história (ou seja, enviar mensagens) é escrita como algo que foi feito no passado (por exemplo, o problema foi corrigido).

Matt Quigley
fonte
79
Hoje ouvi pela primeira vez sobre a suposta preferência pelo estilo imperativo. Para mim, parecia tão antinatural e bizarro que decidi buscar mais algumas opiniões. Fico feliz em ver que não sou o único que acha que o pretérito é mais natural para enviar mensagens. :)
karadoc
57
As mensagens de consolidação e rebase geradas automaticamente pelo git são imperativas e no presente ("Mesclar", não "Mesclado"; "Rebase", não "Rebased");
MJS
13
Parece que a diferença está entre o foco na alteração do software - "Corrigido X ao fazer Y" - ou o repositório - "Fazer Y para consertar X." +1 para um bom argumento, mas acho que o repo geralmente deve se concentrar em si mesmo, e não no software resultante.
precisa saber é o seguinte
28
O fato é que, usando o imperativo, o tempo presente funciona para grandes projetos (por exemplo, Linux), por isso, obviamente, é escalável. Além disso, requer praticamente zero esforço usando o tempo passado. Como resultado, não vejo razão (exceto "pessoas idosas são usadas para escrever mensagens de confirmação no passado") para usar qualquer outra coisa, exceto o presente imperativo. Se você pode aprender o conjunto de comandos git, pode aprender a escrever no imperativo, no presente.
Mikko Rantalainen
35
O imperativo não é "novo desde o git". O ChangeLog existia muito antes do git, e o uso do imperative sempre foi o estilo recomendado no Projeto GNU. gnu.org/prep/standards/html_node/Style-of-Change-Logs.html
adl
81

Eu escrevi uma descrição completa no 365git .

O uso do imperativo no presente é um processo que demora um pouco para se acostumar. Quando comecei a mencioná-lo, encontrou resistência. Geralmente, na linha de "A mensagem de confirmação registra o que eu fiz". Mas, o Git é um sistema de controle de versão distribuído, onde existem potencialmente muitos lugares para obter alterações. Em vez de escrever mensagens dizendo o que você fez; considere essas mensagens como as instruções para o que a aplicação do commit fará. Em vez de ter um commit com o título:

Renamed the iVars and removed the common prefix.

Tenha um como este:

Rename the iVars to remove the common prefix

O que diz a alguém o que a aplicação do commit fará, e não o que você fez. Além disso, se você olhar para o histórico do seu repositório, verá que as mensagens geradas pelo Git também são escritas neste tempo - "Mesclar", não "Mesclado", "Rebase", não "Rebased", portanto, escrever no mesmo tempo mantém as coisas consistentes. Parece estranho no começo, mas faz sentido (depoimentos disponíveis mediante solicitação) e eventualmente se torna natural.

Dito tudo isso - é o seu código, seu repositório: então configure suas próprias diretrizes e cumpra-as.

Se, no entanto, você decidir seguir esse caminho, então, git rebase -icom a opção de reformulação, seria uma boa ideia.

Abizern
fonte
7
Bem, você misturou duas diretrizes diferentes: o projeto de código aberto do Git e o uso regular do Git. O link fornecido não menciona tempo . O documento oficial do Git menciona apenas o limite de 50 caracteres. O Git é um VCS distribuído onde existem muitos lugares para obter alterações ... considere essas mensagens como as instruções para o que a aplicação do commit fará. Isso se aplica apenas a alguns projetos que são realmente projetos distribuídos. 99,999% dos commit do Git nunca serão aplicados manualmente dessa maneira. Na maioria dos projetos, o histórico é um log de alterações, que deve estar no passado.
Matt Quigley
4
"e deve pular o ponto final"
takeshin
30

Fique com o imperativo do presente, porque

  • é bom ter um padrão
  • ele corresponde a tickets no rastreador de erros, que naturalmente têm o formato "implementar algo", "consertar algo" ou "testar algo".
Craig P. Motlin
fonte
16

Para quem você está escrevendo a mensagem? E esse leitor normalmente lê a mensagem antes ou depois da propriedade do commit?

Eu acho que boas respostas aqui foram dadas de ambas as perspectivas, talvez eu deixasse de sugerir que há uma melhor resposta para cada projeto. A votação por partes pode sugerir o mesmo.

ou seja, para resumir:

  • É a mensagem predominantemente para outras pessoas, normalmente lendo em algum momento antes de assumirem a mudança: Uma proposta do que levar a mudança fará com o código existente.

  • A mensagem é predominantemente como um diário / registro para você (ou para sua equipe), mas normalmente é lida da perspectiva de ter assumido a mudança e pesquisada para descobrir o que aconteceu.

Talvez isso leve a motivação para sua equipe / projeto, de qualquer forma.

Wardw
fonte
10

isso importa? as pessoas geralmente são inteligentes o suficiente para interpretar as mensagens corretamente, se não forem, você provavelmente não deve permitir que acessem seu repositório de qualquer maneira!

Michael Baldry
fonte
27
Para algumas pessoas , coisas assim importam bastante.
Wesley Murch
2
@mog o link não faz nenhuma declaração sobre presente e passado.
ceving 19/03/2013
2
Se o projeto se expandir bastante, as pessoas que fazem a revisão de códigos e a caça de bugs verão tantos comprometimentos que precisam de toda a ajuda que você e eu podemos fornecer. Não faz sentido economizar alguns segundos agora para causar grande dor de cabeça no futuro por não escrever uma mensagem de confirmação adequada.
Mikko Rantalainen
Não estou dizendo que não escreva uma boa mensagem de confirmação. Estou dizendo que não importa se você usa o tempo passado ou presente.
Michael Baldry
1
Como você saberia que a pessoa que não consegue interpretar sua mensagem de confirmação é causa dessa pessoa que não é capaz o suficiente ou que você não é capaz o suficiente de escrever uma boa mensagem de confirmação?
Haris
7

É com você. Basta usar a mensagem de confirmação como desejar. Mas é mais fácil se você não estiver alternando entre horários e idiomas.

E se você desenvolver em equipe - isso deve ser discutido e fixado.

Andreas Rehm
fonte