Совместимость и версии

Объяснение: что меняется от выпуска к выпуску, что обещано не меняться и как зафиксировать версию у себя. Что именно поменялось в каждом выпуске - Изменения.

Один номер на все

Крейты на crates.io, пакет brokapi на PyPI, программа brokapi в выпусках GitHub и модуль Go выходят одним номером. Номер на PyPI записан по правилам Python (0.1.0a8 вместо 0.1.0-alpha.8), модуль Go - тегом go/v<номер>. Берите все части одного номера: имитации (brokapi-mocks) и коннекторы одного выпуска знают друг друга, бот на Python и гейтвей одного выпуска говорят на одном .proto.

Что обещано до беты

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

Часть	Обещание	Почему
gRPC гейтвея, пакет `brokapi.gateway.v1`	только дополняется: новые вызовы, поля, значения перечислений. Вызовы и поля не удаляются, номера полей не меняются и не переиспользуются, смысл поля не меняется. Ломающее изменение - только новым пакетом `v2` рядом с `v1`	клиент на другом языке сгенерирован из `.proto` и обновляется отдельно от программы: старый клиент должен работать с новым гейтвеем
Rust (`brokapi`, `brokapi-*`) и Python (`brokapi`)	могут меняться в любом выпуске альфы	интерфейс еще ищем, и правка по жалобе пользователя важнее совместимости. Каждое ломающее изменение записано в Изменениях с тем, что поменять в своем коде
Имитации `brokapi-mocks` и сценарии `brokapi-conformance`	могут меняться в любом выпуске, и после беты тоже	это инструменты тестов: рычаги добавляются, когда появляется сбой, который стоит проверять
Конфиг `brokapi.toml` и команды программы	могут меняться в любом выпуске альфы, неизвестный ключ - ошибка конфига, а не молчание	ошибка при старте лучше, чем гейтвей, который тихо делает не то

После беты обещания для Rust и Python станут строже, это будет записано здесь.

Как зафиксировать версию

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

# Cargo.toml. Без "=" cargo считает следующий выпуск альфы подходящей заменой.
brokapi = { version = "=0.1.0-alpha.8", features = ["tbank"] }

# requirements.txt
brokapi==0.1.0a8

Программу brokapi ставьте файлом конкретного выпуска со страницы выпусков или cargo install brokapi-gateway --version 0.1.0-alpha.8 --locked. Какой номер работает, печатает brokapi --version. Сборка из main добавляет к номеру коммит, так она отличается от выпуска (Установка).

Как обновляться

Прочитать в Изменениях разделы выпусков между вашим и новым, пункты «Что поменять».
Поднять номер у всех частей сразу: библиотеки, программы, имитаций.
Прогнать свои тесты на имитациях нового выпуска, потом бота на песочнице или демо-счете.
Программу на сервере - по разделу «Обновить программу» в Запуске и обслуживании.