# Design ## Context Пакету требуется Python 3.11 или новее; он использует setuptools с исходниками в `src/`, объявляет pytest в extra `test` и хранит тесты в `tests/`. Infra v2 поднимает общий Python CI runner на `cloud`; workflow Gitea выбирают его по метке `cloud-build`. Существующая проверка версии читает базовую версию командой `git show :pyproject.toml`, поэтому целевая ветка pull request должна присутствовать в локальной истории Git. Мотивация и общий scope приведены в `proposal.md`. ## Goals / Non-Goals **Goals:** - Запускать тесты пакета для pull request и push в `main` на build runner infra v2. - Требовать один допустимый шаг SemVer для каждого pull request. - Выполнять CI пакета без прав и секретов деплоя приложений. **Non-Goals:** - Автоматически публиковать wheel, container image или релиз приложения. - Деплоить сам PLBA через `infra_v2`. ## Decisions - Использовать единый `.gitea/workflows/ci.yml` для тестов пакета и проверки версии pull request. Проверки остаются отдельными jobs одного workflow. - Запускать тесты для pull request и push в `main`. Проверять версию только для pull request, используя `github.base_ref` как целевую ветку. - Выбирать метку `cloud-build`, соответствующую host runner, зарегистрированному как `cloud-build:host`. - Использовать Python, установленный для runner; завершать job с понятной ошибкой, если версия ниже 3.11. Устанавливать пакет и test-зависимости через `python -m pip install -e ".[test]"`, затем запускать `python -m pytest`. - Загружать полную историю Git для job проверки версии и вызывать существующий checker со ссылкой `origin/${{ github.base_ref }}`. Checker использует только стандартную библиотеку Python. - До `1.0.0` использовать PATCH для исправлений, рефакторинга и документации; MINOR — для новых возможностей и любых изменений публичного контракта, включая несовместимые. Версия `1.0.0` обозначает начало стабильного контракта. Начиная с `1.0.0`, использовать PATCH для совместимых исправлений, MINOR — для совместимых возможностей, MAJOR — для несовместимых изменений публичного контракта. - Проверка принимает только один допустимый шаг SemVer относительно base pull request. Она не определяет, соответствует ли выбранный компонент типу изменения; это проверяют OpenSpec-планирование и code review. - Не настраивать доступ к registry или токен деплоя. PLBA является Python-пакетом; публикацией образа и деплоем занимаются репозитории приложений. ## Risks / Trade-offs - На build runner может оказаться Python ниже 3.11 → проверять версию интерпретатора до установки и выводить обнаруженную версию при ошибке. - Для установки extra `test` нужен доступ к package index → устанавливать только объявленные зависимости и сохранять ошибки установки в job log. - Контекст pull request в Gitea должен предоставлять `github.base_ref`, а checkout action — получать целевую ветку → загружать полную историю и использовать тот же контекст, что и текущая проверка версии. - Внешние структурные заголовки OpenSpec остаются на английском, чтобы инструменты схемы распознавали артефакты; весь пояснительный текст, включая заголовки групп задач и сценариев, оформляется на русском. ## Migration Plan Заменить version-only workflow объединённым CI workflow. Первый pull request запускает тесты и проверяет версию относительно целевой ветки; последующие push в `main` запускают тестовую job. Production-деплой и миграция данных не затрагиваются.