Manual de lanzamiento

Proceso manual provisional. Este runbook cubre cómo publicar una versión estable hoy usando release-stable-manual.yml. Sigue siendo el proceso vigente hasta que release-plz llegue y lo reemplace; esa migración aún no ha ocurrido (consulte Hacia dónde se dirige esto).

Si algo aquí se siente pesado, es fricción intencional; todavía no tenemos la disciplina de automatización necesaria para eliminarla de forma segura.

Última verificación realizada para el ciclo de lanzamiento de v0.8.2.

El proceso en siete pasos

1. Generar CHANGELOG-next.md usando la habilidad de changelog
2. Abrir y fusionar una PR de incremento de versión
3. Simula localmente los flujos de trabajo de release con act
4. Disparar el flujo de trabajo Release Stable mediante envío manual
5. Aprueba las dos puertas de entorno cuando se te solicite
6. Verifique que la versión existe y que los activos se pueden descargar
7. Despliegue de documentación versionada

Ese es todo el proceso. Todo lo demás (crates.io, Docker, nuevo despliegue del sitio web, Scoop, AUR, Discord, tuit) se ejecuta automáticamente como trabajos posteriores. Homebrew Core detecta la versión estable de GitHub mediante su propio servicio de actualización automática. No necesitas hacer nada con respecto a ellos, a menos que un trabajo falle explícitamente o la actualización externa de Homebrew siga desactualizada.

Paso 1: Generar CHANGELOG-next.md

Ejecuta el skill changelog-generation para generar CHANGELOG-next.md. Su procedimiento completo se encuentra en .claude/skills/changelog-generation/SKILL.md.

La skill genera el changelog a partir del git log entre la última etiqueta estable y HEAD, resuelve los contribuyentes mediante GitHub GraphQL y escribe el archivo. Confirma el resultado directamente en una rama de corta duración e inclúyelo en el PR de incremento de versión (paso 2), o ábrelo como un PR previo independiente si el diff es grande.

Si CHANGELOG-next.md ya existe de un ciclo de lanzamiento anterior que se abortó, revísalo para comprobar su exactitud antes de reutilizarlo.

Paso 2: Incrementar la versión y fusionar el PR de versión

Incrementa workspace.package.version en el Cargo.toml del workspace y luego ejecuta los dos scripts de lanzamiento en orden. Primero sincroniza todas las referencias de versión en todo el repositorio:

./scripts/release/bump-version.sh    # versión de Cargo.toml

Esto actualiza las insignias de README, la configuración de Tauri y los ejemplos de descripción del flujo de trabajo, y luego regenera todas las superficies de instalación basadas en especificaciones mediante cargo generate installers: install.sh, setup.bat, dist/aur/PKGBUILD, dist/aur/.SRCINFO, dist/scoop/zeroclaw.json, flake.nix, los conjuntos de funcionalidades de Dockerfile/Containerfile, dev/ci/docker-tags.toml, docs/book/src/_snippets/install.md, los bloques de ruta rápida de Unix en la documentación de README/plataforma y el bloque de binarios precompilados de Windows en docs/book/src/setup/windows.md. Los valores de versión, funcionalidades y empaquetado de la aplicación provienen de Cargo.toml y [package.metadata.zeroclaw]; las cuatro rutas de instalación estables provienen de contratos tipados en xtask/src/generate/spec.rs. La actualización mantiene estas superficies sincronizadas automáticamente, por lo que nunca debes editar manualmente una región generada. La disponibilidad de las versiones publicadas sigue definiéndose manualmente y el generador no la infiere. Este script también actualiza los hashes de dependencias Git de Nix (nix/hashes.json) mediante scripts/dev/refresh-nix-hashes.sh.

Actualizar y fijar las traducciones

Después de que bump-version.sh establezca la versión de lanzamiento, actualiza los catálogos de traducción de la documentación y fíjalos a la etiqueta correspondiente. Si los catálogos se prepararon por separado, inspecciona la cobertura y valídalos antes de crear la etiqueta:

cargo mdbook stats
cargo mdbook check

Luego ejecuta el wrapper de release:

./scripts/release/refresh-translations.sh --model-provider anthropic.release

