Тема: release-management
-
Tags and releases: lightweight versus annotated tags and how they travel
A lightweight tag is only a name for a commit; an annotated tag is an object with tagger, date, message and optional signature, which is why git describe ignores lightweight tags by default and why releases should use annotated or signed tags; tags are not pushed with branches unless --follow-tags or --tags is used, and a published tag should never be moved.
-
Cherry-picking: when it fits and what it costs the history
git cherry-pick replays the change of a commit as a new commit with a different ID; it is the right tool for backporting a fix to a maintenance branch or salvaging one commit from an abandoned branch, but each pick creates a duplicate that merges cannot recognise, so record the origin with -x and merge instead of picking when the whole branch is wanted.
-
Ритм выпусков небольшого проекта: по расписанию или по готовности
Номер версии говорит, что обещает выпуск; политика периодичности — когда он выходит. Rust выпускает стабильную версию каждые шесть недель через цепочку nightly, beta, stable; Python перешёл на ежегодные функциональные выпуски по PEP 602; Django выпускает функциональные версии по расписанию, а исправления — по необходимости. Небольшой проект может перенять эту схему: функциональные выпуски по календарю или по накоплении заметных изменений, исправления — после принятия каждого исправления.
-
Deprecating a function in a library: warn, document the replacement, remove on schedule
A library deprecation has four parts: a replacement that exists first, a runtime warning plus a documentation note naming the version and the replacement, a changelog entry, and a removal release fixed in advance by policy. PEP 387 requires a deprecation period of at least two years under Python's annual cadence and describes a documentation-only soft deprecation; Django removes shims no earlier than two feature releases after the warning.
-
Conventional Commits: машиночитаемые типы коммитов
Спецификация Conventional Commits добавляет к сообщениям коммитов префикс типа (feat, fix и другие) и отметки несовместимых изменений, чтобы автоматически формировать журналы изменений и определять повышение версии.
-
Семантическое версионирование: что обещает номер версии
Semantic Versioning 2.0.0 кодирует обещания совместимости в MAJOR.MINOR.PATCH и определяет суффиксы предварительных выпусков и метаданных сборки; оно работает только при объявленном публичном API.
-
Версионирование API: когда и как нарушать совместимость
Большинство изменений можно внести добавлением новых возможностей. Новая основная версия — крайняя мера, удваивающая объём поддержки. Указывайте версию в пути или медиатипе, документируйте правила совместимости и объявляйте устаревание до удаления.
-
Поддержка нескольких линий выпусков: какие исправления куда попадают
Политика поддержки — это таблица линий выпусков со статусом каждой (развитие функций, исправления ошибок, только безопасность, конец поддержки) и правило переноса классов исправлений в соответствующие линии. Python поддерживает серию выпусками с исправлениями ошибок два года, а затем ещё три года — выпусками только с исправлениями безопасности; Django переносит критические исправления в последний функциональный выпуск, а исправления безопасности и потери данных — в два последних и линии долгосрочной поддержки; Rust поддерживает только последнюю стабильную версию. Небольшому проекту следует публиковать таблицу и по умолчанию давать самое узкое обещание, которое он способен выполнить.
-
Ведение журнала изменений для людей
Журнал изменений — отобранный и хронологически упорядоченный список заметных изменений по версиям; Keep a Changelog задаёт небольшую структуру (Added, Changed, Deprecated, Removed, Fixed, Security) и раздел Unreleased.
Машиночитаемо: JSON