Hard to be a Maintainer

Василий Хоружик, Минск, Belarus

LVEE 2012

Patch submitting guide. Describes single iteration of getting your code upstream: code modification, creating patch, submitting patch, getting review.

Введение

Сообщество open source широко известно своим подходом “Если тебе что-то не нравится, возьми и исправь”. Но на самом деле испоправить недочеты в программном коде - это только половина задачи. Вторая и главная часть - добится включения патча в апстрим.

Зачем?

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

Мэйнтэйнеры

На самом деле большой проект, даже такой сложный, как ядро Linux - всего лишь программа, а её мэйнтейнер(ы) - обычные люди. Всё что требуется от автора патча - это привести патч в приемлимый вид и отправить нужному человеку (людям).

Coding Style

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

Необходимо выяснить, как принято писать код в данном конкретном проекте. Часто у проекта есть соответствующий документ, например linux/Documents/CodingStyle. Есть смысл заранее настроить соответствующим образом свой текстовый редактор, либо переформатировать код в соответствии со стандартом проекта. А в некоторых случаях такие параметры уже подобраны, и даже готов соответствующий скрипт, например Lindent (linux/scripts/Lindent).

В некоторых проектах (u-boot, Linux, qemu) есть скрипт для проверки патча на соответствие стиля кодирования принятым нормам (scripts/checkpatch.pl)

Система контроля версий

Разработчики очень редко используют релизные версии (снапшоты) своих проектов. Пытаться добится включения патча в релизную версию кода - сомнительное предприятие. По всей видимости, для продвижения патча в апстрим понадобится освоить git (svn, hg, или другую систему контроля версий, которую используют в данном проекте).

В случае git всё выглядит просто:

• git clone git://project.url my_local_project - создать локальный клон удалённого репозитория
• git diff [—cached] - просмотреть текущие [добавленные] изменения
• git add file_name.1 file_name.2 - добавить изменения для фиксации
• git commit - фиксация изменений, для большинства проектов обязательна опция -s (т.н. Sign-Off)
• git format-patch id_коммита - сформировать патчи для коммитов, начиная с коммита, следующего за указанным.

Куда отсылать

После очередной вычитки патча, прогона через checkpatch.pl наступает момент для отправки его на первый review. Кому именно отсылать - зависит от проекта, причем обычно это написано в README. Для Linux и u-boot есть скрипт get_maintainer.pl (находится в linux/scripts), который анализирует патч и определяет, кому его отправить (выдает список адресов).

Отсылать патчи для проектов, которые используют git, лучше всего с помощью git send-email. Используя какой-либо почтовый клиент, следует убедиться, что он не переносит строки, не заменяет табуляцию пробелами, и вообще ничего не изменяет в патче. Слать патч прикреплённым к письму считается дурным тоном, т.к. его в таком виде неудобно просматривать и комментировать. Поэтому патч нужно ’’включать’’ в письмо (inline).

Как правило, приходится отправлять сообщение и в список рассылки (на который лучше всего подписаться), и конкретному человеку (добавляя его адрес в поле CC:).

Для ядра Linux, если вы хотите включения изменения в релизную ветку ядра, также стоит ставить в копию stable@vger.kernel.org.

Review

Как правило, мэйнтейнеры отвечают на письмо с патчем, “разбавляя” его комментариями. Очень редко всё получается с первого раза; Как правило, автор получает в ответ пачку рекомендаций по доводке своего кода. Это нормальное явление, поскольку контрибуция в открытый проект является итеративным процессом, а вы в этот момент находитесь на первой итерации. Также не имеет смысла спорить с мэйнтейнером по поводу каждой строчки кода. Мэйнтейнер практически всегда прав. Несколько рекомендаций:

• Процедура выглядит следующим образом: получить комментарий — поправить патч — отослать снова, с пометкой ‘v2’ (или ‘vN’). Лучше не затягивать, т.к. при долгих итерациях патч может устареть или мэйнтейнер может забыть контекст.
• При долгом отсутствии ответа может потребоваться послать письмо-напоминание. Мэйнтейнер - обычный человек, он может быть занят или загружен работой, или просто забыть о Вас.
• Не имеет смысла ругайться с мэйнтейнером. В крайнем случае следует попросить рассудить спор какое-либо третье лицо.
• И, наконец, не следует отчаиваться.

Никогда не следует слать патчи, которые:

• Содержат большие блоки закомментированного кода
• Перемещают файлы без видимых на то причин
• Меняют систему сборки проекта с технологии N на технологию M, без видимых причин и плюсов
• Патчи, реализующие сразу несколько фич либо исправляющие несколько багов. Необходимо следовать правилу “один баг – один патч”, “одна фича – один патч”.

А что если…

Может случится так, что предложенное изменение расходится с точкой зрения мэйнтейнера и/или общей архитектурой проекта. В таком случае существует два выхода:

1. переделать патч
2. инициировать и поддерживать свой собственный форк проекта

Выводы

Итак, работу можно разделить на 4 шага:
1. Правка кода
2. Оформление изменений
3. Отсылка патча
4. Получение review, и при необходимости - возврат к пункту 2.

Не следует останавливаться на первом пункте. Обязательно добивайтесь включения своего кода в апстрим.

Текст тезисов доступен под лицензией Creative Commons Attribution-ShareAlike 3.0.