1.0 - это не зрелость, а обещание: что мы заморозили и что сломали за три дня до релиза
Первый тег проекта появился 22 июля, а уже 6 сентября вышла версия 1.0. За полтора месяца в продукт добавилось немало функций, но сам по себе список изменений не кажется самым интересным. Гораздо важнее понять, чем 1.0 технически отличается от 0.37 и какие обязательства возникают у автора после перехода к новой схеме версионирования.
Разница оказалась ровно в одном - не в коде, а в обещаниях пользователям. Пока в номере версии есть ноль впереди, автор сохраняет право пересматривать решения между выпусками. Это не обязательно признак хаоса: для пользователей заранее обозначен режим, в котором обновление может потребовать чтения документации, ручных действий или изменения конфигурации.
Для self-hosted-продукта такая особенность особенно заметна. Обновлением занимается не разработчик, а владелец конкретной установки - на собственном сервере, в удобное ему время и иногда спустя месяцы после публикации новой версии. Поэтому подготовка проекта к релизу 1.0 должна включать не только проверку функций, но и честное определение границ совместимости.
Версия 1.0 отменяет право менять всё подряд, однако не превращает весь продукт в неподвижную конструкцию. Обязательства нужно сформулировать точечно. В моём случае заморозке подверглись:
- имена переменных окружения;
- адреса приёма запросов и форматы их тел;
- направление миграций - только вперёд;
- читаемость существующего формата резервных копий;
- тело исходящих вебхуков;
- названия self-метрик, кроме явно временных;
- контракт переменных агента;
- адреса уже опубликованных статус-страниц.
Всё, что нарушает этот список, должно дождаться версии 2.0. Такой подход гораздо практичнее абстрактного обещания "ничего не ломать": пользователи понимают, какие именно интеграции защищены, а какие изменения всё ещё возможны.
Особого внимания заслуживают публичные статус-страницы. Их адрес может быть однажды размещён в шапке сайта, подписи электронной почты или закреплённом сообщении службы поддержки. Если URL перестанет открываться после обновления мониторинга, исправлять последствия придётся владельцу установки. Формально речь идёт лишь о ссылке, но фактически это интеграция с внешним миром, у которой нет отдельного владельца, способного быстро внести исправление.
Поэтому обещание, охватывающее абсолютно всё, быстро превращается в маркетинговую формулировку. За пределами гарантии остались внутренние пакеты: в Go каталог `internal/` сам задаёт достаточно чёткую границу, которую контролирует компилятор. Не фиксируется и внешний вид интерфейса - расположение блоков, тексты и вёрстка. Можно менять имена счётчиков, заранее помеченных как временные, а также исправлять поведение, признанное ошибочным.
Последний пункт наиболее спорный. Автор может считать изменение исправлением дефекта, тогда как пользователь уже встроил прежнее поведение в собственный процесс. Универсального решения здесь нет. На практике помогает только подробный changelog: потенциально несовместимые исправления нужно выносить в отдельный раздел и не прятать среди обычных улучшений.
Ломающее изменение перед заморозкой
Релиз 0.34.0 вышел 3 сентября - всего за три дня до 1.0. В нём были переименованы 31 переменная окружения: 17 серверных, 3 агентские, ещё 11 использовались в `docker-compose` и процессе сборки. Это было намеренное ломающее изменение, помещённое в последний возможный выпуск перед заморозкой API.
За весь период 0.x количество переименований достигло 41. Ещё десять имён изменились ранее, в версии 0.23.0, когда единицы измерения начали включать непосредственно в название переменной.
Причины были вполне практическими. Настройки добавлялись постепенно, под конкретные задачи, и со временем накопили типичные проблемы:
- адрес прослушивания и публикуемый порт можно было легко перепутать;
- `GOTCHA_LOG_LEVEL` относилась к журналу самого приложения, тогда как расположенная рядом `GOTCHA_LOG_RETENTION_DAYS` описывала приём пользовательских логов и относилась к другой подсистеме;
- переменная-модификатор находилась далеко от базовой настройки, которую она изменяла;
- некоторые логические параметры были названы так, что их смысл фактически читался наоборот.
Пока проект находится в зоне 0.x, такие недостатки можно исправлять без многолетнего наследия. После релиза версии 1.0 неудачные имена пришлось бы поддерживать годами, потому что они уже стали частью публичного контракта. Именно поэтому стабилизация проекта перед релизом иногда требует неприятного решения: сломать конфигурацию сейчас, чтобы не закрепить плохую архитектуру навсегда.
Вопрос заключался не только в переименовании, но и в судьбе старых названий. Можно было молча читать прежнее имя как синоним нового, однако это создало бы второй, недокументированный интерфейс. Рано или поздно кто-нибудь настроил бы сервер по старой статье или случайному примеру в интернете, а разработчику пришлось бы выяснять, почему конкретная установка ведёт себя иначе.
Выбранный вариант оказался жёстче: если старое имя присутствует и содержит непустое значение, приложение останавливает запуск и сообщает новое название. Такой отказ выглядит менее дружелюбно, зато он немедленно выявляет устаревшую конфигурацию и не оставляет скрытых правил приоритета.
Молчаливое игнорирование старой переменной было бы ещё опаснее. В этом случае приложение могло бы запуститься со значением по умолчанию, а владелец обнаружил бы проблему значительно позже - например, после потери логов, изменения сетевого поведения или нарушения политики хранения данных. Явная ошибка на старте обычно дешевле и безопаснее, чем незаметная неправильная работа.
При этом управление релизами программного обеспечения не заканчивается публикацией тега. Нужно заранее подготовить миграционные инструкции, автоматическую проверку конфигурации и понятные сообщения об ошибках. Хорошая практика - добавить команду диагностики, которая показывает устаревшие параметры до обновления, не требуя полноценного запуска приложения.
Полезно также разделять обязательные изменения и рекомендуемые. Если переименовали переменную, документация должна содержать таблицу соответствий, пример новой конфигурации и описание того, как проверить результат. Пользователь должен понимать не только "что сломалось", но и "почему это произошло" и "какое действие вернёт систему в рабочее состояние".
Ошибки и проблемы перед релизом продукта неизбежны, но их цена зависит от момента обнаружения. До 1.0 допустимы более смелые исправления, после - каждое изменение внешнего контракта требует веского основания. Поэтому релиз 1.0 нельзя воспринимать как доказательство абсолютной зрелости. Это публичная граница ответственности: разработчик заявляет, какие решения готов поддерживать, а какие оставляет за пределами обещания.
Именно в этом смысле 1.0 - не финальная точка и не заявление о безупречности. Это договор с пользователями. Чем конкретнее перечислены защищённые интерфейсы, тем честнее выпуск и тем меньше неожиданных конфликтов возникнет при следующих обновлениях. Практические детали такого подхода к заморозке контрактов и работе с несовместимыми изменениями можно посмотреть в материале о подготовке проекта к релизу 1.0.
