Предложения для хорошего сообщения о фиксации: формат/ориентир?

Я нахожусь в начале нового проекта, и я пытаюсь настроить хранилище умным способом и установить некоторые правила стиля кода, чтобы каждый мог сконцентрироваться на коде.

Большая часть из них выполняется, но я все еще не уверен в том, какой формат должен применяться для фиксации сообщений. Я свободен и просто говорю людям, чтобы они были ясными и тщательными, но я редко это работаю, люди, имеющие очень разные понятия "ясно":).

И до сих пор я никогда не находил удовлетворительную схему. То, что я чаще всего делаю, - это однострочное резюме фиксации, а затем пулевые точки, описывающие каждое изменение более подробно.

Но часто бывает сложно решить, что заслуживает пуля, а что нет, и какая-то классификация по функциям, файлам или незначительным/значительным изменениям представляется подходящей. К сожалению каждый раз, когда я пытаюсь это сделать, я заканчиваю тем, что пишу глупое сообщение о совершении транзакций для незначительных изменений...

Как вы это делаете?

ОТВЕТЫ

Ответ 1

Я думаю, вы должны полагаться на людей, которые действительно могут думать сами за себя. Вы можете предоставить некоторые основные рекомендации, такие как те, которые вы изложили, но, в конце концов, люди должны понимать их, чтобы следовать им.

Здесь выдержка из мои рекомендуемые рекомендации по управлению версиями:

Всегда записывайте комментарий, когда вы делаете что-то в репозитории. Ваш комментарий должен быть кратким и точным, описывающим, что было изменено и, возможно, почему. Если вы сделали несколько изменений, напишите одну строку или предложение о каждой части. Если вы обнаружите, что пишете очень длинный список изменений, подумайте о том, чтобы разделить вашу фиксацию на более мелкие части, как описано выше. Префикс ваших комментариев с помощью идентификаторов, таких как Fix или Add, является хорошим способом указать, какой тип изменений вы сделали. Это также облегчает фильтрацию содержимого позже, визуально, с помощью программы для чтения человеком или автоматически с помощью программы.

Если вы исправили конкретную ошибку или внедрили конкретный запрос на изменение, я также рекомендую ссылаться на номер ошибки или проблемы в сообщении фиксации. Некоторые инструменты могут обрабатывать эту информацию и создавать ссылку на соответствующую страницу в системе отслеживания ошибок или автоматически обновлять проблему на основе фиксации.

Вот несколько примеров хороших сообщений:

Changed paragraph separation from indentation to vertical space.
...
Fix: Extra image removed.
Fix: CSS patched to give better results when embedded in javadoc.
Add: A javadoc {@link} tag in the lyx, just to show it possible.
...
- Moved third party projects to ext folder.
- Added lib folder for binary library files.
...
Fix: Fixed bug #1938.
Add: Implemented change request #39381.

По моему опыту, вы должны следить за людьми и давать им указания, когда они не следуют правилам фиксации. Разумеется, вы могли бы реализовать script для обеспечения соблюдения некоторых правил (например, для префикса и ссылки на ошибку), но это не поймает ленивых людей, которые не удосуживаются писать что-либо значимое. Я думаю, что важно объяснить, почему вы хотите использовать эти соглашения и как они принесут пользу команде разработчиков.

Настройка списка электронной почты для фиксации и мониторинг его для сообщения - хороший способ отслеживать, что делают люди. Всякий раз, когда кто-то совершает что-то без удовлетворительного сообщения, вы будете знать это и можете сказать им. Я думаю, это так же, как и с соглашениями о кодировании, чтобы они были успешными, кто-то должен следить за ними.

Ответ 2

Некоторые правила, которые я пытаюсь выполнить:

  • Первая строка описания - краткая сводка изменений. Многие системы управления версиями позволяют просмотреть список изменений, отображающих эту строку, поэтому он дает приблизительное резюме.
  • Включить заголовок ошибки и. Не заставляйте людей искать это!
    • Сделайте идентификатор ошибки URL, чтобы открыть ошибку, если отслеживание ошибок поддерживает ее.
  • Скажите , что вы изменили.
  • Скажите , почему вы сделали это изменение, вместо того, чтобы использовать другой подход.
  • Будьте очень подробными.
  • Создание каждого изменения маленького упрощает отслеживание истории, а также упрощает запись и чтение хорошего описания фиксации.
  • Когда изменение является строго рефакторингом, я начинаю первую строку с REFACTORING:. Это позволяет мне игнорировать это изменение при поиске преднамеренных функциональных изменений. (Конечно, случайные функциональные изменения, например, ошибки, все еще могут быть в них.)

Пример очень подробного сообщения о фиксации см. в этом сообщении в блоге от моего старого друга Кира.

Ответ 3

Я пытаюсь выполнить следующие правила:

  • Будьте лаконичны
  • Опишите, почему вы это делаете, а не то, что вы делаете.

Обычный формат для моих сообщений о совершении:

Issue: #[issue number] [short description]

