Перевод статьи: Лучшая практика создания Git Commit'ов от OpenStack / forpes.ru

Главная
Перевод статьи: Лучшая практика создания Git Commit'ов от OpenStack

Перевод статьи: Лучшая практика создания Git Commit'ов от OpenStack +34

01.06.2017 12:31

progga 3 10200 Источник

Предлагаю читателям "Хабрахабра" перевод статьи "Хорошая практика в сообщении коммитов от OpenStack".

1 Git Commit Лучшая практика

Следующий документ основан на опыте разработки кода, устранении ошибок и просмотре кода в ряде проектов, использующих Git, включая libvirt, QEMU и OpenStack Nova. Рассмотрение других проектов с открытым исходным кодом, таких как Kernel, CoreUtils, GNULIB а также других, предполагает, что все они следуют достаточно распространенной практике. Это мотивировано желанием улучшить качество истории Git проекта Nova. Качество — это абстрактный термин для определения в разработке; когда для одного человека некий код «Красивый» (Thing of Beauty) — то для другого это «Костыль» (Evil Hack). Тем не менее мы можем сформулировать некоторые общие рекомендации о том, как и что делать, или, наоборот, чего не делать, когда отправляют Git коммиты для слияния с проектами в OpenStack.

Эта тема может быть разделена на две области:

Порядок объединения или разбиения на несколько коммитов
Информация в сообщениях коммитов

Содержание

1 Git Commit Лучшая практика

1.1 Краткий обзор

Мысли и примеры, описанные в этом документе должны ясно продемонстрировать важность разбиения изменений в группу последовательных коммитов, а также важность написания хороших сообщений к ним. Если эти инструкции будут широко применяться, это значительно улучшит качество истории git'а OpenStack. Кнут и пряник необходимы для эффективного изменения истории git'a. Этот документ должен быть пряником, обращая внимание людей на выгоду и пользу, пока для других использование системы коллективного инспектирования кода Gerrit будет действовать как кнут. ;-P

Другими словами, при инспектировании в Gerrit’е, не просто нужно смотреть на корректность кода. При инспектировании сначала нужно изучить сообщение коммита и указать на улучшения самого сообщения. Приглядитесь к коммитам, которые объединяют множество логических изменений и потребуйте у отправителя разбить их на раздельные коммиты. Убедитесь что изменения с форматированием отступов не объединяются с функциональными изменениями. Также убедитесь, что рефакторинг кода зафиксирован отдельно от функциональных изменений, и так далее.

Также нужно упомянуть, что обработка Gerrit’ом серии патчей не совсем идеальна. Однако не стоит считать это веской причиной, чтобы избегать создания серии патчей. Используемые инструменты должны подчиняться потребностям разработчиков, и поскольку они с открытым исходным кодом, они могут быть исправлены или улучшены. Исходный код «часто читают, время от времени пишут», и, следовательно, наиболее важным критерием является улучшение долговременной поддержки кода при помощи большого количества разработчиков в сообществе, и не стоит жертвовать многим из-за одного автора, который может быть никогда не прикоснется к коду вновь.

А теперь подробные принципы, а также примеры хорошей и плохой практики.

1.2 Структурное разделение изменений

Основным правилом для создания хороших коммитов является предоставление только одного «логического изменения» для каждого коммита. Есть множество причин, по которым это важное правило:

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

1.2.1 Чего нужно избегать при создании коммитов

Необходимо знать и понимать часто встречающиеся примеры плохой практики, чтобы их избегать:

Смешение форматирования отступов и пробелов с функциональными изменениями кода.

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

Смешивание двух несвязанных функциональных изменений.

Опять же рецензенту будет труднее выявить недостатки, если смешать два несвязанных изменения. Если возникнет необходимость в более позднем откате сломанного коммита, необходимо будет разобраться и распутать два несвязанных изменения с дополнительным риском создания новых ошибок.

Отправка больших новых функций в одном гигантском коммите.

