Для чего нужны сообщения фиксации? Я всегда писал их как объяснение того, что я сделал, но недавно я вступил в дискуссию по этому поводу с коллегой, который пишет сообщения коммитов, объясняя, почему он это сделал. Какой из них правильный, или есть совсем другой ответ?
ПРИМЕЧАНИЕ. Я совершенно не знаю, есть ли на это «правильный» ответ. Таким образом, я назвал это вики сообщества и не приму ответа. Голоса определят победителя :)
Лично я могу сказать, что было сделано, непосредственно посмотрев на различия в файлах. почему я не могу сделать вывод, просто глядя на фактические изменения.
Если изменения значительны или сложны, я бы включил не только почему, но и краткий обзор того, как.
Я думаю, что оба полезны. Краткое описание того, что изменилось («Добавление проверки длины для AddUserForm»), проще, чем просмотр различий, особенно если вы просматриваете несколько коммитов. Почему было внесено изменение, какую ошибку оно исправило и т. д., очевидно, тоже очень полезно иметь.
Сообщения фиксации — это то, что вы из них делаете, но когда их сотни для определенного файла или тысячи для проекта, вы хотите иметь возможность просматривать их в поисках определенных изменений или характера изменений. По сути, они похожи на комментарии к коду, и они должны быть максимально полезными, но при этом краткими и содержательными. Может быть, лучше думать о них как о твитах — передать максимальное значение в коротком пространстве.
Как человек, который работал над большими базами кода, охватывающими десятилетия, а также над небольшими проектами, охватывающими год или два, я не нашел ничего более раздражающего при прочесывании журналов коммитов, чем сообщения типа «упс» или «исправлена ошибка». Если вы исправили ошибку, сообщите нам, какую (хотя бы номер ошибки). Это все важно для неизбежной судебной экспертизы в будущем.
Я использую сообщение фиксации как резюме для что было изменено.
Резюме — это [...] краткий документ, резюмирующий [...] информацию таким образом, чтобы читатели могли быстро ознакомиться с большим объемом материала, не читая его целиком.
почему задокументировано где-то еще: система отслеживания проблем, документация по требованиям и т. д. Я также включаю ссылки из сообщения коммита на почему и наоборот.
