Руководство по написанию changelog: различия между версиями

Материал из ALT Linux Wiki
м (+категории)
м (Русская "C" в CVE :-))
(не показано 27 промежуточных версий 11 участников)
Строка 4: Строка 4:


__TOC__
__TOC__
Этот документ описывает рекомендуемые правила оформления секций <tt>%changelog</tt> и объём включаемой в них информации.
Этот документ описывает рекомендуемые правила оформления секции <tt>%changelog</tt> spec-файла пакета и характер/объём включаемой в неё информации.
== Используемые понятия ==
== Термины ==
Пример секции:
Пример секции:
<pre>* Wed Apr 02 2008 Andrey Rahmatullin <wrar@altlinux> 4.6.2-alt7.pre1
<pre>* Wed Apr 02 2008 Andrey Rahmatullin <wrar@altlinux> 4.6.2-alt7.pre1
Строка 24: Строка 24:
- build with slang2</pre>
- build with slang2</pre>


Здесь всё, что относится к сборке 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») — ''строкой''.
Здесь
; запись
: Всё, что относится к сборке 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»)


== Синтаксис чейнджлога ==
== Синтаксис чейнджлога ==
Строка 32: Строка 42:
* Строки переносятся по словам и содержат не более 78 символов. При этом текст новой строки выравнивается по началу текста предыдущей (то есть 3-я позиция для пунктов верхнего уровня и 5-я для подпунктов).
* Строки переносятся по словам и содержат не более 78 символов. При этом текст новой строки выравнивается по началу текста предыдущей (то есть 3-я позиция для пунктов верхнего уровня и 5-я для подпунктов).
* Начинать новую строку с символа # нельзя (такая строка будет воспринята как комментарий).
* Начинать новую строку с символа # нельзя (такая строка будет воспринята как комментарий).
* При использовании макросов следует экранировать символ "%" ещё одним "%" во избежание раскрытия оных, т.е. напрмер вместо <tt>%name</tt> следует записать <tt>%%name</tt>.


Пример:
Пример:
Строка 42: Строка 53:


== Содержимое ==
== Содержимое ==
* Чейнджлог (обязательно!) пишется на английском языке.
* '''Чейнджлог (обязательно!) пишется на английском языке.'''
* При сборке новой upstream-версии это указывается первым пунктом.
* При сборке новой upstream-версии это указывается первым пунктом.
** При сборке из снэпшота системы контроля версий необходимо указать информацию, позволяющую идентифицировать это снэпшот (дата и время для CVS, ревизия SVN, 8 первых символов идентификатора коммита для git, mtn, bzr, hg, либо вывод git-describe для git).
** При сборке из снэпшота системы контроля версий необходимо указать информацию, позволяющую идентифицировать это снэпшот (дата и время для CVS, ревизия SVN, 8 первых символов идентификатора коммита для git, mtn, bzr, hg, либо вывод git-describe для git).
* Если в сборке версии существенно принимало участие более одного человека, то изменения, вносимые разными людьми, собираются в группы по авторам, иначе группы не нужны.
* Если в сборке версии существенно принимало участие более одного человека, то изменения, вносимые разными людьми, собираются в группы по авторам, иначе группы не нужны.эээ
* Если новая сборка содержит исправленные по сравнению с предыдущей сборкой ошибки безопасности, эти ошибки указываются отдельным пунктом (пример: «security fixes (CVE-0001, CVE-0002)»).
'''Информация об уязвимостях (CVE и т.д.) в Changelog обязана соответствовать [[Vulnerability_Policy]].'''
* Изменения, произведённые апстримом (кроме исправлений ошибок безопасности), в чейнджлоге не указываются (для этого есть чейнджлоги апстрима, зачастую включаемые в пакет).
* '''Изменения, произведённые апстримом (кроме исправлений ошибок безопасности), в чейнджлоге не указываются (для этого есть чейнджлоги апстрима, зачастую включаемые в пакет).'''
* Косметические изменения спек-файла, не влияющие на получаемый пакет, указываются максимум одной строкой, либо не указываются вовсе. Это не относится к исправлениям тега License, изменениям параметров сборки и т. д.
* Косметические изменения спек-файла, не влияющие на получаемый пакет, указываются максимум одной строкой («<tt>spec cleanup</tt>»), либо не указываются вовсе. Это не относится к исправлениям тега License, изменениям параметров сборки и т. д.
* Исправления, необходимые для успешной сборки, соответствия требованиям ALT Linux и т. д., не указываются, если они были сопряжены с упаковкой новой версии и для старой версии были не нужны (эти исправления — адаптация новой версии, то есть часть процесса её упаковки). Если же они были вызваны изменением требований либо окружения, желательно это указать (пример: «fix building with new autotools»).
* Исправления, необходимые для успешной сборки, соответствия требованиям ALT Linux и т. д., не указываются, если они были сопряжены с упаковкой новой версии и для старой версии были не нужны (эти исправления — адаптация новой версии, то есть часть процесса её упаковки). Если же они были вызваны изменением требований либо окружения, желательно это указать (пример: «fix FTBFS with new autotools», [[Sisyphus/FTBFS|FTBFS]] == failure to build from source).
* Если .spec-файл адаптирован из другого дистрибутива, то старые записи %changelog обязательно должны быть сохранены (записи в %changelog фактически являются информацией об авторских правах на спек, и их недопустимо выкидывать в производной от исходного спека работе).
* '''Если .spec-файл адаптирован из другого дистрибутива, то старые записи %changelog обязательно должны быть сохранены''' (записи в %changelog фактически являются информацией об авторских правах на спек, и их недопустимо выкидывать в производной от исходного спека работе). Если это затруднительно либо невозможно по техническим причинам (например, в PLD формат несовместим) — следует проставить как минимум упоминание дистрибутива-донора, лучше перечислить делавших предыдущие изменения.
* Используйте спеллчекер :)
* Используйте спеллчекер :)


