Promotion Guard
Cada build termina con un chequeo de seguridad antes de que el nuevo site reemplace al viejo: el promotion guard compara el build terminado contra el último build bueno (en conteo de páginas, broken links, marcadores de contenido sin resolver y problemas de accesibilidad) y se niega a publicar un build que parece una regresión. El peor caso que permite es output obsoleto, nunca output roto.
Esta página explica qué revisa, cómo configurarlo y cómo forzar un build más allá de él.
Qué revisa el guard
Cuatro gates independientes, evaluados por build y resumidos en un solo reporte:
| Check | Qué compara | Threshold por defecto |
|---|---|---|
| Caída de conteo de páginas | Archivos en el build terminado vs la última promoción buena | Una caída de más del 80% bloquea |
| Broken internal links | Incremento vs el conteo almacenado en el último promote limpio | Un incremento de más de 25 |
| Marcadores de bloque sin resolver | Conteo absoluto de comentarios <!-- block not found --> en el output | Desactivado hasta que fijes el límite (0 significa "ni siquiera uno") |
| Problemas de accesibilidad | Incremento vs el último promote limpio (imágenes sin alt text, lang faltante, enlaces vacíos, múltiples H1s por página) | Un incremento de más de 10 |
Por qué deltas en lugar de absolutos para dos de los cuatro: los conteos absolutos escalan naturalmente con el tamaño de tu site (todas las páginas pueden compartir un enlace o un estilo de imagen), así que lo que importa es un salto repentino, no un total de estado estable. Un baseline de conteo de páginas que se ha desplazado hacia abajo tampoco aplica: los builds fallados y bloqueados nunca lo fijan, y un "promote anyway" tampoco lo resetea. El punto de comparación es siempre el último build que el guard dejó pasar limpio, así que no se puede convencer al guard de tolerar un deslizamiento lento.
Los tres modos
Bajo Settings → Workflow:
- Warn (por defecto): un build que incumple un threshold todavía promociona, pero se escribe una línea de warning clara en el build log: qué incumplió, por cuánto, y cuál era el límite. Lo mejor mientras aprendes qué ve el guard en tu site.
- Enforce: un build que incumple no se publica: la copia de staging se descarta y el site previo en vivo sigue sirviendo. El build log registra el resultado como bloqueado, con la razón y los conteos de calidad, y el dashboard muestra un banner de Promotion Blocked.
- Off: no corre ningún guard. No recomendado como setting permanente; si el guard es ruidoso usa "Warn" mejor.
Los thresholds se ajustan a valores sanos al guardar (el porcentaje de caída 0-100; los demás, enteros no negativos). El gate de marcadores sin resolver arranca desactivado en sites actualizados para que una actualización de rutina nunca bloquee de repente los builds por un bug de contenido antiguo. Fija un número (incluso 0) para activarlo deliberadamente.
Cuando un build es bloqueado
- El panel de estado del dashboard cambia a Promotion blocked con la razón, y aparece un botón Promote anyway, pero solo en ese estado, y solo para admins.
- El site construido no se muestra: todo lo del candidato fallido se descarta limpiamente, y el site en vivo nunca sirve una promoción a medio hacer.
- El historial de builds guarda el intento fallido con su log completo y los conteos de calidad, así que puedes ver exactamente qué regresionó (un crash de página, un template roto produciendo ruido de enlaces faltantes, una masa de páginas sin publicar) antes de decidir.
- Un build bloqueado es un warning sobre tus cambios, no una falla del sistema: la causa clásica es publicar un build mientras un template roto o un borrador malo está en vivo.
Promote anyway (el escape hatch)
Si un build está bloqueado y estás seguro de que es correcto (por ejemplo, borraste deliberadamente un tercio del site), haz clic en Promote anyway en el dashboard (o, para builds scriptados, CHINASKI_FORCE_PROMOTE=1 perl builder/build.pl):
- Se omite el guard solo para ese build; el siguiente build normal corre los chequeos completos de nuevo.
- El bypass no refresca los baselines de calidad. Esto es deliberado: forzar números malos al baseline haría que la misma regresión se vuelva "normal" y sea ignorada en builds futuros. El siguiente build regular todavía compara contra la última promoción limpia, así que la regresión permanece visible hasta arreglarse.
- El botón de bypass del dashboard aparece solo mientras un build está bloqueado; los demás chequeos siguen activos. El escape hatch es de un solo uso, y el log lo registra.
Configurando el guard
| Setting (Settings → Workflow) | Campo | Efecto |
|---|---|---|
| Guard mode | Warn / Enforce / Off | Si los incumplimientos avisan o bloquean |
| Page-drop threshold | porcentaje | Cuántos archivos puede perder un build antes de que el guard se pronuncie |
| Broken-link increase | entero | Crecimiento máximo vs el último promote limpio |
| Unresolved block markers | vacío/número | Vacío = gate desactivado; un número (incluso 0) = límite duro sobre embeds de bloque faltantes |
| A11y issue increase | entero | Crecimiento máximo de problemas de accesibilidad vs el último promote limpio |
Los thresholds son por instancia. Si ves warnings frecuentes en un site sano, revisa primero el reporte de incumplimientos: el guard te dice exactamente qué gate se disparó y por cuánto, y cada threshold tiene un default seguro que le cabe a la mayoría de los sites.
Casos con guard desactivado (promociones sin comparación)
- Guard mode fijado a Off.
- Un build forzado (el escape hatch de arriba).
- El primer build después de un arranque limpio (aún no hay nada contra qué comparar; el reporte de calidad igual se produce).
- Los deltas de broken links y a11y cuando no existe un baseline previo (primer build, o bases de datos anteriores). Esos gates despiertan tan pronto como un promote limpio haya almacenado números de baseline.
Letra pequeña
- El gate de "conteo de páginas" cuenta los archivos que escribió el build, lo cual incluye pequeños archivos de soporte además de las páginas de contenido. Así que los builds muy pequeños (sites de tres páginas) tienen proporcionalmente más sensibilidad. El default del 80% absorbe eso.
- Los builds incrementales reciben el mismo guard que los completos: staging es una copia completa del site de cualquier manera, así que los conteos siguen comparables.
- El guard nunca cambia el output mismo. Solo puede avanzar o descartar la copia de staging.