Релизы и политика совместимости

История выпусков и инструкции перехода находятся в CHANGELOG. Обновление версии не создаёт тег или релиз.

Правила версийПравила версий

• PATCH: совместимые исправления ошибок, безопасности и runtime-зависимостей.
• MINOR: новые возможности; до 1.0 также явно описанные несовместимые изменения.
• MAJOR после 1.0: изменение обязательного API, удаление функций или runtime-поддержки.

Для пакета изменений выбирается один максимальный bump. pyproject.toml, публичный
__version__, uv.lock, README, UI и документация меняются вместе. До первого
опубликованного релиза точка отсчёта — предыдущая записанная версия. Каждая задача
имеет отдельный Conventional Commit. Коммит сам по себе пакет не публикует.
Изменение обязательного контракта адаптера также поднимает ADAPTER_API_VERSION.

Библиотека следует явным гарантиям публичного API. До 1.0
несовместимость требует MINOR и миграции EN/RU, после 1.0 — MAJOR. Deprecated API
сохраняется хотя бы ещё один совместимый MINOR-релиз с объявлением замены и версии
удаления. Поддержка Python/framework/ORM определяется проверенной матрицей, а не только
диапазонами зависимостей.

ВыпускВыпуск

1. Зафиксировать версию, дату changelog и миграцию.
2. Отправить коммит в master и дождаться автоматического полного ci.yml, включая
   CI ready и Release ready. Каждый пуш в любую ветку запускает все группы
   проверок, оба аудита зависимостей, сборку документации и проверку дистрибутивов.
3. Запустить python scripts/check_release.py --tag v<project.version>.
4. После разрешения отправить тег. release.yml требует успешный полный CI из master
   и его артефакты документации и дистрибутивов для точного коммита тега, затем публикует
   GitHub release с changelog этой версии и помечает его Latest.
5. После успешного workflow pages.yml выкладывает готовый артефакт документации из CI.
   Параллельно pypi.yml скачивает проверенные один универсальный wheel и один sdist
   из того же полного CI без повторной сборки.
6. Отдельная job загружает проверенные файлы в PyPI через Trusted Publishing.
   Последняя job устанавливает точную версию из публичного индекса и проверяет ресурсы.

Релиз переиспользует артефакты CI без повторного запуска матрицы тестов и сборки пакетов.
Последний запуск ci.yml для SHA тега от пуша
в master или ручного запуска на master должен завершиться успешно, включая
CI ready и Release ready. Для merge в PR сохраняется выбор проверок по изменениям;
для публикации нужен полный результат из master. Старый зелёный результат не скрывает
новый упавший, отменённый или незавершённый запуск. CI из PR и других веток не разрешает
релиз. Дождитесь автоматического полного прогона до создания тега, пока master указывает
на коммит релиза; любой следующий коммит требует собственной проверки. Ручной полный CI
остаётся доступен для повторных запусков и не обязателен при обычном выпуске.

Отсутствующий или просроченный артефакт quite-admin-docs или quite-admin-distributions
блокирует релиз. Для восстановления повторите существующий запуск CI на коммите релиза
или запустите полный CI в master, пока ветка указывает на этот SHA. Pages публикует
версию тега, даже если master уже продвинулся, используя артефакт документации из того
же полного прогона без повторной сборки и тестов демо. Автоматическая и ручная загрузка
в PyPI проверяют тот же полный CI и артефакт дистрибутивов, но повторно не требуют
артефакт документации.

Изменения только документации не требуют версии пакета, тега или релиза. Отправьте их
в master и дождитесь полного CI: pages.yml также принимает успешное завершение ci,
если этот точный коммит остаётся вершиной master. Проверка деплоя сравнивает полный
diff с последним опубликованным релизом, включая удаления и оба пути переименований.
Допускаются только docs/, README, инструкции репозитория и явно перечисленные
инструменты скриншотов и публикации документации. Runtime-код, демо, метаданные пакета,
зависимости и другие инструменты требуют обычного выпуска. Коммит должен происходить
от опубликованного тега; отсутствие истории или сведений о релизе блокирует деплой.
После успеха CI ready и Release ready Pages скачивает артефакт документации
из последнего полного CI в master для точного SHA. Повторной сборки сайта, переноса
опубликованного тега и загрузки нового пакета в PyPI нет.

Создание релиза через интерфейс GitHub проверяет тот же готовый результат CI перед
публикацией Pages и PyPI. Пакетный workflow получает проверенный коммит по SHA;
автоматическая и ручная публикация повторно проверяют статус CI из master, его артефакт
дистрибутивов и соответствие опубликованного тега этому коммиту. Workflow скачивает
quite-admin-distributions из этого CI и передаёт те же файлы как pypi-distributions
в изолированную job Trusted Publishing.

В GitHub release остаются автоматические архивы исходников ZIP/tar.gz. Wheel/sdist
публикуются в PyPI, не в assets GitHub. Отдельная job полного CI собирает одну пару,
запускает строгую проверку Twine и через scripts/check_distributions.py проверяет
чистые установки, ресурсы и подключение FastAPI/Litestar. Python-матрица не собирает
пакеты. Оба дистрибутива явно используют metadata 2.4; проверка отклоняет другую
версию метаданных.

