[newbies] Пример хорошего оформления релиза

[Michael Shigorin]

On Tue, Dec 02, 2025 at 05:06:58PM +0300, Alexander Lubyagin wrote:
> Подскажите пример "красивого" оформления релиза в Gear-репозитории.

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

Что до %changelog, см. тж. http://altlinux.org/changelog

> Вот такая схема правильная ли?
> 
> - Берём исходники, каждое значительное/незначительное
> изменение, или группу изменений, вносим отдельным коммитом
> (не отмечаем его в %changelog). В описании коммита указываем
> содержательную суть изменений.

Бывают изменения -- в том числе значительные как для разработки
-- которые остаются "невидимыми" для пользователя.  Их обычно
упоминать нет смысла (разработчик всё равно полезет в гит,
а для пользователя это будет шум).

В любом случае каждое законченное изменение в гите стоит
оформить коммитом с внятным сообщением, в котором первая
строчка очень кратко описывает суть изменений, а более
подробное описание посвящено не ей же (зачем пересказывать
идущий далее дифф ещё раз), но контексту: зачем сделано
изменение, почему сделано именно так.

То есть сохранить то, что сейчас в голове, а через год
из неё практически гарантированно вылетит (но пригодилось
бы при попытке понять свои же наработки).

Если есть имеющие отношение баги, страницы, коммиты --
это всё стоит упомянуть (See-also:, Fixes: и т.п.).
Разумеется, не забывая про Reported-by: и Suggested-by:,
когда применимо.

> - Когда накапливается "цельный" пакет исправлений, вносим
> финальную правку с одним лишь исправлением Version-Release,
> плюс - совокупную информацию по всем изменениям с последнего
> релиза добавляем в %changelog. Больше ничего этот коммит
> не содержит. Назовём его "релиз-коммитом".
> 
> Или есть другие схемы?

Это не про оформление релиза, это про собственно релиз.
То есть когда принимать решение, что накопившиеся изменения
являются (а) целостными и (б) достаточными для выпуска.

И у разных авторов/проектов бывают очень разные мнения
по этому поводу -- от "собирай верхний коммит, он всегда
лучше предыдущих" и до "мы работали три года и наконец
выкатываем вам плоды наших эпохальных трудов".

-- 
Michael Shigorin
http://altlinux.org/elbrus