Руководство по написанию changelog

Материал из ALT Linux Wiki


Этот документ описывает рекомендуемые правила оформления секции %changelog spec-файла пакета и характер/объём включаемой в неё информации.

Примеры

Тривиальный случай:

* Mon Feb 21 2022 Alexey Shabalin <shaba@altlinux> 2.0.112-alt1
- Initial build.

либо

* Thu Feb 24 2022 Denis G. Samsonenko <ogion@altlinux> 1.0.1365-alt1
- new version

Выпуск, включающий совместную работу:

* Sun Jun 08 2008 Dmitry V. Levin <ldv@altlinux> 4.1.2-alt3
- Removed c++filt from alternatives (at@).
- Added libgcj-src subpackage (viy@).
- Moved NLS files to new locales subpackage (closes: #11510).
- Do not package changelog files.

Ещё вариант написания changelog с совместной работой:

* Sun Jun 08 2008 Dmitry V. Levin <ldv@altlinux> 4.1.2-alt3
- Removed c++filt from alternatives (thnx zerg@).
- Added libgcj-src subpackage (thnx Igor Vlasenko).
- Updated russian translation (ALT #21475), thnx Alexandre Prokoudine.

Термины

Здесь

запись
Всё, что относится к сборке 4.6.2-alt7.pre1
группа
имя в квадратных скобках
пункт
текст, начинающийся с дефиса («- make visible_tabs and visible_tws mcedit options configurable through config file (Debian)»)
подпункт
текст, начинающийся с плюса («+ recognize man pages with additional suffixes other than 'x', such as write.3p (Debian)»)
строка
одна строка файла спека («- make visible_tabs and visible_tws mcedit options configurable through config»)

Синтаксис чейнджлога

  • (Опциональная) группа состоит из имени в квадратных скобках и начинается с первой позиции строки.
  • Пункт верхнего уровня начинается с 1-й позиции в строке и состоит из дефиса, пробела и собственно текста.
  • Подпункт начинается с 3-й позиции в строке и состоит из плюса, пробела и собственно текста.
  • Строки переносятся по словам и содержат не более 78 символов. При этом текст новой строки выравнивается по началу текста предыдущей (то есть 3-я позиция для пунктов верхнего уровня и 5-я для подпунктов).
  • Начинать новую строку с символа # нельзя (такая строка будет воспринята как комментарий).
  • При использовании макросов следует экранировать символ "%" ещё одним "%" во избежание раскрытия оных, т.е. напрмер вместо %name следует записать %%name.

Пример:

- syntax:
  + recognize .hh and .hpp as c++ again
  + recognize man pages with additional suffixes other than 'x', such as
    write.3p (Debian)
- make visible_tabs and visible_tws mcedit options configurable through config
  file (Debian)

Содержимое

  • Чейнджлог пишется на английском языке.
  • При сборке новой upstream-версии это указывается первым пунктом.
    • При сборке из снэпшота системы контроля версий необходимо указать информацию, позволяющую идентифицировать это снэпшот (дата и время для CVS, ревизия SVN, 8 первых символов идентификатора коммита для git, mtn, bzr, hg, либо вывод git-describe для git).
  • Изменения, произведённые апстримом (кроме исправлений ошибок безопасности), в чейнджлоге не указываются (для этого есть чейнджлоги апстрима, зачастую включаемые в пакет).
  • Изменения, произведённые силами участников ALT Linux Team как в собственных проектах, так и во внешних проектах перечисляются полностью (конечно только информация, полезная для пользователей).
  • Информация об уязвимостях (CVE и т.д.) в Changelog обязана соответствовать Vulnerability_Policy.
  • Косметические изменения спек-файла, не влияющие на получаемый пакет, указываются максимум одной строкой («spec cleanup»), либо не указываются вовсе. Это не относится к исправлениям тега License, изменениям параметров сборки и т. д.
  • Если в сборке версии существенно принимало участие более одного человека, то изменения, вносимые разными людьми, собираются в группы по авторам, иначе группы не нужны.
  • Исправления, необходимые для успешной сборки, соответствия требованиям ALT Linux и т. д., не указываются, если они были сопряжены с упаковкой новой версии и для старой версии были не нужны (эти исправления — адаптация новой версии, то есть часть процесса её упаковки). Если же они были вызваны изменением требований либо окружения, желательно это указать (пример: «fix FTBFS with new autotools», FTBFS == failure to build from source).
  • Если .spec-файл адаптирован из другого дистрибутива, то майнтейнер вправе как оставить старые записи %changelog, так и удалить их. Следует помнить, что
    • Записи в %changelog содержат информацию о том, как шла разработка пакета до импорта — в них есть адреса майнтейнеров и протокол их действий. Эта информация часто бывает полезной.
    • Сам адаптированный спек является модификацией исходного кода, авторские права на который принадлежат не вам. Некоторые лицензии требуют сохрания атрибуции непосредственно в тексте исходного кода. Самый простой способ сделать это — оставить прошлый %changelog в неприкосновенности
    • Формат унаследованного %changelog может отличаться от принятого в ALT, это иногда приводит к сбою в инструментах работы со спеками.
    • Если вы оставляете исходный %changelog, первую запись о сборке адаптированного пакета стоит делать видимой (традиционно она содержит слова "Initial build for ALT"). Это поможет отделить историю пакета в ALT от исходной истории разработки
  • Используйте спеллчекер :)

Указание источников и контекста

  • Если изменение взято извне либо основано на взятом извне, в соответствующем изменению пункте чейнджлога в скобках указывается источник. Это может быть название дистрибутива/репозитория, название внешней BTS и номер бага в ней, ID участника ALT Linux Team или произвольное указание на человека или сайт. Здесь под изменением подразумевается готовый патч, адаптированный патч или иные аналогичные указания.

Примеры:

- move global configs to /etc (RH)
- linked libnetpbm.so against -lm (RH #165980)
- use optflags (drool@)

Автозакрытие багов

  • Если изменение связано с багрепортом из bugzilla.altlinux.org, в соответствующем пункте можно указать (по вкусу; регистр не учитывается, но обязательно в скобках):
    • (Closes: NNNN)
    • (ALT NNNN)
    • (ALT bug NNNN)

с опциональным двоеточием после ключевого слова и опциональным знаком # перед номером бага. Можно также указать несколько багов: (Closes: NNNN, MMMM, ZZZZ). Перед ключевым словом допускается имя автора с точкой с запятой: (Girar Builder; closes: NNNN).

  • Номера багов в скобках разделяются запятыми (или пробелами).
  • Баг закрывается (RESOLVED FIXED) при коммите задачи. Просматриваются все записи changelog, которые новее версии пакета в целевом репозитории (для нового пакета — записи за последние 3 месяца), а для задачи удаления пакета — сообщение задачи.

Примеры, которые закрывают баги:

- add option to build with libslang2 (closes: 10591)
- fix crash on startup (closes: #10592, #10593)
- recognize .3gp as video, not manpage (ALT #14982, #14999)
- fix build with gcc 15 (ALT#14983)
- fix desktop file (ALT bug: 14984)
- drop obsolete patch (alt bug #14985)

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

- fix crash, closes: #10591 (нет скобок)
- see ALT bug #10591 (нет скобок)
- fix crash (closes: bug 10591) (лишнее слово «bug»)
- fix crash (closes alt #10591) (лишнее слово «alt»)
- fix crashes (closes: #10591 and #10592) (лишнее слово «and»)
- fix crash (closes: #10591; thanks to John Doe) (лишние слова)
- fix crash (altbug #10591) («altbug» слитно)
- fix a very long description of the change that does not fit (closes:
  #10591) (ссылка перенесена на другую строку)

Полный regexp для поиска номеров багов в changelog можно посмотреть здесь.

Указание устраненных уязвимостей

Основная статья: Vulnerability Policy


Лучшие практики оформления changelog

  • Если changelog пакета оформлен единообразно, не нарушайте это единообразие (если оно не противоречит этому руководству). Если же changelog хаотичен, то оставленный перед changelog комментарий о рекомендуемом стиле ведения changelog поможет избежать продолжения хаоса в будущем.
  • Старайтесь, чтобы все предложения в changelog были в одной форме («fix memory leaks», «fixed memory leaks», «memory leaks fixed»), в таком виде их гораздо удобнее читать. Оптимально для предложений changelog использовать простое прошедшее время (past simple).
  • Единообразно оформляйте предложения changelog’а: либо начинайте, либо не начинайте их все с большой буквы; либо заканчивайте, либо не заканчивайте их точкой. Или проще говоря - если вы начинаете запись changelog с большой буквы, то обязательно заканчивайте её точкой и если вы начинаете с маленькой буквы, то заканчивать точкой не нужно.
  • Группировка сходных пунктов в подпункты позволяет уменьшить размер changelog’а и улучшить его читаемость.
  • Если вы разрабатываете и упаковываете сторонний проект, то в случае выхода новой версии рекомендуется просто указать факт изменения версии в записи changelog и привести список закрытых уязвимостей и ошибок в соответствии с правилами Vulnerability_Policy. Например: * 1.2.3 -> 1.2.7 (Fixes: CVE-1995-1121-2).
  • Для собственного проекта, если вы меняете только specfile - увеличивать нужно тэг release, если меняете код - поднимать версию.
  • Не стоит в changelog пакета перечислять все сделанные апстримом изменения, если вы не принимали участия в их разработке.

Разное

Ссылки