Одноразовая настройка PyPIОдноразовая настройка PyPI

Войдите в PyPI и добавьте pending publisher в
настройках публикации аккаунта для первой
загрузки либо настройте издателя на странице Publishing существующего проекта:

Job загрузки использует GitHub environment pypi. Только у неё есть id-token: write;
в ней нет checkout и выполнения кода проекта. PyPI обменивает OIDC identity GitHub на
короткоживущие права загрузки. Постоянный PyPI-токен не нужен ни в secrets, ни в репозитории.
При необходимости настройте reviewers окружения для ручного разрешения публикации.
См. официальную настройку PyPI.

PyPI workflow самостоятельный, не reusable: издатель всегда сопоставляется с pypi.yml.
Он принимает только успешные release-запуски этого репозитория и проверяет, что тег
по-прежнему указывает на проверенный коммит, а GitHub release опубликован.
Для повтора запустите publish to PyPI вручную из master, указав существующий тег,
v<project.version>. Ручной запуск проверяет тот же последний CI из master для коммита
пакета и требует его артефакт дистрибутивов; артефакт документации повторно не нужен. Уже загруженные файлы
пропускаются при повторе; версии PyPI нельзя перезаписать.
Не перемещайте опубликованный тег для изменения загруженного пакета.

Установка пакетным менеджеромУстановка пакетным менеджером

pip install 'quite-admin[sqlalchemy,fastapi]'
uv add 'quite-admin[sqlalchemy,litestar]'

Ядро устанавливается как pip install quite-admin без ORM-зависимостей. Другие extras:
sqlmodel, tortoise, peewee, gino-legacy, pydantic, fastapi, litestar, all. GINO 1.x
требует отдельного окружения от современных SQLAlchemy-адаптеров. Установка из
распакованного архива исходников также остаётся доступной.

Уязвимости зависимостейУязвимости зависимостей

security.yml запускает pip-audit и npm audit после каждого пуша в любую ветку,
при полном ручном запуске и еженедельно. В PR выбираются аудиты затронутых экосистем
зависимостей. Python проверяется со всеми зафиксированными extras/dev groups. npm показывает все
уровни и завершает job ошибкой при high/critical. В публичных PR с выбранными проверками
безопасности также работает
GitHub Dependency Review.
Ошибки сети/базы advisories не считаются чистым аудитом. Общих исключений advisory нет.
Приватные сообщения об уязвимостях и политика ранних версий описаны в SECURITY.md.

Зависимости документации закреплены через package-lock.json и overrides в
package.json. scripts/diplodoc.cjs обеспечивает совместимость CommonJS/ESM на Node 24.
Окружение проверяется строгой сборкой EN/RU и новым аудитом безопасности.

Обязательные проверки и артефактыОбязательные проверки и артефакты

ci.yml запускает полный набор workflows Python, документации, JavaScript, браузеров,
БД, совместимости, безопасности и дистрибутивов при каждом пуше в любую ветку.
Необязательный ручной запуск также включает все группы. Пуш тега версии запускает workflows публикации без
повторного CI. Каждый запуск CI проверяет метаданные релиза без установки зависимостей.
Для PR проверки выбираются по Git diff; план виден в сводке запуска:

Смешанные изменения в PR объединяют нужные проверки. Head сравнивается с общей базой
целевой ветки; учитываются удаления и оба пути переименованного файла. Если сравнение
недоступно, выполняются все проверки. Пуши в ветки всегда проходят полный набор независимо
от изменённых путей. Еженедельный скан безопасности продолжает проверять обе экосистемы
даже без обновления зависимостей.

CI ready запускается всегда и требует успеха всех выбранных групп. Допустимы только
пропуски, явно указанные планом; ошибка выбора проверок, ошибка метаданных, отмена или
неожиданный пропуск блокируют gate. Сделайте CI ready обязательным check для master;
защита ветки настраивается в репозитории. Release ready успешен только после полного
прогона; для merge он должен оставаться необязательным. Пуш тега версии запускает только
публикацию и проверяет эти готовые результаты для точного SHA тега. Проверка версии
допускает Unreleased; тег требует даты в changelog.

CI проверяет Chromium, Firefox и WebKit на временной БД с вымышленными данными:
фильтры и поиск связанных ID, задержку поиска, выгрузку CSV/XLSX, inline-тоглы и
конфликты записи, календарь темы, узкую вёрстку и работу без JavaScript. При ошибках
сохраняются скриншоты и трассы. Python-матрица проверяет исходный checkout; отдельная
job дистрибутивов проверяет пару wheel/sdist. При её выборе CI ready и полный
Release ready требуют успеха этой job. Артефакты документации и дистрибутивов
отделены от assets GitHub release.

WebKit запускается на macOS. В Linux-сборке Playwright текстовые вложения сейчас
отображаются как страница вопреки корректному Content-Disposition
(ошибка upstream). На macOS
сценарий проверяет реальные скачивания CSV и XLSX без подмены заголовков ответа.

Pages публикуется после успеха workflow release и повторно проверяет полный CI для
SHA релиза. Успешный полный CI в master также может публиковать изменения только
документации по правилам выше. PR, другие ветки и коммиты с неопубликованными изменениями
пакета не публикуют сайт через этот путь.