angular-upgrade-copilot

Pack de prompts, guardrails y auditoría para GitHub Copilot que dirige una migración de major de Angular en cualquier repo Angular.

Documentado para la cadena 17 → 18 → 19 → 20, pero el bucle sirve para cualquier par de majors.

Qué es

No es un script que migra solo. Es el proceso que evita las cuatro formas en que una migración de Angular sale mal:

1. Saltar varios majors de una y quedar sin poder diagnosticar qué rompió.
2. Descubrir a mitad de camino que una lib de terceros no soporta el destino.
3. Confundir "compila" con "anda".
4. Mezclar el salto de versión con modernizaciones opcionales, y no poder revertir nada.

Qué contiene

Archivo	Rol
scripts/angular-upgrade-audit.sh	Audita el repo. Lee versiones, peer deps reales, cobertura de tests, estado NgModule/standalone, builders, deps malformadas.
.github/instructions/angular-upgrade.instructions.md	Guardrails always-on. Copilot los aplica solo mientras exista un MIGRATION-PLAN.md.
.github/prompts/angular-upgrade-plan.prompt.md	/angular-upgrade-plan — audita y escribe el plan. No migra.
.github/prompts/angular-upgrade-hop.prompt.md	/angular-upgrade-hop — ejecuta un major.
.github/prompts/angular-upgrade-verify.prompt.md	/angular-upgrade-verify — gate de verificación, sin arreglar nada.
docs/breaking-changes-v18/19/20.md	Referencia por versión. angular.dev es la fuente de verdad.

Instalación

git clone <este-repo>
cd angular-upgrade-copilot
./install.sh /ruta/al/repo-angular

Copia los prompts, las instructions, los docs y el script. No pisa archivos existentes. No toca node_modules ni el código de la app.

Requiere VS Code con Copilot Chat y prompt files habilitados (chat.promptFiles: true en settings).

Uso

1. ./scripts/angular-upgrade-audit.sh     # qué tenés hoy
2. /angular-upgrade-plan                  # escribe MIGRATION-PLAN.md
3. — revisión humana del plan —           # los bloqueantes se deciden acá
4. /angular-upgrade-hop      17->18
5. /angular-upgrade-verify
6. — smoke test manual —                  # esto lo hace una persona
7. repetir 4-6 para 18->19 y 19->20

El paso 3 y el paso 6 son humanos por diseño. El agente no cierra un salto solo.

Las reglas que hacen que funcione

• Un major por vez. ng update soporta un salto. La cadena es explícita.
• Terceros antes que Angular. Si una lib no tiene versión para el destino, el salto para ahí. Nunca --legacy-peer-deps.
• Schematics antes que edición a mano. Y se reporta lo que la schematic omitió.
• El build verde no es la verificación. Con poca cobertura de tests, el smoke test manual es la red de seguridad.
• Sin refactors de oportunidad. El control flow nuevo, inject() y signals van en commits aparte, después.
• El hecho verificado gana. Nada de rangos de versión citados de memoria.

Adaptarlo

Los docs de docs/ son referencia, no dogma: los prompts mandan a verificar contra angular.dev y a corregir el doc si difiere.

Para otra cadena de majors, agregá docs/breaking-changes-vNN.md con la misma forma. Los prompts lo levantan por nombre.