Привет читающим) Сегодня рассмотрим советы, позволяющие сделать более понятными оформление лога изменений и превратить версию проекта из милых сердцу циферок в мощного поставщика информации пользователю. В заметке используются материалы проектов Keep a Changelog[1] и Semantic Versioning[2].
Одна из глобальных проблем программирования - возрастающая со временем и величиной проекта сложность и соответственно стоимость поддержки. Хоть код исполняется машинами, но пишут и читают его пока еще преимущественно люди. Поэтому огромная часть практик и правил направлена именно на упрощение, улучшение читаемости.
Почему бы просто не использовать лог коммитов с гита? Эта информация больше нужна самим разработчикам и только запутает пользователя. В лучшем случае они будут содержать лишнюю информацию вроде небольших правок после ревью, дополнения комментариев и т.д. В худшем могут содержать сообщения "small fix", "подправил переменную amount".
Из этого вытекает первое правило - лог пишем для пользователя.
Основные принципы ведения лога:
- Лог пишем для людей, а не машин.
- Для каждой версии должна быть запись.
- Группируем однотипные изменения.
- Расставляем локальные ссылки на версии и изменения.
- Последняя версия должна быть первой для чтения.
- Ставим дату релиза у каждой версии.
- Указываем используется ли семантическое версионирование.
Секции группировки для изменений:
- Added для новых свойств.
- Changed изменения текущих свойств.
- Deprecated функционал, который скоро будет удален.
- Removed функционал, удаленный в указанной версии.
- Fixed багфиксы.
- Security исправление уязвимостей.
- Unreleased для планируемого к разработке функционала. Отличный способ снизить себе затраты на поддержание лога и наметить перспективы для пользователей.
Окей, с логом вроде понятно, но что за жуткое семантическое версионирование? Здесь все проще чем кажется. Саму концепцию можно описать в 3 предложениях:
[0.0.0]
- Главная (MAJOR) версия меняется, если вы внесли несовместимые с прошлыми версиями изменения.
- Младшая (MINOR) версия меняется, при внесении правок поддерживающих обратную совместимость.
- Патч (PATCH) версию меняем при багфиксах с поддержкой обратной совместимости.
_________________________________________________________________________________________
Если считать, что мажорную версию 1 я получил устроившись на работу, то после добавления этих практик в работу можно назвать меня программистом [1.1.0]
# Changelog
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning
# [Unreleased]
- Немного размышлений и ретроспективы. "Что я получил и потерял став программистом?"
# [1.1.0] - 2020-05-17
# Added
- Правила оформления лога изменений и правильного версионирования проектов.
=) Хорошего дня.
С примерами и более подробным объяснением можно ознакомиться по ссылкам.
[1] Keep a Changelog