refresh-translations.sh lee la versión desde Cargo.toml (nada escrito a mano), ejecuta el proceso de traducción, confirma y sube los catálogos al submódulo zeroclaw-labs/zeroclaw-docs-translations, crea la etiqueta v{version} allí y prepara el gitlink del repositorio principal fijado a esa etiqueta. Inicializa el submódulo si aún no está descargado. Ejecútalo después de bump-version.sh para que la versión de Cargo.toml que lee sea la versión de publicación. El alias del proveedor configurado se requiere de forma explícita para que la publicación no dependa de un backend codificado; pasa --config-dir cuando sea necesario. El alias seleccionado por --model-provider se resuelve desde providers.models.<kind>.<alias>. Usa --no-translate cuando los catálogos ya estén actualizados, o pasa una versión explícita antes de --model-provider para sobrescribir el valor predeterminado de Cargo.toml, por ejemplo:

./scripts/release/refresh-translations.sh 0.8.2 --model-provider anthropic.release

Confirma todo junto:

chore: bump version to vX.Y.Z

Si la PR también cambia [workspace.package] rust-version o las toolchains de Rust fijadas, trátalo como un cambio de compatibilidad, no solo como tareas de preparación de la release. La PR debe indicar el nuevo MSRV, explicar la ruta de actualización para builds desde el código fuente y demostrar que CI, Docker, el instalador y las superficies generadas coinciden en el nuevo mínimo antes de fusionar.

Abre un PR. Asígnale las etiquetas type:ci, size:XS y cualquier etiqueta de ruta que añada el etiquetador de PR. Si el PR eleva el nivel mínimo de la cadena de herramientas, aplica también risk:high y tramítalo por el carril D. Obtén dos aprobaciones independientes del Core Team. Fusiona solo cuando CI esté en verde. La compuerta Installer Drift de CI hace fallar el PR si una superficie generada no está sincronizada con la especificación, por lo que una regeneración omitida no puede incorporarse. La compuerta Validate Translations Pin resuelve el submódulo en el commit fijado y valida el formato del catálogo y la paridad de msgid, por lo que tampoco puede incorporarse una referencia fijada incorrecta. Consulta Documentación y traducciones para obtener detalles sobre el flujo de traducción.

Confirma que el merge se aplicó correctamente:

git fetch origin
git show origin/master:Cargo.toml | grep '^version'
# Debe mostrar: version = "X.Y.Z"

Paso 3: Ejecute en modo de prueba (dry-run) los flujos de trabajo de lanzamiento localmente con act

El workflow Release Stable es un grafo de trabajos de GitHub Actions que consume tu ventana de aprobación de la puerta de entorno en el momento en que haces clic en Run workflow. Si un paso del workflow está roto: un artefacto de compilación faltante, una ruta obsoleta, un paso de codegen que alguien eliminó sin actualizar la CI, el fallo aparece después de que te has comprometido a una ventana de lanzamiento, con el PR de versión ya fusionado y master en la nueva versión. La recuperación implica integrar una rama de corrección de emergencia, volver a ejecutar la CI y publicar bajo presión de tiempo en un árbol que ya se anuncia como una versión completamente lanzada.

