Files
plba_v2/openspec/changes/archive/2026-10-10-add-plba-python-ci/design.md
T
alex d517820088
PLBA package CI / Python tests (push) Failing after 2s
PLBA package CI / Package version increment (push) Skipped
PLBA2-2. Архивация спек
2026-10-10 20:55:13 +03:00

43 lines
5.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Design
## Context
Пакету требуется Python 3.11 или новее; он использует setuptools с исходниками в `src/`, объявляет pytest в extra `test` и хранит тесты в `tests/`. Infra v2 поднимает общий Python CI runner на `cloud`; workflow Gitea выбирают его по метке `cloud-build`.
Существующая проверка версии читает базовую версию командой `git show <ref>: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-деплой и миграция данных не затрагиваются.