Вполне возможно, что код для новой функции полезен только тогда, когда присутствует вся реализация. Однако, это не означает, что вся функция должна предоставляться в одном коммите. Новые функции часто влекут за собой рефакторинг существующего кода. Весьма желательно, чтобы любой рефакторинг выполнялся в отдельных коммитах, а не в тех, в которых реализуются новая функция. Это поможет рецензентам и наборам тестов подтвердить, что рефакторинг не имеет непреднамеренных функциональных изменений. Даже недавно написанный код часто можно разделить на несколько частей, которые могут быть независимо рассмотрены. Например, изменения, которые добавляют новые внутренние API или классы, могут быть в отдельных коммитах. Опять же, это приводит к упрощению проверки кода. Это также позволяет другим разработчикам получать маленькие куски работы при помощи git cherry-pick, если новая функция не совсем готова к слиянию. Добавление новых публичных HTTP API или RPC-интерфейсов должно быть выполнено в коммитах, отдельных от фактической внутренней реализации. Это побудит автора и рецензентов подумать об общем дизайне API или RPC, а не просто выбрать дизайн, который проще для выбранной в настоящий момент внутренней реализации. Если патч влияет на публичный HTTP, используйте флаг APIImpact (см. Включение внешних ссылок).

Главное следовать правилу:

Если изменение кода можно разбить на последовательность патчей или коммитов, то оно должно быть разделено. Меньше - НЕ больше. Больше это больше.

1.2.2 Примеры плохой практики

Теперь немного проиллюстрируем примеры из истории Git Nova. Примечание: хоть хэши коммитов цитируются для ссылки, имена авторов удалены, поскольку мы не должны обвинить или оскорбить ни одного человека. Время от времени каждый из нас виноват в нарушении правил хорошего тона. Кроме того, люди, которые рецензировали и одобряли эти коммиты, так же виновны, как и тот, кто их написал и отправил;

1.2.2.1 Пример 1

Коммит: ae878fc8b9761d099a4145617e4a48cbeb390623
Автор: [удалено]
Дата: Пт. 1 Июня 01:44:02 2012 г. +0000

Рефакторинг вызовов метода create libvirt

 * Сводит к минимуму дублирование кода для create
 * Заставляет срабатывать wait_for_destroy при выключении
   вместо undefine
 * Позволяет уничтожить экземпляр при выходе из домена
 * Использует reset для жесткой перезагрузки вместо create / destroy
 * Заставляет resume_host_state использовать новые методы
   вместо hard_reboot
 * Заставляет rescue/unrescue не использовать жесткую перезагрузку
   для пересоздания домена

Change-Id: I2072f93ad6c889d534b04009671147af653048e7

В этом коммите выполнено как минимум два независимых изменения.

Переход на использование нового reset API в методе «hard_reboot»
Корректировка методов внутреннего драйвера, чтобы не использовать "hard_reboot"

В чем же тут проблема:

Во-первых, нет никаких веских причин, по которым эти изменения необходимо было вносить одновременно (в одном коммите). Первый коммит мог включать изменения для прекращения вызова в разных местах метода «hard_reboot». Второй коммит мог бы переписать реализацию «hard_reboot».
Во-вторых, переход на использование метода reset libvirt был запрятан в большом рефакторинге кода, и рецензенты это пропустили, а ведь это вводило зависимость от более новой версии API libvirt. Этот коммит был найден как проблемный достаточно быстро, но тривиальный откат невозможен из-за большого числа несвязанных изменений.

1.2.2.2 Пример 2

Коммит: e0540dfed1c1276106105aea8d5765356961ef3d
Автор: [удалено]
Дата: Cр. 16 Мая 15:17:53 2012 +0400

Документ lvm-disk-images

Добавлена возможность использования томов LVM для дисков VM.

Реализует поддержку LVM дисков для драйвера libvirt.

VM-диски будут храниться на томах LVM в группе томов
 указанных параметром `libvirt_images_volume_group`.
 Другой параметр `libvirt_local_images_type` указывает, какой тип
 хранилища будет использоваться. Поддерживаются значения: `raw`,
 `lvm`, `qcow2`, `default`. Если `libvirt_local_images_type` =
 `default`, будет использоваться с флагом `use_cow_images`.
Логический параметр `libvirt_sparse_logical_volumes` управляет тем,
 какого типа логические тома будут создаваться (распределенные с
 помощью virtualsize или обычные логические тома с полным
 выделением пространства). Значение по умолчанию для этой
 опции `False`.
