Saltar a contenido

Checklist pre-update de Home Assistant

Cinco pasos obligatorios antes de presionar "Install" en un upgrade. Saltarse cualquiera de los pasos 1–3 es la causa más documentada de upgrades que rompen sin posibilidad de revert rápido.

Contexto

Esta checklist es la base mínima. Es texto vivo: cada vez que se ingiere un nuevo postmortem de upgrade, el wiki revisa si la checklist habría detectado el fallo. Si no, se agrega un paso.

Contenido

Los 5 pasos

  1. Leer release notes y breaking changes
  2. Ir al blog de ../entities/home-assistant y revisar el changelog completo de la versión target.
  3. Foco en "Breaking Changes": el equipo de HA lista los cambios incompatibles ahí.

  4. Documentar mentalmente qué integrations propias o de ../entities/hacs podrían verse afectadas.

  5. Verificar compatibilidad de integrations

  6. Para cada integration custom (HACS u otra): revisar su GitHub para ver si ya hay un release compatible con la versión target de HA.

  7. Para integrations hardware-specific (Zigbee, Z-Wave, BLE coordinators): revisar issues recientes en el foro / GitHub del repo correspondiente.

  8. Full backup verificado

  9. HA OS / Supervised: Settings → System → Backups → Full backup + descargar a un sitio separado del host (NAS, off-site).
  10. HA Container: snapshot del bind mount /config + dump de cualquier base de datos externa (MariaDB, InfluxDB) si aplica.

  11. Crítico: el backup tiene que ser verificable (extraer + listar archivos / probar restore en sandbox). Un backup que no se probó no cuenta.

  12. Validar configuración

  13. Developer Tools → YAML → Check Configuration.

  14. Devuelve errores de sintaxis y referencias rotas antes del restart. Si esto falla, NO actualizar.

  15. Plan de rollback escrito

  16. Decidir antes del update qué procedimiento se va a aplicar si falla. Las dos opciones documentadas:
    • Full restore desde backup (recomendado para fallos mayores) — ver ha-rollback-procedure.
    • Core-only rollback con ha core update --version <X> — sólo para fallos aislados al Core.
  17. Tener el número de versión anterior anotado.

Extensiones aplicables al setup del usuario

  • Pre-upgrade snapshot de Zigbee (para Z2M): coordinator_backup.json, database.db, configuration.yaml. Aplica si el upgrade toca el add-on Z2M, no sólo el Core.
  • Smoke test de ESPHome devices: ping (o estado en HA) de cada device custom antes del update, para detectar cuáles dejan de reportar después.
  • AI-assisted: pre-update checklist como prompt para Claude Code / agente — input: versión actual + target + repo de configs. Output: lista de probables breaking changes que afectan este setup.

Relaciones

Citas / evidencia

Abierto / gaps

  • Convertir esta checklist a un script ejecutable (bash o agente) que automatice los pasos 1–4.
  • Cuando se ingieran los 2 postmortems de upgrade en gaps, evaluar si la checklist habría detectado el fallo y, si no, agregar paso.
  • Versión específica para HA Container (los paths de UI no aplican directamente).