fgl-aircon/docs/RELEASE_HA.md

Чек-лист релиза HA-интеграции (H5)

1. Публикация pyfglair (PyPI)

Манифест компонента требует pyfglair>=1.0.0; штатный installer HA резолвит требования только через PyPI. PyPI (warehouse) принимает только manylinux*/musllinux* платформенные теги — локальный py3-none-linux_x86_64 будет отклонён (HTTP 400 unsupported platform tag), поэтому wheel нужно «починить» auditwheel'ом в контейнере со старой glibc (manylinux):

pip install build auditwheel twine

# для каждой архитектуры (linux x86_64/aarch64) в manylinux-контейнере
# (например, quay.io/pypa/manylinux2014_<arch>):
python -m build --wheel                       # .so без внешнего mbedcrypto
auditwheel repair dist/pyfglair-*.whl \
    --plat manylinux2014_x86_64 -w dist/manylinux/   # или manylinux_2_28
rm -f dist/pyfglair-*-linux_*.whl              # linux-тег PyPI отклонит
python -m build --sdist                         # sdist с C++-исходниками (MANIFEST.in)
twine upload dist/manylinux/* dist/*.tar.gz

Проверки перед публикацией:

• scripts/py-ci.sh — pyfglair + acceptance self-test + components;
• scripts/ci.sh — ядро (gcc/clang, ASan/UBSan) 11/11;
• readelf -d build-pyfglair/libfgl-aircon.so* (или распакованный wheel: pyfglair/libfgl-aircon.so*) — нет внешней libmbedcrypto (встроен);
• auditwheel show для repaired-wheel — тег manylinux и только базовые системные библиотеки;
• установка wheel в чистый venv вне репозитория: python -c "import pyfglair.session";
• aarch64: сборка в соответствующем manylinux-контейнере (QEMU или нативная), иначе пользователи ARM не смогут поставить pyfglair.

Альтернатива — cibuildwheel (pip install cibuildwheel) с auditwheel repair внутри, но текущий bdist_wheel-хук отдаёт тег py3-none-<plat>, поэтому проверяйте итоговые теги вручную.

2. GitHub-зеркало и Custom Repositories

HACS устанавливает интеграции только с публичных GitHub-репозиториев (GitLab/Gitea не поддерживаются: https://hacs.xyz/docs/faq/other_git_providers/). Публикация в default-репозиторий HACS не требуется — достаточно Custom Repositories, но хостинг обязан быть GitHub.

# один раз: зеркало и перенос веток/тегов
git remote add github git@github.com:<owner>/fgl-aircon.git
git push --mirror github

После зеркала:

• заполнить в настройках GitHub: Description, Topics (home-assistant, hacs, fujitsu, air-conditioner), включить Issues (эти пункты проверяет HACS Action; файлами они не настраиваются);
• проверить codeowners в custom_components/fglair/manifest.json — сейчас @petr.polezhaev; для GitHub Action/HACS это должен быть реальный GitHub-логин;
• проверить documentation/issue_tracker в манифесте;
• обновить version манифеста под номер тега (сейчас 0.1.0, pyfglair — 1.0.0; компонент и пакет версионируются отдельно);
• заменить заглушки custom_components/fglair/screenshots/step-N.png реальными скриншотами (описания «что должно быть видно» — в README);
• заменить заглушки custom_components/fglair/brand/*.png фирменными ассетами (сейчас — сгенерированные плейсхолдеры: icon/icon@2x/logo и тёмные варианты);
• создать git-тег (semver) в GitHub-зеркале — HACS покажет версию.

Файлы, которые HACS/hassfest проверяют у интеграции: hacs.json, custom_components/fglair/manifest.json (domain/documentation/ issue_tracker/codeowners/name/version), custom_components/fglair/brand/icon.png, README/info.md, OSI-лицензия (LICENSE, MIT). Всё это в репозитории есть; workflow .github/workflows/{validate-hacs,hassfest}.yaml включатся на GitHub.

3. Приёмка на живом стенде

• tests/acceptance/test_esphome_ha.py quick — матрица изменений (HA; с --esphome-host шаги «режим/уставка» идут через ESPHome, проверка — по состоянию в HA), возврат к исходному.
• long --hours 24 --interval 3600 --report acceptance.csv — суточный прогон, отчёт дописывается по ходу.
• Сценарии: 503 (два слота заняты), key_error + Repair, offline и восстановление, два устройства (разные порты прослушивания), options flow (копирование/смена ключа), reconfigure без потери конверсий.

4. Ограничения текущего стенда

• Реального железа/облака в CI нет: протокол проверен mock-модулем (tests/ayla/mock_ac.py), облако — мок-сервером; приёмочный скрипт имеет self-test на моке HA REST.
• Суточный soak, re-key и облачный вход — только на приборе/аккаунте.
• ESPHome-канал приёмки требует установленного aioesphomeapi и работающего ESPHome-компонента (PLAN_ESPHOME); без них скрипт работает только со стороны HA.