El seguro económico contra esto es ejecutar el mismo grafo de trabajos localmente primero, sobre el commit exacto fusionado en master, antes de abrir el formulario de GitHub Actions. act ejecuta los flujos de trabajo de GitHub Actions dentro de contenedores Docker usando el mismo ecosistema actions/* que usa GitHub. No replica perfectamente el runner en la nube; no puede acceder al runtime de carga de artefactos, a los tokens OIDC emitidos por GitHub, a los secretos de entorno ni a los trabajos que dependen de una etiqueta de versión real, pero sí ejecuta los pasos de compilación y pruebas que representan casi todos los fallos de CI en tiempo de lanzamiento que hemos encontrado.

Este paso requiere una inversión de 15 a 20 minutos por versión. Ha detectado defectos reales que el CI habitual por PR no reveló (porque el flujo de trabajo que falla solo se ejecuta con workflow_dispatch, no con push).

Configuración inicial

act ejecuta los workflows. La ruta de instalación más limpia es la extensión de GitHub CLI, ya que hereda tu autenticación de gh y expone un GITHUB_TOKEN real a cada ejecución de workflow:

1. Instala la CLI de GitHub desde https://cli.github.com (Linux, macOS, Windows). Autentícate una vez: gh auth login.

2. Instala la extensión act:

   sh

   gh extension install nektos/gh-act
   

   Los trabajos que producen artefactos necesitan un protocolo del servicio de artefactos de act que actions/upload-artifact v7 y actions/download-artifact v8 requieren, y ninguna versión publicada actualmente de act lo implementa (comprobado hasta la versión más reciente publicada en el momento de redactar esto). El ayudante comprueba previamente la versión instalada de act antes de iniciar un trabajo que usa las acciones de artefactos con versión fijada y falla de forma segura: no intentará ejecutar el trabajo con una versión no verificada. Hasta que se publique una versión compatible de act y se verifique con un ciclo real de ida y vuelta de artefactos, usa la alternativa alojada en GitHub que aparece a continuación para cualquier trabajo que produzca o consuma artefactos; esa es la ruta recomendada actualmente, no una excepción poco frecuente.

3. Instala Docker Engine o Docker Desktop desde https://docs.docker.com/engine/install/. En Linux, agrégate al grupo docker para no necesitar sudo. act también funciona con Podman y Colima; consulta la documentación de runners de act.

Eso es toda la configuración. El .actrc del repositorio y scripts/dev/act-local.sh se encargan de todo lo demás (imagen del runner, archivo de secrets, servidor de artefactos, precarga de SHA de actions).

Simulación por versión

Asegúrate de que tu árbol de trabajo coincida con el extremo del master fusionado del paso 2:

git fetch upstream
git checkout upstream/master

Lista lo que se puede ejecutar en cada archivo de flujo de trabajo:

./scripts/dev/act-local.sh --list

Ejecuta un trabajo específico, selecciónalo de forma interactiva o ejecuta todos los trabajos seguros para dry-run:

./scripts/dev/act-local.sh release-stable-manual:web   # un trabajo
./scripts/dev/act-local.sh                              # selector interactivo
./scripts/dev/act-local.sh --all                        # todo trabajo seguro para dry-run

La primera ejecución descarga la imagen del runner (~1.5 GB) y prepara la caché de compilación de Rust mediante Swatinem/rust-cache; las ejecuciones posteriores son mucho más rápidas. El script crea automáticamente el archivo .secrets (ignorado por git), descarga previamente cada SHA de acción fijado en ~/.cache/act/ (de lo contrario, el clon superficial de act no puede resolver commits arbitrarios), pasa GITHUB_TOKEN desde tu autenticación de gh a la ejecución a través del entorno del proceso padre (el valor del token nunca llega a argv), y configura --artifact-server-path para que actions/upload-artifact y actions/download-artifact funcionen entre jobs. Todo eso es simplemente act por debajo; el script solo elimina la maraña de flags.

Antes de que se inicie cualquier trabajo que produzca o consuma artefactos, el auxiliar comprueba la versión independiente resuelta de act o gh act con respecto a un umbral interno de compatibilidad (act >= un marcador inalcanzable, actualmente 999.0.0). Ese umbral no es una versión que se deba instalar; ninguna versión publicada de act lo satisface, y solo pasa a ser una versión real y específica una vez que se ha verificado un ciclo real de ida y vuelta de artefactos con esa versión. Todas las versiones de act publicadas actualmente fallan la comprobación previa antes de que se inicie la compilación y apuntan a Actions alojadas en GitHub; no rebajes las acciones de artefactos fijadas para que un ejecutor local supere la comprobación.

Para --all, la compatibilidad se comprueba en el conjunto completo de trabajos seleccionados antes de que se inicie el primer trabajo. Si algún trabajo seleccionado necesita el servicio de artefactos, la ejecución completa falla de forma segura (ninguna versión publicada actualmente de act alcanza el umbral) y termina sin ejecutar un subconjunto parcial. --all --no-allowlist sigue la misma política de compatibilidad.

Los fallos de las comprobaciones previas de artefactos locales son esperables en todas las versiones publicadas actualmente de act, no un contratiempo ocasional. Sube el commit exacto a GitHub y usa el flujo de trabajo alojado como alternativa de validación para los trabajos que usan artefactos. La compilación multiplataforma de solo lectura se puede iniciar de forma segura y supervisar desde la CLI:

gh workflow run cross-platform-build-manual.yml --ref <validation-branch>
gh run list --workflow cross-platform-build-manual.yml --branch <validation-branch> --limit 1
gh run watch <run-id> --exit-status

No actives release-stable-manual.yml antes de tiempo como sustituto de una ejecución en seco: ese flujo de trabajo publica después de recibir las aprobaciones de su entorno. Registra los trabajos de artefactos locales como omitidos debido a la política de versiones, usa la compilación multiplataforma alojada para el ciclo de ida y vuelta de los artefactos y deja la ejecución protegida de la versión estable para el Paso 4.

--all solo ejecuta trabajos en una lista de permitidos segura para dry-run

act no respeta las barreras de protección de entornos de GitHub. Con el GITHUB_TOKEN real del mantenedor introducido en la ejecución, una invocación local exitosa de un trabajo que escribe en GitHub (un publish que llama a gh release create, un trabajo docker que envía a GHCR, un docs-deploy que fuerza el push de gh-pages, un daily-audit que abre un issue, un tweet-release o discord-release que publica en un webhook) podría realizar el efecto secundario en el mundo real al primer intento.

--all por lo tanto aplica una lista de permitidos codificada de forma fija con trabajos que se ha comprobado que son seguros para ejecutar localmente; actualmente los pasos de compilación de solo artefactos en release-stable-manual.yml y cross-platform-build-manual.yml (validate, web, release-notes, build, build-desktop). Todo lo demás se omite con un motivo registrado:

==> skip release-stable-manual:publish (not on dry-run-safe allowlist)
==> skip release-stable-manual:docker (not on dry-run-safe allowlist)
==> skip release-stable-manual:crates (not on dry-run-safe allowlist)
==> skip release-stable-manual:redeploy-website (not on dry-run-safe allowlist)
==> skip docs-deploy:deploy (not on dry-run-safe allowlist)
==> skip daily-audit:advisories (not on dry-run-safe allowlist)
==> skip tweet-release:tweet (not on dry-run-safe allowlist)

La lista de permitidos es fail-closed (falla en modo cerrado): un nuevo workflow añadido al repositorio se trata como potencialmente mutante hasta que un mantenedor lo revisa y añade los IDs de los jobs seguros a DRY_RUN_SAFE_JOBS en scripts/dev/act-local.sh. Esto es importante porque discover_jobs recorre todos los .github/workflows/*.yml, no solo los workflows de release; una lista de denegados dejaría pasar silenciosamente un futuro workflow con superficie de escritura.

Existen dos vías de escape para el caso poco frecuente en el que tengas un motivo para intentar ejecutar localmente un trabajo no incluido en la lista de permitidos:

• ./scripts/dev/act-local.sh release-stable-manual:publish: la forma explícita <wf>:<job> ejecuta lo que solicitas e imprime una advertencia llamativa antes de invocar act si el destino no está en la lista de permitidos.
• ./scripts/dev/act-local.sh --all --no-allowlist: desactiva el filtro de lista de permitidos para una ejecución completa con --all (se usa solo cuando ya has verificado que los pasos del workflow no alcanzarán una superficie de mutación, p. ej. en un fork sin credenciales reales de registro y con un archivo .secrets vacío).

Qué se espera que falle bajo act (y está bien)

act no puede simular algunas superficies exclusivas de GitHub. Estos fallos no son defectos reales:

• Trabajos que dependen de una etiqueta de versión real (publish creando una GitHub Release).
• Trabajos condicionados por el entorno (publish, docker y el publicador de crates): la interfaz de aprobación no existe localmente.
• Tokens de identidad federada basados en OIDC.

Todo lo demás, un error de tsc, un archivo faltante, un fallo de compilación de Rust, una discrepancia en el lockfile de cargo, es un defecto real. No haga clic en Run workflow en el formulario de GitHub Actions hasta que se corrijan mediante un PR estándar desde master.

Paso 4: Activar el lanzamiento

Ir a:

https://github.com/zeroclaw-labs/zeroclaw/actions/workflows/release-stable-manual.ymlHaz clic en Run workflow. Completa:

• Branch: master
• Versión estable a publicar: X.Y.Z, sin el prefijo v

Haz clic en Run workflow.

El primer trabajo (validate) verifica que la versión coincida con Cargo.toml y que no exista ya una etiqueta vX.Y.Z. Si falla, corrige la discrepancia y vuelve a activarlo. No intentes evadirlo.

Paso 5: Apruebe las puertas de aprobación del entorno

Tres trabajos están sujetos a las reglas de protección del entorno de GitHub. Cuando cada uno pase a estar pendiente, verás un banner “Waiting for review” en la ejecución del flujo de trabajo.

Aprueba los tres cuando aparezcan. Aprueba crates-io solo después de que la comprobación previa de su paquete sin token esté en verde:

Si se te pasa la ventana de aprobación y un trabajo agota el tiempo de espera, vuelve a ejecutar solo el trabajo fallido desde la página de ejecución del flujo de trabajo; no es necesario reiniciar desde cero.

Paso 6: Verifica el lanzamiento

Una vez que publish se complete, confirma:

[ ] GitHub Release exists at /releases/tag/vX.Y.Z and is marked Latest
[ ] Release notes are non-empty
[ ] SHA256SUMS asset is present and non-empty
[ ] Both SPDX and CycloneDX SBOM assets are present
[ ] Exactly one zeroclaw-vX.Y.Z-verification.tar.gz asset is present
[ ] No loose *.bundle, *.attestation.jsonl, or *.intoto.jsonl assets are present
[ ] At least one binary archive is downloadable (spot-check linux x86_64)
[ ] Prebuilt Docker and generated Docker matrix jobs are green

CHANGELOG-next.md se deja intencionalmente en master después del lanzamiento: el trabajo de publicación solo lo lee como el cuerpo del lanzamiento, no lo elimina. El siguiente ciclo de lanzamiento lo sobrescribe, por lo que no se requiere limpieza manual.

Para la ruta normal de workflow_dispatch, Docker Publish se ejecuta de forma síncrona dentro del flujo de trabajo de lanzamiento estable. No necesitas una comprobación independiente de Docker si todos los trabajos de lanzamiento aparecen en verde. Si, en cambio, un mantenedor inicia el lanzamiento insertando una etiqueta vX.Y.Z, Docker Publish se inicia como una ejecución independiente activada por etiqueta; confirma que esa ejecución paralela aparece en verde antes de considerar completa la publicación del contenedor. crates.io, Scoop y AUR solo requieren atención independiente cuando sus trabajos aparecen en rojo. Homebrew Core es externo a este flujo de trabajo; su servicio de Autobump comprueba las fórmulas aptas según su propia programación.

Los consumidores que deseen verificar firmas, SBOM o procedencia SLSA en los artefactos publicados pueden seguir Verificación de artefactos de la versión.

Después de cualquier cambio en el flujo de trabajo de atestación de versiones, un mantenedor humano también debe ejecutar el ensayo de verificación en línea y sin conexión en docs/maintainers/release-attestation-runbook.md antes de cerrar la incidencia de seguimiento. Un lint de flujo de trabajo local o una ejecución de act no reemplazan esa comprobación a nivel de versión, porque ninguno puede generar la atestación OIDC de producción de GitHub.

Paso 7: Despliegue de documentación versionada

La documentación de ZeroClaw utiliza una estructura versionada en la rama gh-pages. El job deploy-docs del workflow Release Stable despacha el workflow Deploy mdBook docs to Pages para el tag de release una vez que publish finaliza con éxito; esa ejecución despachada construye y publica la documentación de la versión en /vX.Y.Z/ de forma asíncrona (el job de despacho no espera a que termine). Los detalles de bootstrap y de versión mínima soportada que figuran a continuación son material de referencia para cuando necesites recrear gh-pages o cambiar la ventana de versiones soportadas.

Por qué un despacho explícito y no el desencadenador de inserción de etiquetas. docs-deploy.yml enumera tags: [v*], pero la etiqueta de la versión la crea el trabajo publish mediante gh release create usando GITHUB_TOKEN. GitHub no inicia una nueva ejecución del flujo de trabajo a partir de una inserción de etiqueta creada con GITHUB_TOKEN (docs), por lo que el desencadenador tags: [v*] nunca se activa para una versión creada de esta forma. Por lo tanto, el trabajo deploy-docs invoca docs-deploy.yml mediante workflow_dispatch (la excepción documentada que se ejecuta incluso con GITHUB_TOKEN) con la etiqueta como entrada. Si alguna vez creas una etiqueta manualmente con un token personal, el desencadenador de inserción de tags: [v*] se activa y el despacho del flujo de trabajo de publicación es una reejecución sin efecto del mismo despliegue, y ambas rutas convergen en /vX.Y.Z/.

Qué sucede automáticamente

• El job deploy-docs despacha una compilación que se publica en /vX.Y.Z/.
• “Stable” es un puntero, no una copia. El deploy del tag de release (p. ej., v0.8.0) es lo que construye y publica el directorio de docs de esa versión. bump-version.sh escribe la versión publicada en docs/book/stable-version.txt; integrar ese cambio en master solo actualiza los metadatos de stable. El deploy de master no reconstruye ni vuelve a publicar las docs del tag de release; copia stable-version.txt a la raíz de gh-pages y regenera la redirección de la raíz / y la entrada “Stable (latest release)” del selector de versiones para que ambas apunten al directorio de versión ya publicado de ese release. El deploy falla de forma explícita si el directorio de versión indicado no está presente en gh-pages. No hay un árbol /stable/ duplicado.
• El orden importa: el despliegue de la etiqueta debe colocar /vX.Y.Z/ en gh-pages antes de que un despliegue de master pueda cambiar el puntero estable para que apunte a él. En la secuencia normal de publicación, el PR de incremento de versión se fusiona primero (Paso 2), por lo que su despliegue de documentación de master normalmente se ejecuta antes de que Release Stable cree y despliegue la etiqueta. Ese despliegue anterior de master no encuentra /vX.Y.Z/ y retiene deliberadamente el puntero anterior; el cambio se difiere (consulta la lógica de cambio diferido en docs-deploy.yml). El job deploy-docs crea entonces /vX.Y.Z/, y el cambio se publica en el siguiente despliegue de master después de que el directorio esté activo. Ten en cuenta que deploy-docs solo despacha la compilación de la etiqueta y no espera a que termine: un job deploy-docs en verde significa que el despacho fue aceptado, no que la ejecución de la documentación haya finalizado. Después de que /vX.Y.Z/ esté activo, despacha docs-deploy.yml con tag=master para publicar el cambio del puntero estable (y confirma en la pestaña Actions que las ejecuciones despachadas realmente se completaron correctamente).
• gh-pages es efímera: cada despliegue fuerza el envío de un único commit huérfano (sin acumular historial) y aplica la retención mediante DOCS_KEEP_VERSIONS (master más las N versiones finales más recientes; las versiones preliminares y las finales más antiguas se eliminan). Esto mantiene acotado el tamaño del clon.
• El directorio _shared/ (que contiene CSS de UI, JS y favicons) se actualiza desde la compilación para que el tema se aplique en cascada a todas las versiones desplegadas.
• Las configuraciones regionales traducidas (es, fr, ja, zh-CN) se renderizan desde el submódulo docs/book/po, que el despliegue resuelve mediante submodules: recursive en el commit al que apunte la referencia desplegada. Ese pin se establece durante el aumento de versión; consulta Step 2 para el procedimiento de actualización, etiquetado y fijación. El inglés no necesita submódulo.

Inicializando gh-pages

Si la rama gh-pages alguna vez se elimina o necesita recrearse por completo, inicializa las versiones en este orden específico:

1. Versión compatible más antigua: workflow_dispatch con la etiqueta v0.7.5
2. Próximas versiones: workflow_dispatch con la etiqueta v0.8.0-beta-1, etc.
3. Master actual: workflow_dispatch con la etiqueta master

[!IMPORTANTE] master debe desplegarse en último lugar durante el bootstrapping. Escribe la capa de chrome _shared/ definitiva que utilizan todas las demás versiones.

[!NOTE] La versión estable se resuelve desde docs/book/stable-version.txt (incluido en el código fuente, publicado en la raíz de gh-pages como stable-version.txt). Tras el arranque inicial, confirma que ese archivo indique la versión GA prevista; la redirección de la raíz y la entrada del selector “Stable (latest release)” lo siguen. No se crea ningún directorio /stable/.

Redespliegues manuales y el Version Floor

Para volver a desplegar manualmente una versión específica:

1. Ve a Actions → Deploy mdBook docs to Pages
2. Haz clic en Run workflow
3. Ingrese la etiqueta (p. ej., v0.7.5 o master)

El piso DOCS_MIN_VERSION: Para evitar el despliegue accidental de versiones muy antiguas o sin soporte, el flujo de trabajo aplica un piso de versión mínima (actualmente v0.7.5).

• Las etiquetas más antiguas que DOCS_MIN_VERSION (como v0.7.4) son rechazadas por el flujo de trabajo.
• cargo mdbook gen-versions (el asistente de xtask) ignora cualquier directorio en gh-pages por debajo de este mínimo, manteniéndolos fuera del menú desplegable de versiones.

Si necesitas elevar el mínimo de versión para dejar de dar soporte a una versión anterior:

1. Actualiza la variable de entorno DOCS_MIN_VERSION en .github/workflows/docs-deploy.yml.
2. Los directorios de versiones antiguas se eliminan automáticamente en el siguiente despliegue mediante la pasada de retención DOCS_KEEP_VERSIONS; no se requiere ninguna edición manual de gh-pages para recuperar espacio.

Si algo sale mal

La ejecución muere al instante con startup_failure (cero trabajos creados): Trata esto como un síntoma, no como un diagnóstico de la lista de permitidos. Revisa el resumen de la ejecución y la política de Actions del repositorio. Si GitHub informa de un rechazo de acciones seleccionadas y el flujo de trabajo de publicación añadió o cambió recientemente referencias uses:, compara esas referencias con Acciones permitidas. Añade únicamente el patrón rechazado en Settings → Actions → General, espera unos minutos a que la configuración se propague y luego lanza una nueva ejecución. Si GitHub no informa de un rechazo de política, investiga la definición del flujo de trabajo u otra política del repositorio.

validate falló: discrepancia de versión: El PR de incremento de versión no fue fusionado, o escribiste la versión incorrecta. Corrige la discrepancia y vuelve a ejecutar el disparador.

Una puerta de entorno agotó el tiempo de espera: Vuelve a ejecutar solo el trabajo que agotó el tiempo de espera. No es necesario reiniciar el flujo de trabajo.

Se produjo un error en un trabajo de distribución de Scoop o AUR: Cada uno tiene un subflujo de trabajo correspondiente que se puede activar manualmente. Vuelve a ejecutar el específico primero con dry_run: true para confirmar la corrección y, después, con dry_run: false. No son imprescindibles: un trabajo de distribución fallido no invalida la versión en sí. Para los errores de credenciales de Scoop, usa Scoop Bucket Canary en lugar de considerar una ejecución en seco genérica como prueba de credenciales; el canary activa la ruta credential_canary cerrada ante fallos.

El publicador de crates.io se detuvo después de subir algunos crates: No incrementes la versión ni inicies una segunda publicación. Las versiones de crates.io no se pueden reemplazar ni eliminar. Corrige el crate que falla en el mismo commit de la versión y vuelve a ejecutar Pub crates.io para la misma etiqueta con dry_run: false; el publicador consulta primero cada <crate>@<version> y omite las versiones que ya se publicaron. Lee el paso Publish para ver el último crate publicado correctamente. Si falló la comprobación previa, no se intentó ninguna carga y el problema aún se puede revertir.

El trabajo de scoop falló con remote: Permission ... denied to <account> (403): Es un problema de permisos, no del manifiesto: el token del bucket está caducado o tiene un alcance insuficiente. Rota el token según Rotating SCOOP_BUCKET_TOKEN y, después, ejecuta Scoop Bucket Canary para confirmar la corrección sin escribir en el bucket. Vuelve a ejecutar el publicador de Scoop con dry_run: false y confirma que el bucket haya recibido la nueva versión. La recuperación de Excavator en el lado del bucket sigue pendiente de zeroclaw-labs/scoop-zeroclaw#1, del permiso de escritura en los flujos de trabajo del repositorio y de una prueba de humo del mantenedor; no esperes a que repare una publicación hasta completar esos pasos.

La Scoop Bucket Canary semanal se puso en rojo: El token ha caducado o ha perdido el acceso de escritura. Sigue el mismo proceso de rotación. Arréglalo antes de la próxima versión.

Homebrew Core está desactualizado: Homebrew no es un trabajo del flujo de trabajo de lanzamiento. Consulta el estado de autobump de Homebrew y la ruta documentada de bump manual en lugar de agregar un token de fork del repositorio.

El trabajo de AUR falló con The AUR is down due to maintenance: Una interrupción del servicio upstream, no un problema de credenciales. AUR_SSH_KEY es correcto si el registro muestra la huella de una clave en SSH key diagnostics y el fallo provino del servidor, no de SSH. El publicador reintenta cinco veces durante aproximadamente siete minutos, con un límite de tiempo estricto para el trabajo. Cada intento vuelve a clonar el paquete actual y se detiene en lugar de degradarlo si otra ejecución ya ha publicado una versión más reciente. Llegar al error de mantenimiento significa que la ventana superó el presupuesto de reintentos. Espera a que aur.archlinux.org vuelva a estar disponible y, después, vuelve a ejecutar Pub AUR Package en la etiqueta de lanzamiento con dry_run: true y luego con dry_run: false. Confirma el resultado con curl -fsS 'https://aur.archlinux.org/rpc/v5/info?arg%5B%5D=zeroclawlabs', o simplemente ejecuta AUR Freshness Check. Omitir esto deja al AUR desactualizado silenciosamente hasta que la comprobación semanal lo detecte.

El AUR es más reciente que una versión estable revertida deliberadamente: Verifica la etiqueta de reversión y el contenido del paquete. Si el paquete publicado tiene un epoch distinto de cero que la etiqueta de reversión no contiene, no vuelvas a activar el flujo con la etiqueta antigua: los metadatos de la versión proceden de la etiqueta inmutable, por lo que los cambios en la rama predeterminada no pueden modificar esa ejecución. En su lugar, prepara una versión estable con un número de versión superior que contenga el código revertido, añade la asignación correspondiente de epoch= a dist/aur/PKGBUILD, ejecuta cargo generate installers para regenerar dist/aur/.SRCINFO, revisa ambos archivos, fusiona los cambios y crea una nueva etiqueta de versión. La comprobación de vigencia seguirá en rojo hasta que se publique esa etiqueta. Nunca uses allow_downgrade para cruzar un límite de epoch. Para una reversión dentro del mismo epoch, ejecuta una vez el flujo de trabajo manual Pub AUR Package con dry_run: true para validar la generación de metadatos y la condición objetivo de la protección de versiones; luego ejecútalo con dry_run: false y allow_downgrade: true. La protección de la ejecución real compara además el clon nuevo de AUR. Esa anulación solo existe en la activación manual; la interfaz reutilizable no declara la entrada y, por tanto, no puede solicitarla. Nunca la uses para eludir metadatos de AUR mal formados ni una discrepancia de versiones sin explicación.

La publicación se detuvo porque los archivos del paquete difieren en la misma versión: El publicador se niega deliberadamente a reemplazar archivos diferentes en una tupla epoch:pkgver-pkgrel existente. Inspecciona la diferencia. Un mantenedor autorizado de AUR debe restaurar el PKGBUILD canónico y el .SRCINFO generados a partir de esa etiqueta de lanzamiento, o fusionar un cambio de código fuente corregido y publicarlo con una nueva etiqueta de lanzamiento estable. Editar la rama predeterminada y volver a despachar la etiqueta antigua no puede funcionar, porque el publicador lee los metadatos de la etiqueta inmutable.

La publicación informa de una versión actual de AUR no numérica o con un formato incorrecto: El publicador automatizado falla de forma segura intencionadamente, y allow_downgrade no puede omitir los metadatos con formato incorrecto. Un mantenedor autorizado de AUR debe reparar el paquete mediante un envío manual a AUR con un epoch:pkgver-pkgrel con el formato correcto, verificarlo mediante la RPC de AUR y, después, volver a despachar el publicador normal. No debilite la protección para hacer que el estado publicado con formato incorrecto sea comparable.

Se eliminaron los flujos de trabajo heredados

Varios flujos de trabajo de publicación automática que anteriormente residían en .github/workflows/ han sido eliminados porque omitían la revisión o publicaban de forma irreversible. Ya no están presentes; si alguno reaparece en un PR, trátelo como una regresión y bloquéelo:

El inventario completo de los flujos de trabajo que permanecen (automáticos y manuales) se encuentra en CI & Actions.

Hacia dónde se dirige esto

Este runbook y release-stable-manual.yml son un puente, no un destino.

El estado final objetivo:

• release-plz gestiona automáticamente los incrementos de versión y los registros de cambios
• Un único release.yml reemplaza el actual mosaico de subflujos de trabajo
• La procedencia SLSA está integrada en el pipeline
• El equipo publica versiones fusionando un PR de release, no siguiendo un runbook

Hasta que eso se implemente, usa este proceso. Cada versión que publiques manualmente usando este runbook es práctica que sirve de referencia para lo que la automatización debe hacer.