git-monorepo-release — Релиз монорепо с независимыми версиями

Цель: в репозитории, где живёт несколько пакетов со своими версиями, определить состав релиза и провести его так, чтобы версии не поехали друг относительно друга.

Перед началом прочитай ../../rules/git-conventions.md — разделы про Semver и теги.

Постановку одного тега с changelog делает git-release-tag. Этот скилл решает, какие теги ставить и почему, и вызывает git-release-tag на каждый.

Границы

Скилл применим, когда в репозитории больше одного независимо версионируемого пакета. Проверь это до всего остального:

git tag --list --sort=-v:refname | head -20
ls -d */ | head -20

Признаки монорепо с независимыми версиями: теги вида <name>/vX.Y.Z, несколько директорий с собственными манифестами (go.mod, package.json, pyproject.toml, *.csproj).

Если пакет один — скажи об этом и передай работу git-release-tag. Не изобретай монорепо там, где его нет.

Шаг 1. Определи затронутые пакеты

Возьми диапазон с последнего релиза каждого пакета и посмотри, что реально менялось:

# последний тег конкретного пакета
git tag --list 'sdk-go/v*' --sort=-v:refname | head -1

# что изменилось в его директории с тех пор
git log sdk-go/v0.3.0..HEAD --oneline -- sdk-go/

Пройди так по каждому пакету. Пакет без коммитов в своей директории не релизится — даже если релизится соседний.

Осторожно с изменениями вне директорий пакетов: правка общей спецификации, protobuf-схемы или генератора может затрагивать всех потребителей, не оставив коммитов в их папках. Такие коммиты покажи пользователю отдельно и спроси, чьи версии они двигают.

Шаг 2. Определи bump для каждого пакета

Semver считается для каждого пакета отдельно. Breaking change в Go SDK не двигает версию Python SDK.

Правило нулевой мажорной версии: до v1.0.0 breaking change идёт в minor, а не в major. Пакеты в монорепо часто находятся на разных стадиях зрелости, поэтому проверяй текущую версию каждого, а не применяй одно правило ко всем.

Если коммиты не по Conventional Commits и bump не выводится — покажи их пользователю и спроси. Не угадывай.

Шаг 3. Покажи план релиза целиком

До любых команд покажи таблицу и дождись подтверждения:

Пакет         текущая   новая     причина
sdk-go        v0.3.0  → v0.4.0    feat(sdk-go): streaming API
sdk-python    v0.2.1  → v0.2.2    fix(sdk-python): retry on 429
sdk-java      v0.5.0    —         нет изменений
sdk-csharp    v0.1.2    —         нет изменений

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

Шаг 4. Проведи релиз

Для каждого релизуемого пакета вызови git-release-tag — он соберёт changelog из коммитов и поставит annotated-тег.

Теги ставятся на один и тот же коммит main, поэтому сначала убедись, что дерево чистое и main актуален:

git checkout main && git pull --ff-only
git status --porcelain      # должно быть пусто

Пуш нескольких тегов — одной командой, чтобы CI увидел релиз целиком, а не по частям:

git push origin sdk-go/v0.4.0 sdk-python/v0.2.2

Не пушь без явного подтверждения. Тег, за который зацепился release-pipeline, откатывается тяжело.

Шаг 5. GitHub Releases

Один Release на один тег. Каждый содержит changelog только своего пакета — не сваливай изменения всех SDK в общий текст.

gh release create sdk-go/v0.4.0 --title "sdk-go v0.4.0" --notes-file <changelog>

Если CI уже создаёт Releases по тегу — не дублируй вручную, просто запушь тег и скажи об этом пользователю.

Backport в старую версию

Когда часть пользователей осталась на старой версии, а main ушёл вперёд:

# ветка от старого тега
git checkout -b release/sdk-go-v0.1 sdk-go/v0.1.0

# только нужный фикс
git cherry-pick <commit-sha>

# patch поверх старой линии
git tag -a sdk-go/v0.1.1 -m "sdk-go v0.1.1"
git push origin release/sdk-go-v0.1 sdk-go/v0.1.1

Release-ветку заводи только когда backport действительно нужен. В обычной ситуации фикс едет в main и выходит следующим minor.

После backport проверь, что фикс есть и в main — иначе следующий релиз его потеряет.

Почему формат тега именно такой

<пакет>/vX.Y.Z — не стилистический выбор. Go требует ровно такой формат, чтобы go get умел забрать модуль из поддиректории монорепо: путь тега должен совпадать с путём модуля относительно корня репозитория. Для единообразия остальные пакеты используют тот же формат, хотя их тулчейны свободнее.

Отсюда следует: не ставь общий тег vX.Y.Z на монорепо с независимыми версиями. Он не соответствует ни одному пакету и ломает разрешение версий у Go.

Чего не делать

• не ставь общий тег на все пакеты сразу — версии разъедутся, а Go перестанет находить модуль
• не бампь пакет, в котором нет изменений, ради «ровных» номеров
• не переиспользуй и не передвигай опубликованный тег: пользователи уже получили этот код под этой версией
• не выводи major из feat! вслепую — сначала посмотри, дошёл ли пакет до 1.0
• не релизь при грязном рабочем дереве: тег укажет на коммит, которого нет у остальных