Коммит вводит три новых класса: `Raw`, `Qcow2` и `Lvm`. В них
 содержатся логика создания образа, которая была сохранена в
 методах `LibvirtConnection._cache_image` и` libvirt_info`
 благодаря чему создаются правильные конфигурации `LibvirtGuestConfigDisk`
 для libvirt. Класс `Backend` выбирает, какой тип образа будет
 использоваться.

Change-id: I0d01cb7d2fd67de2565b8d45d34f7846ad4112c2

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

Заменен флаг конфигурации «use_cow_images» новым флагом «libvirt_local_images_type» с поддержкой обратной совместимости для устаревшего флага «use_cow_images».
Создание внутреннего класса «Image» и реализация подклассов Raw & QCow2.
Рефакторинг libvirt драйвера для замены кода управления образами raw / qcow2, при помощи вызова нового класса «Image».
Внедрение новой реализации класса образа «LVM».

1.2.3 Примеры хорошей практики

1.2.3.1 Пример 1

Коммит: 3114a97ba188895daff4a3d337b2c73855d4632d
Автор: [удалено]
Дата: Пн. 11 Июня 17:16:10 2012 +0100

Обновление политик по умолчанию для KVM гостевых VM таймеров PIT и RTC

Коммит: 573ada525b8a7384398a8d7d5f094f343555df56
Автор: [удалено]
Дата: Вт. 1 Мая 17:09:32 2012 + 0100

Добавлена поддержка настройки часов и таймеров VM libvirt

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

1.2.3.2 Пример 2

Коммит: 62bea64940cf629829e2945255cc34903f310115
Автор: [удалено]
Дата: Пт. 1 Июня 14:49:42 2012 -0400

Добавлен комментарий к методу rpc.queue_get_for().
Change-Id: Ifa7d648e9b33ad2416236dc6966527c257baaf88

Коммит: cf2b87347cd801112f89552a78efabb92a63bac6
Автор: [удалено]
Дата: Ср. 30 Мая 14:57:03 2012 -0400

Добавлены методы shared_storage_test для вычисления rpcapi.
...пропуск...
Добавлен get_instance_disk_info в метод вычисления rpcapi.
...пропуск...
Добавлен remove_volume_connection в метод вычисления rpcapi.
...пропуск...
Добавлен compare_cpu в метод вычисления rpcapi.
...пропуск...
Добавлен get_console_topic() в метод вычисления rpcapi.
...пропуск...
Добавлен refresh_provider_fw_rules() в метод вычисления rpcapi.
... много других коммитов ...

Эта последовательность коммитов реорганизовала весь слой API RPC внутри OpenStack Compute (Nova), чтобы можно было использовать реализацию подключаемых систем сообщений. Для такого существенного изменения основной части функциональности, было ключевым моментом разделение работы на большую последовательность коммитов, позволяющим сделать осмысленную проверку кода, а также упростило отслеживание изменений и поиск возможных регрессий на каждом этапе процесса.

1.3 Информация в сообщениях коммитов

Текст сообщения коммита является таким же важным, как и само изменения кода. При создании сообщения есть некоторые важные вещи, которые нужно помнить:

Не предполагайте, что рецензент понимает, в чем изначально была проблема.

Часто не всегда бывает ясно в чем была проблема, даже если были прочитаны отчеты об ошибках (bug report), а также пару комментариев. Сообщение о коммите должно содержать четкое изложение исходной проблемы. Конкретный баг — это только лишь интересная историческая справка о том, как проблема была выявлена. Рецензенту должно быть понятно что же делает предложенный патч для правильности принятия решения, не изучая этот дефект в системе отслеживания ошибок.

Не предполагайте, что у рецензента есть доступ к внешним веб-сервисам или сайтам.

Через 6 месяцев, когда кто-то в поезде / самолете / автобусе / пляже / баре будет устранять проблему и просматривать историю git'a, нет гарантий, что у него будет доступ к онлайн-отчету об ошибках или к серверу с документацией. Распределенные системы управления исходным кодом (SCM) сделали большой шаг вперед в том, что вам больше не нужно быть «онлайн», чтобы иметь доступ ко всей информации в репозитории. Сообщение коммита должно быть полностью самодостаточным, чтобы продолжать извлекать пользу из git'a.

