[newbies] changelog in spec and commit message

[newbies] changelog in spec and commit message

[Alexander Lubyagin]

Добрый день.

В каких случаях запись 'commit message' (git commit -m) дублирует 
многострочную запись в spec's changelog?

В каких случаях они различаются? Есть ли рекомендации?

--

Re: [newbies] changelog in spec and commit message

[Anton Farygin]

On 9/25/25 14:33, Alexander Lubyagin wrote:
> Добрый день.
>
> В каких случаях запись 'commit message' (git commit -m) дублирует 
> многострочную запись в spec's changelog?
>
> В каких случаях они различаются? Есть ли рекомендации?


Изменения в rpm spec обычно фиксируются через команду gear-commit -a, 
эта команда автоматически в commit message добавит записи из changelog

Другие изменения в пакете лучше фиксировать отдельными коммитами, 
оформленными по обычным рекомендациям к написанию commit message на 
английскком языке:
-------------------------

Короткий заголовок в повелительном наклонении (до 50 символов)

Более развернутое объяснение изменений:
- Что изменено
- Почему это важно
- Ссылки: Fixes #NNN
-------------------------


Важно фиксировать не только то, что изменилось, но и зачем было сделано 
это изменение.

пример (выдуман):
-----------------------

|Addsystemd hardening options tokeepalived.service Enabled additional 
security directives: 
-ProtectSystem=full-ProtectHome=true-ProtectKernelModules=true-RestrictRealtime=trueThese 
options reduce the attack surface bylimiting access tosystemfiles, 
userhomes andkernel interfaces. Fixes: ALTBUG#55878 ------------------|

Re: [newbies] changelog in spec and commit message

[Anton Farygin]

On 9/25/25 14:43, Anton Farygin wrote:
> On 9/25/25 14:33, Alexander Lubyagin wrote:
>> Добрый день.
>>
>> В каких случаях запись 'commit message' (git commit -m) дублирует 
>> многострочную запись в spec's changelog?
>>
>> В каких случаях они различаются? Есть ли рекомендации?
>
>
> Изменения в rpm spec обычно фиксируются через команду gear-commit -a, 
> эта команда автоматически в commit message добавит записи из changelog
>
> Другие изменения в пакете лучше фиксировать отдельными коммитами, 
> оформленными по обычным рекомендациям к написанию commit message на 
> английскком языке:
> -------------------------
>
> Короткий заголовок в повелительном наклонении (до 50 символов)
>
> Более развернутое объяснение изменений:
> - Что изменено
> - Почему это важно
> - Ссылки: Fixes #NNN
> -------------------------
>
>
> Важно фиксировать не только то, что изменилось, но и зачем было 
> сделано это изменение.
>
> пример (выдуман):
> ----------------------- 

Почему-то в примере слетело форматирование:


Add systemd hardening options to keepalived.service


Enabled additional security directives:
- ProtectSystem=full
- ProtectHome=true
- ProtectKernelModules=true
- RestrictRealtime=true

These options reduce the attack surface by limiting access to
system files, user homes and kernel interfaces.
Fixes: ALT#55878

Re: [newbies] changelog in spec and commit message

[Paul Wolneykien]

В Thu, 25 Sep 2025 14:33:04 +0300
Alexander Lubyagin <lubyagin@yandex.ru> пишет:

> Добрый день.
> 
> В каких случаях запись 'commit message' (git commit -m) дублирует 
> многострочную запись в spec's changelog?
> 
> В каких случаях они различаются? Есть ли рекомендации?

  Основная рекомендация по моей версии такая. Работая в git вы
комментируете свои изменения для других мэйнтейнеров (и для себя).
Проделав эту работу (или попутно) в %changelog пакета вы перечисляете
важные для пользователя изменения, переводя их на понятный пользователю
язык. Таким образом, главное в том, что целевая аудитория у git и
%changelog разная. Всегда нужно думать о том, для кого вы пишете
сообщение.

  К примеру, в git следует написать о том, что была убрана
неиспользуемая функция или забытая переменная в коде, а также о том,
что были исправлены предупреждения (warnings) во время компиляции.
Однако, поскольку для пользователя ровно ничего от этого не изменилось,
в %changelog об этом писать не следует.

  А вот если вы добавили новую переменную в конфигурационный файл, то
написать об этом в %changelog нужно обязательно. Правда относится это
только к вашим собственным изменениям: дублировать release notes из
апстрима в %changelog не нужно (он раздуется тогда до гигантских
размеров). Поэтому при тривиальном обновлении пишем просто "New
version: такая-то" или подобную запись (не регламентировано). Однако,
если сборка новой версии исправляет известную ошибку -- об этом всё
же стоит написать отдельно (с указанием номера ошибки).

  Бывают ситуации, когда в %changelog и написать особо нечего, а хотя
бы строчку написать нужно -- без этого никак. Поэтому бывают записи
наподобие "Recompiled with new libXXYY", которые для пользователя,
в общем-то, не несут никакой полезной информации.

Re: [newbies] changelog in spec and commit message

[Leonid Krivoshein]

Добрый день!


On 9/25/25 14:33, Alexander Lubyagin wrote:
> В каких случаях запись 'commit message' (git commit -m) дублирует 
> многострочную запись в spec's changelog?
>
> В каких случаях они различаются? Есть ли рекомендации?
>

Это разные сущности, их вообще не стоит связывать и сравнивать.

Commit message делается по каждому изменению в git'е для других 
разработчиков. Заголовок сообщения отвечает на вопрос, что делает 
коммит, а тело сообщения -- на вопрос, зачем он это делает. Для многих 
коммитов, если это и так очевидно, тело сообщения можно опустить. Ширина 
теста в обоих случаях должна быть ограничена, см. в книге 
https://git-scm.com/book/ru/v2 (раздел "Правила создания коммитов").

Changelog в SPEC'ах делается для пользователей, а не для разработчиков. 
В нём не нужно отражать все изменения в исходниках. В нём отражаются 
наиболее важные изменения новой сборки пакета. По его написанию есть 
своё руководство: 
https://www.altlinux.org/Руководство_по_написанию_changelog

Если я, как разработчик, одним коммитом в git/исходники вношу важное 
изменение в будущую сборку, только тогда сообщения в changelog и commit 
message совпадут, такое встречается, но не так часто.


-- 
WBR, Leonid Krivoshein.