Строка 59: Строка 70:
  - linked libnetpbm.so against -lm (RH #165980)
  - linked libnetpbm.so against -lm (RH #165980)
  - use optflags (drool@)
  - use optflags (drool@)
* Если изменение связано с багом в багзилле ALT Linux, номер бага указывается в скобках в соответствующем пункте. Это может быть совмещено с предыдущим требованием. Синтаксис такого рода помещает (точнее, будет помещать после введения в строй соответствующей инфраструктуры) в указанный баг оповещение о том, что такой пакет вышел.
 
== Автозакрытие багов ==
* Если изменение связано с багрепортом из [[altbug:|bugzilla.altlinux.org]], в соответствующем пункте можно указать (по вкусу; регистр не учитывается, но обязательно в скобках):
** <tt>(Closes: NNNN)</tt>
** <tt>(ALT NNNN)</tt>
** <tt>(ALT bug NNNN)</tt>
с опциональным знаком <tt>#</tt> перед номером бага. Можно также указать несколько багов: <tt>(Closes: NNNN, MMMM, ZZZZ)</tt>. Синтаксис такого рода закрывает указанный баг после прохождения пакета в репозиторий при условии присутствия соответствующей записи в выводе {{cmd|rpmquery --lastchange}}.
* Номера багов в скобках разделяются запятыми.
Примеры:
Примеры:
  - add option to build with libslang2 (#10591)
  - add option to build with libslang2 (closes: 10591)
  - recognize .3gp as video, not manpage (#14982, hiddenman@)
  - recognize .3gp as video, not manpage (ALT #14982, #14999)
* Специальный синтаксис (Closes: #12345, #6789) закрывает (точнее, будет закрывать после введения в строй соответствующей инфраструктуры) все упомянутые в скобках баги в багтракере при прохождении пакета в Сизиф.
 
Пример:
Обратите внимание, что других слов в скобках при этом нельзя указывать.
- Fixed segfault on exit (Closes: #66666)
 
* Номера багов в скобках разделяются запятыми.
'''Полный regexp для поиска номеров багов в changelog можно посмотреть [http://git.altlinux.org/people/ldv/packages/?p=girar-builder.git;a=blob;f=gb-x-parse-bugs-from-changelog;hb=HEAD здесь].'''
 
== Указание устраненных уязвимостей ==
{{main|Vulnerability Policy}}


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


* Если changelog пакета оформлен единообразно, не нарушайте это единообразие (если оно не противоречит этому руководству). Если же changelog хаотичен оформлен не по правилам этого руководства, то оставленный перед changelog комментарий о рекомендуемом стиле ведения changelog поможет избежать продолжения хаоса в будущем.
* Если changelog пакета оформлен единообразно, не нарушайте это единообразие (если оно не противоречит этому руководству). Если же changelog хаотичен, то оставленный перед changelog комментарий о рекомендуемом стиле ведения changelog поможет избежать продолжения хаоса в будущем.
* Старайтесь, чтобы все предложения в changelog были в одной форме («fix memory leaks», «fixed memory leaks», «memory leaks fixed»), в таком виде их гораздо удобнее читать.
* Старайтесь, чтобы все предложения в changelog были в одной форме («fix memory leaks», «fixed memory leaks», «memory leaks fixed»), в таком виде их гораздо удобнее читать.
* Единообразно оформляйте предложения changelog’а: либо начинайте, либо не начинайте их все с большой буквы; либо заканчивайте, либо не заканчивайте их точкой.
* Единообразно оформляйте предложения changelog’а: либо начинайте, либо не начинайте их все с большой буквы; либо заканчивайте, либо не заканчивайте их точкой.

Версия от 10:04, 20 августа 2018


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

Термины

Пример секции:

* Wed Apr 02 2008 Andrey Rahmatullin <wrar@altlinux> 4.6.2-alt7.pre1
[ Andrey Rahmatullin ]
- syntax:
  + recognize .hh and .hpp as c++ again
  + recognize man pages with additional suffixes other than 'x', such as
    write.3p (Debian)

[ Vladislav Primerov ]
- make visible_tabs and visible_tws mcedit options configurable through config
  file (Debian)

[ Alexander Sluchainyi ]
- specfile cleanup

* Sat Mar 29 2008 Andrey Rahmatullin <wrar@altlinux> 4.6.2-alt6.pre1
- build with slang2

Здесь

запись
Всё, что относится к сборке 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).
  • Если в сборке версии существенно принимало участие более одного человека, то изменения, вносимые разными людьми, собираются в группы по авторам, иначе группы не нужны.эээ

Информация об уязвимостях (CVE и т.д.) в Changelog обязана соответствовать Vulnerability_Policy.

  • Изменения, произведённые апстримом (кроме исправлений ошибок безопасности), в чейнджлоге не указываются (для этого есть чейнджлоги апстрима, зачастую включаемые в пакет).
  • Косметические изменения спек-файла, не влияющие на получаемый пакет, указываются максимум одной строкой («spec cleanup»), либо не указываются вовсе. Это не относится к исправлениям тега License, изменениям параметров сборки и т. д.
  • Исправления, необходимые для успешной сборки, соответствия требованиям ALT Linux и т. д., не указываются, если они были сопряжены с упаковкой новой версии и для старой версии были не нужны (эти исправления — адаптация новой версии, то есть часть процесса её упаковки). Если же они были вызваны изменением требований либо окружения, желательно это указать (пример: «fix FTBFS with new autotools», FTBFS == failure to build from source).
  • Если .spec-файл адаптирован из другого дистрибутива, то старые записи %changelog обязательно должны быть сохранены (записи в %changelog фактически являются информацией об авторских правах на спек, и их недопустимо выкидывать в производной от исходного спека работе). Если это затруднительно либо невозможно по техническим причинам (например, в PLD формат несовместим) — следует проставить как минимум упоминание дистрибутива-донора, лучше перечислить делавших предыдущие изменения.
  • Используйте спеллчекер :)

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

  • Если изменение взято извне либо основано на взятом извне, в соответствующем изменению пункте чейнджлога в скобках указывается источник. Это может быть название дистрибутива/репозитория, название внешней 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). Синтаксис такого рода закрывает указанный баг после прохождения пакета в репозиторий при условии присутствия соответствующей записи в выводе rpmquery --lastchange.

  • Номера багов в скобках разделяются запятыми.

Примеры:

- add option to build with libslang2 (closes: 10591)
- recognize .3gp as video, not manpage (ALT #14982, #14999)

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

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

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

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


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

  • Если changelog пакета оформлен единообразно, не нарушайте это единообразие (если оно не противоречит этому руководству). Если же changelog хаотичен, то оставленный перед changelog комментарий о рекомендуемом стиле ведения changelog поможет избежать продолжения хаоса в будущем.
  • Старайтесь, чтобы все предложения в changelog были в одной форме («fix memory leaks», «fixed memory leaks», «memory leaks fixed»), в таком виде их гораздо удобнее читать.
  • Единообразно оформляйте предложения changelog’а: либо начинайте, либо не начинайте их все с большой буквы; либо заканчивайте, либо не заканчивайте их точкой.
  • Группировка сходных пунктов в подпункты позволяет уменьшить размер changelog’а и улучшить его читаемость.

Разное