Не предполагайте, что код самоочевиден / самодокументирован.

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

Опишите, почему изменения были сделаны.

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

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

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

Обеспечьте достаточной информацией для принятия правильного решения что именно проверять.

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

Первая строка коммита является наиболее важной.

В Git первая строка сообщения коммита имеет особое значение. Она используется в качестве темы электронного письма, в сообщениях команды git annotate, в программе gitk viewer, при слиянии ветки и многих других местах, где места для текста не так уж и много. Помимо краткого описания самого изменения, следует не забывать, какая часть кода затронута. Например, если это влияет на драйвер libvirt, укажите «libvirt» где-нибудь в первой строке.

Опишите любые ограничения текущего кода.

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

Не включайте комментарии, которые относятся исключительно к этому патчу.

Другими словами, если вы переделаете свой коммит, пожалуйста, не добавляйте «Патч №2: переделан» (Patch set 2: rebased) к вашему сообщению. Это не будет иметь никакого значения после слияния изменений. Однако напишите заметку в Gerrit как комментарий к вашему изменению. Это поможет рецензентам узнать, что изменилось между наборами патчей. Это также относится к комментариям, таким как «Добавлены юнит-тесты», «Исправленны проблемы локализации» или любые другие патчи, которые не влияют на общую цель вашего коммита.

Главное следовать правилу:

Сообщение коммита должно содержать всю информацию, которая необходима для полного понимания и проверки патча на корректность. Меньше - НЕ больше. Больше это больше.

1.3.1 Включение внешних ссылок

Хоть сообщение в основном и предназначено для интерпретации человеком, в нем всегда присутствуют метаданные, предусмотренные для машинной обработки. В OpenStack'а в них включают «Change-Id» (Идентификатор изменения), а также необязательные ссылки на идентификаторы «bug», ссылки на «blueprint» (схемы/документы), флаг DocImpact, флаг APIImpact и флаг SecurityImpact.

Строка «Change-Id» представляет собой уникальный хеш, описывающий изменение, которое генерируется перехватчиком Git'а (hook). Она не должна меняться после инспектирования при редактировании коммита командой rebase, так же оно используется системой Gerrit для отслеживания версий патча.
Строка 'bug' может ссылаться на ошибку несколькими способами. Gerrit создает ссылку на ошибку при просмотре патча на сайте review.openstack.org, чтобы рецензенты могли быстро получить доступ к ошибке в Launchpad.
- Closes-Bug: #1234567 — используйте «Closes-Bug», если коммит предназначен для полного устранения и закрытия ошибки на которую ссылаетесь.
- Partial-Bug: #1234567 — используйте 'Partial-Bug', если коммит — это только частичное исправление и требуется еще работа для устранения этого бага.
- Related-Bug: #1234567 — используйте 'Related-Bug', если коммит просто связан с указанной ошибкой.
В строке 'blueprint' должно быть указано имя Launchpad blueprint (документация на сайте Launchpad), если коммит предназначен для реализации некой функции. Gerrit создает ссылку на blueprint при просмотре патча на сайте review.openstack.org, чтобы рецензенты могли быстро получить доступ к документу на Launchpad.
Строка DocImpact содержит строку DocImpact и комментарий о том, почему это изменение влияет на документацию. Поместите DocImpact в отдельную строку. Используйте этот флаг, чтобы указать, что документация содержится в патче, или изменение затрагивает документацию, чтобы рецензенту можно было понять о причинах изменений. Включите как можно больше информации. Когда этот флаг включен в сообщение о фиксации, Gerrit создает bug-report для проекта openstack-manuals (инструкции openstack) для отслеживания и очередности выполнения, или перемещает если необходимо, в openstack-api-site.
Строка APIImpact содержит строку APIImpact и комментарий о том, почему это изменение влияет на общедоступный HTTP API. Поместите APIImpact на отдельную строку. Используйте этот флаг, чтобы указать, что патч создает, обновляет или удаляет общедоступный HTTP API или изменяет поведение общедоступного API. Включите как можно больше информации. Когда этот флаг включен в сообщение фиксации, все связанные отзывы можно найти с помощью этой ссылки, также страница из документации API_Working_Group может помочь в поиске релевантных отзывов. Кроме того, с рабочей группой API (API Working Group) можно напрямую связаться по IRC в канале Freenode #openstack-sdks.
Строка SecurityImpact просто содержит строку SecurityImpact. Она используется, чтобы указать, что изменение имеет последствия для безопасности и должно быть пересмотрено группой OpenStack Security Group.
Строка UpgradeImpact содержит строку UpgradeImpact и комментарий о том, почему это изменение влияет на обновления. Она используется, чтобы указать, что изменение имеет последствия обновлений для тех, кто делает непрерывное развертывание (continuous deployment), или от N до N + 1 апдейтов. Также возможно указывает на обновления раздела «Upgrade Notes» (Примечания по обновлению) в примечаниях к выпуску для затронутого проекта.

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

