O que devo colocar nos comentários ao me comprometer com o Controle de Origem?

Sou um desenvolvedor independente e mantenho um servidor SVN para controle de origem. Até agora, não segui nada específico ao confirmar minhas alterações.

Eu estava revisando meus commits anteriores e não conseguia entender os meus comentários.

O que você coloca nos comentários ao confirmar seus check-ins?

Você pode estar interessado em ler isso: /programming/321720/best-practices-for-version-control-comments .

Se você não está usando um rastreador de erros e, como tal, não pode incluir um ID / número de relatório de erro, você deve ser muito descritivo em seus comentários. Caso contrário, se você acabou de escrever "problema corrigido com o X", por exemplo, duas semanas após a confirmação, não se lembrará do problema. Nesse caso, você precisará comparar as versões de confirmação antes e depois para entender o que era.

Quando comecei a desenvolver aplicativos profissionalmente, não usamos um rastreador de erros, e lembro-me de que algumas vezes os comentários eram muito descritivos (até demais), outras vezes não havia nenhum comentário, era uma bagunça. Com uma identificação de rastreador de erros, os comentários são muito mais úteis e, com mais algumas palavras, você pode até indicar por que fez essa alteração específica. Além disso, IDEs como o Eclipse, por exemplo, possuem plug-ins que detectam os IDs dos rastreadores de erros nos comentários (e também no código-fonte) e podem fornecer um link clicável para a página da Web do rastreador de erros.

O que você esperava encontrar nos comentários dos seus commits anteriores?

Basta colocar essas informações em seus próximos commits.

Às vezes, um ID de ticket é suficiente, um ticket representando um relatório de bug ou uma solicitação de recurso.

Os comentários de confirmação são sobre ver facilmente o que foi alterado. Eles estão lá para sua referência; portanto, a quantidade de detalhes que você colocar neles dependerá de quanto esforço você deseja gastar agora para poupar tempo no futuro. De um modo geral, um pouco de esforço no tempo de confirmação tem o potencial de economizar muito tempo no futuro.

Por exemplo, digamos que mudou um <=a um >e um ++a um --em um loop, mas não adicionar um descritivo cometer comentário. Mais tarde, seria difícil encontrar a revisão em que você inverteu a direção da iteração. Se você tivesse comentado " Direção invertida da travessia do índice de blá ", seria muito mais fácil encontrar essa revisão pesquisando o log de revisão.

É por isso que incluir informações de rastreamento de problemas nas mensagens de confirmação é realmente uma boa ideia. Digamos que você corrige um bug e, posteriormente, o problema é reaberto porque não foi completamente corrigido. Se o seu comentário de confirmação da correção original mencionou o identificador do rastreador de problemas, você pode encontrá-lo facilmente e, mais tarde, encontrar todas as revisões associadas a esse problema.

Costumo escrever uma forma concisa do que estou comprometendo; se for para uma tarefa específica, incluirei o número da tarefa na mensagem. Coisas como:

Changed foobar module to account for the new baz; created quux pages and data objects.

O que não se deve fazer é escrever algumas bobagens como "Ops" ou "Comentários adicionados" (ambos os quais vi adicionados nos logs de confirmação por um colega de trabalho) ou, o pior de tudo, fazer algo como vi no outro dia - A um único arquivo foi registrado, com a mensagem de confirmação "Comentário" (citação exata). O que foi adicionado, você pode perguntar? Algo para o efeito de:

if (z == true) { 
    x = y; // x is being overridden here... <--- added in commit
}

E não, não somos medidos pelo número de confirmações.

Eu acho que tudo isso se resume a como você gerencia seus projetos. Para mim, costumo confirmar sempre que finalizo um recurso que quero enviar para uma versão. Como no meu caso, cada recurso resulta em uma confirmação, eu uso a história e o número do problema do meu recurso como meu comentário. O mesmo vale para a correção de bugs. Começo com um pico, deriva uma história, uso a história para descrever as alterações que preciso fazer e, mais uma vez, comprometo-me a controlar a fonte com uma história nos comentários.

ID do problema.

A maioria dos rastreadores de problemas possui um formato que pode analisar os IDs de problemas das mensagens confirmadas e o grupo confirmado.

Se você não usa um rastreador de problemas, não importa se você é um desenvolvedor solo, eu desenvolvi o assunto em outra resposta :

Use um rastreador de problemas. Não importa que você seja um lobo solitário, acompanhe tudo o que faz pelo seu projeto, seja um recurso ou um bug. Faça uma lista de recursos / componentes. Marque componentes verdadeiramente essenciais como versão 1.0 e tudo mais como versão 2.0. E exclua tudo que estiver marcado como 2.0.

Ok, como a pergunta recebeu uma notificação mod para respostas mais longas, sinto-me obrigado a expandir:

Sim, apenas coloquei o ID do problema nos comentários de confirmação, nada mais. É quando em projetos solo, em projetos de equipe, é uma história totalmente diferente. Não estou defendendo colocar apenas o ID do problema, deve haver algo mais, mas:

1. Em projetos solo, é extremamente tentador não documentar nada,
2. Colocar o ID do problema significa, por padrão, que você passou pelo processo de configuração de um rastreador de problemas,
3. Isso é bom o suficiente para mim.

Usar efetivamente um rastreador de problemas ao desenvolver solo é uma conquista muito maior do que enviar comentários. Seria bom se eu tivesse a motivação de adicionar algo útil nos comentários, mas não tenho.

Geralmente, coloco o objetivo do check-in no topo. Pode ser o nome de uma solicitação de recurso, número do ticket etc.

Em seguida, acompanho a lista dos arquivos afetados e as alterações específicas necessárias em cada arquivo. Isso é particularmente útil quando se está analisando o histórico de revisões de um arquivo em oposição ao projeto / pasta.

Algo como

Ticket 101 fix web service exception when uploading widget

Bug was caused by users uploading incomplete widgets (widgets without wonkers)

webservice.cs:  
  improved post validation for incomplete widgets
  added default exception handler to ProcessWidget
widget.cs:  handled the SqlException when inserting widgets without wonkers

Geralmente, o que você trabalhou nesse commit é um bom começo :)

(por curiosidade ... o que você escreveu se não conseguia entender nada?)

As alterações que você fez no código e o que mais pode ser relevante, incluindo, não se limitam a correções de bugs, novos recursos, quebras de funcionalidade, alterações nas bibliotecas etc. É claro que, como o código é confirmado em pequenos incrementos, não terá todas as opções acima. Por exemplo, se você estiver corrigindo um bug, poderá fazer várias alterações. Serão vários commits para corrigir o bug, mas quais alterações você fez para corrigir o bug específico.

A informação mais importante no log de confirmação é o 'porquê', não o 'o que'.

Um breve resumo das alterações pode ser útil, mas geralmente você pode obter essas informações do próprio diff. Não é um grande problema se está faltando.

Olhando para trás em um log de confirmação, você deve saber por que essa alteração foi feita. Uma identificação de bug pode ajudar bastante a responder a essa pergunta. Às vezes, são necessárias mais explicações. Por exemplo, se você corrigir um probem com entrada incorreta, explique que entrada causou o problema e se não é trivial também como isso pode ocorrer.

Estamos usando assembla em nosso projeto. Construímos o cardwall com todos os talentos / bugs que precisam ser executados e, quando se comprometer, apenas nos referimos a este ticket

Por exemplo:

see #243
 - Grid listed all users with an income more then 1000$ but not the ones that have
   exactly 1000. Added a >= in the file xy.cs on the line xyz

Dessa forma, você pode identificar as alterações mais rapidamente e encontrar alguns erros com mais facilidade