openSUSE:Руководство по оформлению патчей

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

Жизненный цикл исправлений

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

  • Исправление добавлено в пакет
  • В исправление внесены изменения
  • Исправление отключено (но не удалено)
  • Исправление удалено из состава пакета

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

Любой из этих этапов должен быть зафиксирован в файле .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, становится намного проще.


Текущий список аббревиатур

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

Этот список не является авторитетным, пожалуйста, проверьте как они определены в Open Build Service (osc api /issue_trackers). Также можно оставить запрос для добавления нового трекера в github-проекте.
Между сокращением и номером ошибки не должно быть символов пробела.
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 может быть найден здесь.