Примечание: Хотя во многих проектах с открытым исходным кодом, использующих Git является популярной практикой включать тэг «Signed-off-by» (Подписан) (генерируемого при помощи команды «git commit -s»), для OpenStack это не обязательно. Прежде чем получить возможность отправить код в Gerrit, OpenStack требует, чтобы все участники подписали CLA (Contributor License Agreement, Лицензионное соглашение для участников), что служит для эквивалентной цели.

Мы поощряем использование Co-Authored-By: name name@example.com (Соавторство) в сообщениях коммита, чтобы указать людей, которые работали над определенным патчем. Это является соглашением о признании нескольких авторов, и наши проекты призывают инструменты сбора статистики следить за этими полями при их анализе.

1.3.2 Краткий обзор структуры сообщений коммитов

В первой строке представьте небольшое описание изменений.
Вставьте пустую строку после первой строки.
В следующих строках напишите подробное описание изменений, разбив на пункты там, где это необходимо.
Первая строка должна быть ограничена 50 символами и не должна заканчиваться точкой.
Последующие строки должны быть заключены в 72 символа.
- vim (по умолчанию в переменной среды $EDITOR на большинстве дистрибутивов) может автоматически обернуть строки для вас. В большинстве случаев вам просто нужно скопировать файл примера vimrc (который можно найти где-нибудь, например /usr/share/vim/vim74/vimrc_example.vim) в ~/.vimrc, если у вас его нет.
- После редактирования абзаца его можно обернуть, нажав клавишу escape, поместив курсор внутри абзаца и введя комбинацию gqip.
Поместите строки «Change-id», «Closes-Bug #NNNNN» и «blueprint NNNNNNNNNNNN» в самом конце если это необходимо.

Например:

Переключение метода libvirt get_cpu_info на использование конфигурации API

Метод get_cpu_info в драйвере libvirt в настоящее время использует
запросы XPath для извлечения информации из возможностей
XML документа. Переключение на использование нового класса
конфигурации LibvirtConfigCaps. Также добавили тестовый случай для
проверки возвращаемых данных.

DocImpact
Closes-Bug: #1003373
Implements: blueprint libvirt-xml-cpu-model
Change-Id: I4946a16d27f712ae2adf8441ce78e6c0bb0bb657

1.3.3 Некоторые примеры плохой практики

Посмотрим немного примеров из истории Git Nova, опять же с удаленными именами авторов, так как мы не хотим никого обвинить или оскорбить.

1.3.3.1 Пример 1

Коммит: 468e64d019f51d364afb30b0eed2ad09483e0b98
Автор: [удалено]
Дата: Пн. 18 Июня 16:07:37 2012 -0400

Исправление отсутствующего импорта в compute/utils.py

Fixes bug #1014829

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

Добавить отсутствующий импорт "exception" в compute/utils.py

nova/compute/utils.py делает ссылку на класс исключения
exception.NotFound, однако исключение не было импортировано.

1.3.3.2 Пример 2

Коммит: 2020fba6731634319a0d541168fbf45138825357
Автор: [удалено]
Дата: Пт. 15 Июня 11:12:45 2012 -0600

Предоставляет правильный формат ec2id для томов и снимков

Fixes bug #1013765
* Добавлен аргумент шаблона в вызовы ec2utils.id_to_ec2_id()

