| Статус | Черновик,  обсуждение |
| Автор(ы) | Андрей Рахматуллин (wrar@) |
| Обязательно в | 4.1 и выше |
| Метабаг | не создан |
Этот документ описывает правила оформления секций %changelog и объём включаемой в них информации.
Используемые понятия
Пример секции:
Здесь всё, что относится к сборке 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») – строкой.
Оформление
- Чейнджлог пишется на английском языке.
- Желательно, чтобы все предложения были в одной форме («fix memory leaks», “fixed memory leaks”, “memory leaks fixed”, но не смесь разных форм в одной записи). можно в принципе попробовать выбрать и зафиксировать одну форму
- Все пункты, являющиеся фразами, оформляются как предложения (с прописной буквы, заканчиваются точкой).
либо
- Все пункты начинаются со строчной буквы и не заканчиваются точкой.
- Сходные пункты желательно группировать, используя подпункты.
- Пункт верхнего уровня начинается с 1-й позиции в строке и состоит из дефиса, пробела и собственно текста.
- Подпункт начинается с 3-й позиции в строке и состоит из плюса, пробела и собственно текста.
- Строки переносятся по словам и содержат не более 78 символов. При этом текст новой строки выравнивается по началу текста предыдущей (т.е. 3-я позиция для пунктов верхнего уровня и 5-я для подпунктов).
- Начинать новую строку с символа # нельзя (такая строка будет воспринята как комментарий).
Пример:
Содержимое
- При сборке новой upstream-версии это указывается первым пунктом. Возможные варианты: “new version”, “0.0.1”, "[0.0.1]", «new version [0.0.1]" и т.д. Желательно зафиксировать. Особенно случаи сборки VCS-снапшота.
- Если новая сборка содержит исправленные по сравнению с предыдущей сборкой ошибки безопасности, эти ошибки указываются отдельным пунктом (пример: «security fixes (CVE-0001, CVE-0002)").
- Изменения, произведённые апстримом (кроме исправлений ошибок безопасности), в чейнджлоге не указываются (для этого есть чейнджлоги апстрима, зачастую включаемые в пакет).
- Косметические изменения спек-файла, не влияющие на получаемый пакет, указываются максимум одной строкой, либо не указываются вовсе. Это не относится к исправлениям тега License, изменениям параметров сборки и т.д.
- Исправления, необходимые для успешной сборки, соответствия требованиям ALT Linux и т.д., не указываются, если они были сопряжены с упаковкой новой версии и для старой версии были не нужны (обоснование: эти исправления – адаптация новой версии, т.е. часть процесса её упаковки). Если же они были вызваны изменением требований либо окружения, желательно это указать (пример: “fix building with new autotools”).
Указание источников и контекста
- Если изменение взято извне либо основано на взятом извне, в соответствующем изменению пункте чейнджлога в скобках указывается источник. Это может быть название дистрибутива/репозитория, название внешней BTS и номер бага в ней, ID участника ALT Linux Team или произвольное указание на человека или сайт. Здесь под изменением подразумевается готовый патч, адаптированный патч или иные аналогичные указания.
Примеры:
- Если изменение связано с багом в багзилле ALT Linux, номер бага указывается в скобках в соответствующем пункте. Это может быть совмещено с предыдущим требованием. В дальнейшем эта информация может быть автоматически передана в указанный баг.
Примеры:
- Если изменение не просто связано с багом, но закрывает его – это желательно указать в форме "(closes: #12345)". В дальнейшем на основании такой записи указанный баг может быть автоматически закрыт.
Powered by WackoWiki R4.2