Если у вас есть какая-то система отслеживания ошибок, укажите номер проблемы в сообщении commit.
Я обнаружил, что многие разработчики просто пишут что-то вроде "Добавлен X. Удалено Y", но я могу найти эту информацию, глядя на код diff. Если номер проблемы не указан, может быть трудно понять, почему разработчик внес некоторые изменения.

Ответ 4

Мне действительно нравится формат, продвигаемый angular.js:

Git Рекомендации по фиксации

У нас есть очень точные правила относительно того, как наши сообщения Git commit могут быть отформатирована. Это приводит к более читаемым сообщениям, которые легко следовать при просмотре истории проекта. Но также мы используем Git зафиксировать сообщения сгенерировать журнал изменений AngularJS.

Формат сообщений. Каждое сообщение фиксации состоит из заголовка, тела и нижнего колонтитула. Заголовок имеет специальный формат, включающий тип, область и тему:

<type>(<scope>): <subject> <BLANK LINE> <body> <BLANK LINE> <footer>

Любая строка сообщения фиксации не может превышать 100 символов! Эта позволяет легче читать сообщение на github, а также в различные инструменты Git.

Тип Должен быть один из следующих:

  • feat: новая функция
  • fix: исправление ошибки
  • docs: только документация изменяется
  • стиль: изменения, которые не влияют на смысл кода (пробел, форматирование, отсутствующие полуколоны и т.д.)
  • refactor: изменение кода, которое не исправляет ошибку или не добавляет функцию
  • perf: изменение кода, которое повышает производительность
  • test: добавление отсутствующих тестов
  • chore. Изменения в процессе сборки или вспомогательных инструментах и ​​библиотеках, таких как создание документации.

Сфера охвата Область может быть любым, определяющим место изменения фиксации. Например $location, $browser, $compile, $rootScope,

ngHref, ngClick, ngView и т.д.

Тема Тема содержит краткое описание изменения:

  • используйте императивное, настоящее время: "изменение" не "изменено", не "изменяется"
  • не использовать первую букву
  • нет точки (.) в конце

Тело Так же, как в субъекте, используйте императивное, настоящее время: "изменение" не "изменено", не "изменяется". Тело должно включать

мотивация для изменения и сопоставление этого с предыдущим поведением.

Нижний колонтитул Нижний колонтитул должен содержать любую информацию о Breaking Changes, а также место для ссылки на проблемы GitHub, что это

commit Закрывает.

Подробное описание доступно здесь.

Пример:

fix (ngOptions): ngModel необязательно

Ответ 5

Мои 5 центов, следующая ссылка для git, но в любом случае может оказаться полезной:

http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

Основная вещь (в соответствии с этой статьей) заключается в том, чтобы написать сначала краткое описание (50 символов), а затем вы можете подробно описать материал, оставаясь всегда менее чем на 72 символа.

Ответ 6

  • Идентификатор ошибки: (если применимо)
  • Изменить описание:
  • Код Пересмотрены:
  • Тестирование модуля:
  • Значок целевой публикации:

Ответ 7

Одна вещь, которую я всегда делаю, заключается в следующем: если изменение вызвано каким-то программным обеспечением для отслеживания ошибок/следов, то обязательно укажите идентификатор ошибки. Таким образом, легче отслеживать все изменения, связанные с ошибкой на более позднем этапе.

Пример:

BugID: 2345 Добавлена ​​проверка ввода пользователя во избежание эксплойта.

Ответ 8

Мы используем Altassian JIRA для отслеживания ошибок и Subversion для нашего исходного элемента управления. JIRA имеет приятную функцию, в которой он может отслеживать коммиты, связанные с этой ошибкой, и помещать их в историю разрешений ошибок.

Таким образом, формат, который мы обычно принимаем, это:

PROJECTCODE - 1234: Достаточно подробное описание произведенных изменений

Под "разумно подробным" я имею в виду, что вы не просто добавляете "исправленную ошибку" или "измененную реализацию", вы обычно добавляете описание, которое не является очень конкретной ошибкой, все еще говорит о том, что на самом деле было сделано, например, "Стратегия сортировки для SortingMethod() была изменена с сортировки пузырьков на quicksort для повышения производительности".

Ответ 9

Мы префикс каждой строки комментария символом + или -, чтобы указать, должен ли он быть включен в список изменений выпуска. Список изменений (или, по крайней мере, первый черновик) может быть автоматически сгенерирован из нашего журнала контроля версий.

Кроме того, у нас есть ключевое слово (выбранное из конечного набора), чтобы указать тип фиксации (исправление ошибок, новая функция, порядок и т.д.), а затем короткий комментарий, описывающий изменение, со ссылками на нашу проблему система отслеживания.

[+/-][Keyword]: [Description]

Общий формат может быть принудительно применен с фиксацией фиксации, но описания все равно должны быть проверены человеком, чтобы убедиться, что все делают полезные сообщения о фиксации.

Ответ 10

Мы не заботимся о свободном тексте, но каждый должен ввести идентификатор бигтрейкового билета задачи, к которой принадлежит комманда, и кто оценил его код.