Change-Id: I5e574f8e60d091ef8862ad814e2c8ab993daa366

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

Представляет правильный формат ec2id для томов и снимков

Во время миграции uuid'а тома, выполненной набором изменений
XXXXXXX, форматы идентификаторов ec2 для томов и моментальных
снимков были удалены и теперь используют по умолчанию формат
экземпляра (i-xxxxx). Идентификаторы необходимо вернуть обратно
к vol-xxx и snap-xxxx.

Добавляет аргумент шаблона для вызовов ec2utils.id_to_ec2_id ()

Fixes bug #1013765

1.3.3.3 Пример 3

Коммит: f28731c1941e57b776b519783b0337e52e1484ab
Автор: [удалено]
Дата: Ср. 13 Июня 10:11:04 2012 -0400

Добавлена проверка минимальной версии libvirt.

Fixes LP bug #1012689

Change-Id: I91c0b7c41804b2b25026cbe672b9210c305dc29b

Проблема: в этом коммите сообщение просто документирует, что было сделано, а не почему это было сделано. Нужно было упомянуть, что ранее набор изменений ввел новую минимальную версию libvirt. Также нужно было сообщить, какое текущее поведение, если проверка не проходит.
Например:

Добавлена проверка версии libvirt, минимум 0.9.7

В коммите XXXXXXXX введено использование API сброса 'reset'
которое доступно только в libvirt 0.9.7 или новее. Добавлена
проверка версии перед libvirt версии подключения, выполняющаяся
при запуске вычислительного сервера. Если проверка версии завершилась
неудачей, служба будет завершаться.

Fixes LP bug #1012689

Change-Id: I91c0b7c41804b2b25026cbe672b9210c305dc29b

1.3.4 Примеры хорошей практики

1.3.4.1 Пример 1

Коммит: 3114a97ba188895daff4a3d337b2c73855d4632d
Автор: [удалено]
Дата: Пн. 17 Июня 17:16:10 2012 +0100

Обновление политик по умолчанию для KVM гостевых VM таймеров PIT и RTC

Политики по умолчанию для таймеров PIT и RTC для гостевой системы
KVM плохо поддерживают надежность времени (часов) в гостевых
операционных системах. В частности, гостевые Windows 7
часто приводят к сбою политик таймера KVM по умолчанию, а старые
гостевые Linux системы будет иметь сильное смещение времени.

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

Устанавливает RTC таким образом, чтобы пропущенные тики вводились с
более высокой скоростью, для того чтобы 'догонять'

Это соответствует следующему libvirt XML

<clock offset='utc'>
  <timer name='pit' tickpolicy='delay'/>
  <timer name='rtc' tickpolicy='catchup'/>
</clock>

И следующие KVM параметры запуска

  -no-kvm-pit-reinjection
  -rtc base=utc,driftfix=slew

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

Closes-Bug: #1011848

Change-Id: Iafb0e2192b5f3c05b6395ffdfa14f86a98ce3d1f

Некоторые вещи, которые следует отметить в этом примере:

Описано, что из себя представляет исходная проблема (плохие настройки KVM по умолчанию)
Описываются функциональные изменения (новые политики PIT / RTC)
Описывается результат изменения (новый XML / QEMU args)
Также описывается область для будущего улучшения (возможная конфигурация типа каждой ОС)
Используется запись Closes-Bug

1.3.4.2 Пример 2

Коммит: 31336b35b4604f70150d0073d77dbf63b9bf7598
Автор: [удалено]
Дата: Ср. 06 Июня 22:45:25 2012 -0400

Добавлена поддержка фильтрации планировщика архитектуры CPU

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

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

Драйвер libvirt запрашивает гостевые возможности
хоста и сохраняет архитектуры гостевых ОС в списке
permitted_instances_types в словаре cpu_info хоста.

Для Xen позже будет сделан эквивалентный коммит.

Фильтр архитектуры будет сравнивать архитектуру экземпляра с
списком permitted_instances_types хоста и отфильтровывать
недействительные хосты.

Также добавляет ARM как действительную архитектуру к фильтру.

По умолчанию ArchFilter не включен.

Change-Id: I17bd103f00c25d6006a421252c9c8dcfd2d2c49b