Соглашения для журнала изменений
Соглашения для журнала изменений
Заголовок раздела «Соглашения для журнала изменений»Эта страница определяет контракт, которого придерживается каждый публичный репозиторий NextPDF при фиксации изменений и публикации выпуска. Это справочник по соглашениям; он не задаёт поведение пакета. Заметки о выпусках для каждого пакета и каждой версии хранятся в собственном файле CHANGELOG.md соответствующего репозитория. Эти общие правила помогают сохранять сводку журнала изменений по всем репозиториям согласованной и свободной от утечек.
Conventional Commits 1.0.0
Заголовок раздела «Conventional Commits 1.0.0»Тема каждого коммита имеет формат type(scope): description. Значение type — одно из следующих:
| Тип | Значение | Для пользователя | Влияние на версию |
|---|---|---|---|
feat | Новая возможность | да | повышение младшей версии |
fix | Исправление поведения | да | повышение патч-версии |
perf | Улучшение производительности без изменения поведения | да | повышение патч-версии |
refactor | Внутренняя реструктуризация без наблюдаемых изменений | нет | отсутствует |
docs | Только документация | нет | отсутствует |
test | Только тесты | нет | отсутствует |
build / ci | Только сборка или конвейер | нет | отсутствует |
chore | Обслуживание, зависимости или инструментарий | нет | отсутствует |
revert | Откат предыдущего коммита | зависит | зависит |
Несовместимое изменение отмечается ! после типа или области (feat(api)!: …) либо нижним колонтитулом BREAKING CHANGE:. Любой из этих маркеров ведёт к повышению старшей версии согласно Semantic Versioning. Фиксируйте исправление, связанное с безопасностью, так, чтобы оно могло попасть в столбец Security сводки по всем репозиториям.
Semantic Versioning 2.0.0
Заголовок раздела «Semantic Versioning 2.0.0»Версия повышается по механическим правилам. Выпуск, содержащий хотя бы одно несовместимое изменение, является старшим. В противном случае выпуск, содержащий хотя бы один feat, является младшим. В противном случае выпуск, содержащий хотя бы один fix или perf, является патчем. Пакеты с версиями до 1.0 могут повышать младшую версию при несовместимом изменении согласно SemVer §4. Коммит всё равно содержит маркер несовместимости, чтобы сводка оставалась точной.
Группировка по Keep a Changelog
Заголовок раздела «Группировка по Keep a Changelog»Файл CHANGELOG.md каждого репозитория ведётся по Keep a Changelog 1.1.0: записи сгруппированы по выпущенным версиям в разделах Added, Changed, Deprecated, Removed, Fixed и Security. В репозитории раздел [Unreleased] может содержать заметки о текущей работе, но сводка по всем репозиториям учитывает только отмеченные тегом и выпущенные версии. Невыпущенные изменения никогда не появляются в публичном индексе.
Как формируется сводка по всем репозиториям (и сохраняется свободной от утечек)
Заголовок раздела «Как формируется сводка по всем репозиториям (и сохраняется свободной от утечек)»Сводная таблица в индексе журнала изменений формируется так: история Conventional Commits каждого репозитория читается в режиме только для чтения по его последнему выпущенному тегу, затем подсчитываются категории. Правила формирования намеренно узкие, чтобы внутренние детали не просачивались наружу:
- Количество, а не содержимое. Отображается только число коммитов для каждого видимого пользователю типа. Тема, тело, нижний колонтитул или хеш коммита не отображаются.
- Только типы, видимые пользователю.
docs,test,ci,choreиrefactorисключаются, потому что они не меняют ничего, что видит потребитель пакета. - Только выпущенное. Коммит учитывается только тогда, когда он становится частью отмеченного тегом выпуска публичного пакета.
- Без идентификаторов. Внутренние ссылки на задачи, тикеты, циклы, волны или рабочие элементы, которые могут появляться в приватной области коммита, никогда не раскрываются, потому что сам текст области не отображается. Читается только тип.
- Без указания авторства автоматизации. Завершающие строки, указывающие на участие автоматизации, не читаются и не отображаются.
По этой причине публичный журнал изменений представляет собой сводку по категориям со ссылками на собственный файл CHANGELOG.md каждого пакета, а не агрегированную ленту коммитов. По своей конструкции сводка свободна от внутренних утечек. Канонический текст выпуска остаётся в пакете, которому он принадлежит.