openSUSE:Руководство по оформлению патчей
Содержание
Жизненный цикл исправлений
Исправления добавляются к пакетам на основании различных причин и, важно, чтобы их жизненный цикл был четко определен. Это помогает предотвратить возникновение ситуаций с утерей исправлений, когда никто не знает почему они были удалены. Жизненный цикл можно задать в следующем виде:
- Исправление добавлено в пакет
- В исправление внесены изменения
- Исправление отключено (но не удалено)
- Исправление удалено из состава пакета
Обязательными являются только крайние стадии, остальные могут быть пропущены.
Любой из этих этапов должен быть зафиксирован в файле .changes, включая имя файла с исправлением. Это необходимо только для удобного чтения людьми, поэтому нет необходимости в жестком следовании понятному только машине формату. Например, описание можно выполнить так:
- Добавлен package-awesomeness.patch: делает пакет удивительным (awesome — удивительный, в переводе с английского).
- Убран package-awesomeness.patch: разработчики сделали программу еще удивительнее.
- Отключен package-awesomeness.patch: Тестирование, могут ли пользователи жить без удивительности.
- Обновлен package-awesomeness.patch для применения к новой версии.
Метки патчей (спец. комментарии)
Для облегчения использования автоматических инструментов и, чтобы помочь будущим сборщикам пакетов — мы пришли к договоренности об использовании следующих категорий для наших патчей:
- Исправления:
- Исправления специфичные для openSUSE, и не интересные разработчикам данного проекта.
- Исправления специфичные для SLE, не интересные разработчикам данного проекта и не нужные в openSUSE.
- Обычные исправления, которые должны быть переданы в соответствующий проект.
- Функционал:
- Функции специфичные для openSUSE (интеграция AppArmor, например), и не интересные разработчикам данного проекта.
- Функции специфичные для SLE, не интересные разработчикам данного проекта и не нужные в openSUSE.
- Функции, которые должны быть добавлены в код исходного проекта. Когда мы добавляем новые функции такого типа, требуется координировать свои действия с авторами данного исходного кода. В этом случае мы можем разработать нечто, что может быть принято в исходный проект без изменений. Когда код нового функционала готов, требуется ещё много работы для его переработки, что бы он был принят в изначальный проект. Так как только авторы проекта знают, насколько данная функциональность соответствует их первоначальному замыслу.
Тип 1: минимальный однострочный комментарий в spec-файле
Чтобы отметить исправления соответствующие описанным выше категориями, установлен стандарт (для .spec файлов) на комментарии к патчам, следующего вида:
# PATCH-FIX-OPENSUSE fix-for-opensuse-specific-things.patch [bnc#123456] Patch1: fix-for-opensuse-specific-things.patch # PATCH-FIX-SLE fix-for-sle-specific-things.patch [bnc#123456] Patch2: fix-for-sle-specific-things.patch # PATCH-FIX-UPSTREAM fix-for-upstream-sources.patch [bnc#123456] Patch3: fix-for-upstream-sources.patch # PATCH-FEATURE-OPENSUSE feature-for-opensuse-specific-things.patch [bnc#123456] Patch4: feature-for-opensuse-specific-things.patch # PATCH-FEATURE-SLE feature-for-sle-specific-things.patch [bnc#123456] Patch5: feature-for-sle-specific-things.patch # PATCH-FEATURE-UPSTREAM feature-for-upstream.patch [bnc#123456] Patch6: feature-for-upstream.patch
Особый случай: иногда нужно временно отключить патч, так как он не может быть применен к последней версии исходных кодов и в его нужно внести соответствующие правки. Не комментируйте объявление патчей, вместо этого закомментируйте место его применения. При пометке исправления, как требующего пересоздания, хорошей идеей будет сохранить старый тег.
# PATCH-NEEDS-REBASE old-patch.patch [bnc#123456] -- Does something old. Was: PATCH-FEATURE-OPENSUSE Patch7: old-patch.patch [...] # %patch7
Не забудьте указать адрес электронной почты автора патча, чтобы с ним можно было связаться, если возникнут какие-либо вопросы. Комментарий в свободной форме можно оставить после последовательности символов " -- ".
Например:
# PATCH-{FIX|FEATURE}-{OPENSUSE|SLE|UPSTREAM} name-of-file.patch bnc#[0-9]* ваш@адрес.org -- this patch makes things totally awesome (это исправление делает все абсолютно превосходным)
Если ошибка зарегистрирована в Novell или другом трекере ошибок, то, пожалуйста, добавьте соответствующую ссылку: с ее помощью можно будет получить больше необходимой информации. Если существует несколько таких ссылок, то укажите их все.
Текущий набор сокращений можно найти в конце этой статьи. Этот список может быть расширен, если это будет необходимо.
Некоторые патчи исправляют ошибки, которые явно не описаны, но об их существовании известно. В этом случае решение остается за создателем пакета. Например, можно поступить одним из следующих способов:
- Если в скором времени должен состояться выпуск новой версии, то создайте соответствующее сообщение в системе отслеживания ошибок. Как правило, это обязательно и, даже, если это не так — все равно сделайте это.
- Если выпуск новой версии в скором времени не планируется и ошибка уже исправлена, то в комментарии укажите номер соответствующей ревизии SVN (или какой-либо другой системы контроля версий), а так же, что этот патч не потребуется при следующем обновлении версии.
Тип 2: Указание полной информации в исправлении
В предыдущем стандарте не хватает упоминания о самой важной части патча: описания необходимости использования данного исправления в начале файла. Кроме того, необходимо упомянуть назначение патча (изменения из основного проекта или только для openSUSE, исправления или добавление нового функционала и так далее).
Для исправлений в openSUSE для пакетов ядра традиционно используется следующая форма: данные с описание размещаются непосредственно там, где это необходимо — в самом файле патча. Это облегчает передачу патчей в основной проект, так описание не может быть случайно потеряно, и Git SCM (где используется) знает как сохранить эти метаданные при импорте. Извлечение патчей из Git-репозитория так же проходит с созданием отдельных файлов.
Файлы исправлений должны следовать схеме используя пары "ключ: значение", описание, необязательно со статистикой различий, добавляется к основному куску. Например:
From: Random J Developer <email@address.de> Date: 2012-07-28 01:28:22 +0200 Subject: input: add Acer Aspire 5710 to nomux blacklist References: bnc#404881 Upstream: submitted Acer Aspire needs to be added to nomux blacklist, otherwise the touchpad misbehaves. --- drivers/input/serio/i8042-x86ia64io.h | 7 +++++++ 1 file changed, 7 insertions(+) --- a/drivers/input/serio/i8042-x86ia64io.h +++ b/drivers/input/serio/i8042-x86ia64io.h @@ -371,6 +371,13 @@ static const struct dmi_system_id __init [...]
Рекомендуется использовать например, Quilt, которая сохраняет описания при обновлении. `quilt ref --sort --diffstat -p1` создает/обновляет патчи, сортирует, выдает статистику изменений в формате -p1.
Например:
- From: — указывается адрес электронной почты автора оригинала исправления.
- Date: — дата создания исправления. Желательно использовать формат описанный в ISO-8601 с указанием временной зоны. Если патч был только что создан можно воспользоваться командой `stat your.patch`, чтобы определить время его создания.
- References: ссылки на сообщения в списках рассылки, трекерах ошибок (bugzilla) и так далее. Специальный формат не используется, тем не менее желательно каждый URL указывать так, чтобы их можно было легко открыть в браузере. Смотрите секцию “#Текущий список аббревиатур” ниже.
- Upstream: отношение исправления относительно основного проекта. Специальный формат не используется, хотя используются общие фразы вроде “never”/“no” ("никогда"/"нет"; актуально для openSUSE), “to be done” (tbd, должно быть сделано), “sent”/“submitted” (отправить основным разработчикам; предоставить ссылку, если возможно), “merged” ("объединено", основной разработчик принял исправление; предоставить ссылку, если возможно) и “dead” ("мертво", активности над проектом у основного разработчика не наблюдается).
- Subject: Короткое однострочное описание исправления.
В исправлении нужно оставлять описание. В нем нужно указать, зачем нужен этот патч. Подробность описания будет влиять на решение другого разработчика о необходимости данного исправления, если оно перестанет корректно применяется. При составлении описания постарайтесь указать ответы на три вопроса: "какую команду нужно выполнить?", "Что при этом наблюдается?", "Что ожидалось увидеть вместо этого?". Если известен точный текст сообщения об ошибке, например, когда исправление создано для устранения синтаксической ошибки в файле с исходным кодом, которая приводит к аварийному завершению компиляции, то включите его сокращенную версию в основную часть описания.
Ряд примеров, указывающих на необходимость указывания в исправлении подобных данных можно прочесть (в почтовой рассылке) перейдя по следующим ссылкам: (1) (2) (3)
Имена исправлений
Все новые исправления должны иметь расширение '.patch'.
Вопрос о том, должно ли имя исправления начинаться с имена пакета, является предметом дебатов о стиле. Если есть сомнения, то следуйте соглашениям используемым в пакете с которым вы работаете.
Ни в коем случае НЕ ИСПОЛЬЗУЙТЕ макрос %{version} в строке Patch:, укажите версию вручную. Использование макросов:
- является причиной многочисленных переименований при обновлении версий
- делает простым поиск исправлений, которые больше не нужны
- делает трудным определение времени, когда патч был затронут в последний раз
- делает простым поиск неверных патчей
Исключениями являются патчи, которые исправляют предупреждения компилятора генерирует за счет фиктивного кода. Их часто называют 'abuild.patch'.
Предпочтительным уровнем является -p1, так как делать импорт с помощью таких инструментов как, например, quilt, становится намного проще.
Текущий список аббревиатур
Для избежания путаницы и двойной работы, разрешены ссылки и на другие трекеры ошибок. Ниже представлен список сокращений для часто используемых трекеров, которые должны находится перед символом "#" в идентификаторе ошибки.
| Shortcut | Issue-Tracker-URL | Example |
|---|---|---|
| openSUSE Bug tracker | http://bugzilla.opensuse.org/show_bug.cgi?id=123456 | (boo#123456) |
| Boost | https://svn.boost.org/trac/boost/ | (boost#123456) |
| Clutter Project Bugzilla | http://bugzilla.clutter-project.org/ | (bco#123) |
| CPAN Public Bug Tracker | http://rt.cpan.org/Public/ | (RT#123456) |
| Debian | http://bugs.debian.org/ | (deb#123456) |
| freedesktop.org | http://bugs.freedesktop.org/ | (fdo#123456) |
| GCC | http://gcc.gnu.org/bugzilla/ | (GCC#123456) |
| GNOME | http://bugzilla.gnome.org/ | (bgo#123456) |
| ICCULUS | http://bugzilla.icculus.org/ | (bio#123456) |
| Kernel or K | http://bugzilla.kernel.org/ | (bko#123456) |
| KDE | http://bugs.kde.org/ | (kde#123456) |
| Launchpad (Ubuntu) | https://bugs.launchpad.net/ | (lp#123456) |
| MeeGo | http://bugs.meego.com | (MeeGo#123456) |
| Mozilla | http://bugzilla.mozilla.org/ | (bmo#123456) |
| Novell | https://bugzilla.novell.com/ | (bnc#123456) |
| SUSE bugs | https://bugzilla.suse.com/ | (bsc#123456) |
| OpenLDAP | http://www.openldap.org/its/ | (ITS#123456) |
| OpenOffice.org Issuezilla (obsolete) | http://qa.openoffice.org/issues/ | (i#123456) |
| Fate (Feature tracking tool) | https://fate.suse.com | (fate#123456) |
| RedHat | https://bugzilla.redhat.com/ | (rh#123456) |
| Samba | https://bugzilla.samba.org/ | (bso#123456) |
| Sourceforge | http://sf.net/support/tracker.php?aid=1234567 | (sf#1234567); number is in the "aid=" part in an URL |
| Xamarin | http://bugzilla.xamarin.com/ | (bxc#4321) |
| CVE entries (please add the number, even if there is an additional bugzilla for it) | http://cve.mitre.org | (CVE-2009-0067) |
| Xfce | https://bugzilla.xfce.org/ | (bxo#123456) |
| OBS GitHub Issues | https://api.github.com/repos/openSUSE/open-build-service/issues | (obs#123) |
| OBS build script Issues | https://api.github.com/repos/openSUSE/obs-build/issues | (build#123) |
| OBS CLI Issues | https://api.github.com/repos/openSUSE/osc/issues | (osc#123) |
| Progress openSUSE issue | https://progress.opensuse.org/issues | (poo#123) |
| Linux Foundation | https://developerbugs.linux-foundation.org/ | (lf#1234) |
| SUSE SLE features (epic id should be always used, not dev task id) | https://jira.suse.com/ | (jsc#SLE-1234) |
Для других трекеров ошибок используйте полные URL-адреса (вместо номеров ошибок), в начале файла с исправлением. Например:
Bookmarklet
Сокращение с префиксом bnc# для поиска по bugzilla.novell.com может быть найден здесь.