Первый может генерировать небольшие накладные расходы для быстрых исправлений, но это может быть спасателем жизни. Имея фактическую причину каждой отдельной строки кода, очень ценно.

Второй - это просто призыв к экспертным обзорам.

Ответ 11

Я думаю, что идентификатор ошибки (если он есть) - хорошая идея.

Одна из моих любимых функций FogBugz заключается в том, что вы можете настроить hook script, чтобы при вводе идентификатора ошибки в журнале фиксации информация о фиксации добавляется в случай FogBugz. enter image description here

Изображение из здесь


Помимо этого, просто напишите что-нибудь значимое в , почему сделанные вами изменения.

Ответ 12

Рассмотрим следующие рекомендации, которые следует за git: http://git.kernel.org/cgit/git/git.git/tree/Documentation/SubmittingPatches?id=HEAD

В частности:

(2) Опишите ваши изменения.

В первой строке сообщения фиксации должно быть короткое описание (50 символы - это мягкий предел, см. ОБСУЖДЕНИЕ в git -commit (1)) и должен пропустить полную остановку. В большинстве случаев это также условно префикс первой строки "area:", где область является именем файла или идентификатор для общей области изменяемого кода, например

. архив: контрольная сумма заголовка ustar вычисляется без знака

. git -cherry-pick.txt: уточнить использование нотации диапазона версий

Если у вас есть сомнения, какой идентификатор использовать, запустите "git log -no-merges" на файлы, которые вы изменяете, чтобы видеть текущие соглашения.

Тело должно содержать содержательное сообщение фиксации, которое:

. объясняет проблему, которую пытается решить изменение, о том, что не так     с текущим кодом без изменения.

. оправдывает то, как изменение решает проблему, так почему     результат с изменением лучше.

. альтернативные решения считаются, но отбрасываются, если они есть.

Опишите ваши изменения в императивном настроении, например. "make xyzzy do frotz" вместо "[Этот патч] делает xyzzy do frotz" или "[I] изменен xyzzy делать frotz", как будто вы отдаете приказы на изменение кода его поведение. Постарайтесь убедиться, что ваше объяснение можно понять без внешних ресурсов. Вместо того, чтобы указывать URL-адрес списка рассылки архив, подытожим соответствующие моменты обсуждения.

Когда это зависит от меня, я оставляю тело пустым, если первая строка сообщения фиксации кажется самоочевидной.

Ответ 13

Мне очень сложно получить сообщения о фиксации. Почему бы не предложить это:

Каждое сообщение о фиксации должно начинаться с идентификатора ошибки/задачи, который разрешен фиксацией. Все остальное - просто болтовня...

Ответ 14

Мой предпочтительный формат сообщения фиксации основан на "Как написать коммандное сообщение" от Chris Beams, а также Джоэл Паркер Хендерсон "активные глаголы" и несколько моих собственных идей:

  • Введите идентификатор проблемы.. Это упрощает просмотр соответствующего номера случая без необходимости поиска в теле сообщения фиксации.
  • Объясните решаемую проблему с точки зрения конечного пользователя (если применимо). Эта часть должна быть нетехническим, кратким обзором высокого уровня. Это может несколько дублировать контент в системе отслеживания проблем, но это нормально. При анализе истории фиксации я не хочу открывать проблему в системе отслеживания, чтобы понять основы каждой фиксации.
  • Что вызвало это с точки зрения развития. Кто-то случайно вводил плохую логику путем копирования/вставки? Просмотрите историю фиксации, чтобы узнать, что произошло. Если вы просто не знаете, что вызвало это, то прекратите писать: "Я не знаю, почему это было нарушено". По крайней мере, следующий разработчик будет знать, что вы просто догадывались.
  • Почему это изменение исправляет его. Почему новый код более корректен, чем старый код? Если вы не можете определить, почему старый код был неправильным, что заставляет вас думать, что новый код прав?

Формат:

IssueID: Short description (starting with one of the "active verbs")

Concise overview of problem (ideally from the end-user perspective). 
Caused by (technical reasons go here).
Fixed by (technical fix explanation goes here).

Пример:

995: Fix JS error on landing page preventing sign-in

It wasn't possible to sign in on the landing page because the email and 
password inputs were not being displayed. 
Caused by invalid logic accidentally introduced by #994 which assumed 
that the user was already signed in, thus attempting to render the 
welcome message with the user name (which isn't yet accessible since 
they're not signed in). 
Fixed by changing the logic to check if the user is already signed in 
before attempting to render the welcome message.

В приведенном выше примере вы должны быть в состоянии сказать, в чем проблема, как это получилось, и почему я считаю, что эти изменения являются правильным способом устранения проблемы. Вам даже не нужно видеть код, чтобы понять, что было изменено и почему.

Для тривиальных изменений, совершенно нормально опустить тело фиксации (и даже номер проблемы, если изменение не связано с любыми отслеживаемыми проблемами).

Примеры:

Cut old dead code
Document User.setAddress
Refactor User.getName for readability
564: Add missing name to profile page
Bump lodash to latest version