Cambiar un gran monorepositorio de flujos de trabajo en Python sin romperlo

## Encontrar el paquete responsable y sus instrucciones antes de editar Utiliza en el texto la terminología canónica del dominio del proyecto. Conserva exactamente como lo exige el código los identificadores literales, comandos, rutas, claves de configuración y nombres de compatibilidad; no los reescribas solo para uniformar el estilo. Antes de editar: - Identifica el paquete responsable, sus instrucciones locales y la guía de arquitectura o pruebas más cercana. - Utiliza el entorno de desarrollo y pruebas administrado por el proyecto en lugar de invocar directamente las herramientas del sistema anfitrión. - Instala los mecanismos de enlace o adaptadores de comandos del repositorio mediante el procedimiento documentado de configuración inicial. - Coloca los scripts auxiliares temporales únicamente en el área de desarrollo montada que se haya designado y retíralos al completar la tarea. - Selecciona las comprobaciones según los archivos y paquetes que realmente hayan cambiado. Considera los archivos de bloqueo de dependencias generados y los artefactos similares como salidas de un generador oficial, nunca como código fuente que deba editarse a mano. ## Evitar que el planificador ejecute código de flujos y que los procesos de trabajo toquen la base de datos Comprende el flujo de datos antes de modificar el código de orquestación: 1. Los autores definen flujos de trabajo mediante el SDK público. 2. Los procesadores aislados analizan esas definiciones y conservan los datos serializados del flujo de trabajo. 3. Los planificadores leen los datos serializados y no deben ejecutar código de flujos de trabajo proporcionado por los autores. 4. Los procesos de trabajo ejecutan tareas mediante el SDK o la API admitidos y no deben acceder directamente a la base de datos de metadatos. 5. Los servicios de API median las interacciones de la interfaz de usuario y de los clientes con el estado persistente. 6. Los servicios que activan eventos se ejecutan por separado de los planificadores y los procesos de trabajo. Utiliza credenciales de corta duración y alcance estrictamente limitado entre los componentes. Las comprobaciones de software que desaconsejan el acceso directo a la base de datos son medidas de protección útiles, pero no constituyen una frontera de seguridad frente a código deliberadamente malicioso. Clasifica cualquier posible problema de seguridad antes de proponer una solución: - Una infracción aprovechable del modelo de confianza documentado es una vulnerabilidad. - Un comportamiento ya declarado fuera del modelo de confianza es una limitación conocida. - Una opción de despliegue más segura que no repara una garantía incumplida es una directriz de refuerzo de seguridad. Mantén estas categorías separadas para que la gravedad y la corrección se correspondan con el riesgo real. ## Poner cada dependencia en el paquete que la importa Trata el monorepositorio como un conjunto de distribuciones relacionadas y no como un único paquete indiferenciado. La orquestación principal, los SDK públicos, las integraciones con proveedores, las herramientas de línea de comandos, las plantillas de despliegue, las herramientas de desarrollo y los scripts pueden tener distintos ciclos de publicación y reglas de dependencias. Para una biblioteca compartida: - Mantén su API pequeña e independiente. - Proporciónale su propio árbol de código fuente, pruebas, configuración y dependencias declaradas. - Utiliza los enlaces de espacio de trabajo admitidos por el repositorio en lugar de duplicar código. - Prueba la propia biblioteca y cada consumidor directamente afectado. Coloca cada dependencia en la distribución que la importa. Cuando un cambio atraviese los límites de los paquetes, verifica tanto la dirección de las importaciones como la responsabilidad de publicación antes de modificar los manifiestos. Vuelve a generar los archivos de bloqueo con el flujo de trabajo admitido y revisa que la diferencia de dependencias resultante no contenga cambios ajenos. ## Escribir código Python claro y mantener pequeño cada cambio Aplica formato y análisis estático a cada archivo de Python modificado mientras el cambio aún sea pequeño. Mantén explícito el comportamiento en producción: - No utilices aserciones para la validación durante la ejecución ni para gestionar errores recuperables. - Escribe comentarios que expliquen restricciones o intenciones, no que narren el código. - Mide las duraciones con un reloj monotónico. - Mantén las importaciones en el ámbito del módulo, salvo en los casos documentados de dependencias circulares, carga diferida o dependencias opcionales. - Protege las importaciones costosas que solo sirven para comprobar tipos, a fin de que no afecten al inicio de la ejecución. - Lanza la excepción significativa de alcance más estrecho; no introduzcas una excepción base genérica que lo capture todo. - Convierte los fallos del dominio en respuestas específicas del protocolo únicamente en el límite de transporte. - Nombra las funciones con verbos de acción y conserva el encabezado de licencia requerido. Prefiere un cambio pequeño y fácil de revisar a una refactorización oportunista. Si una limpieza no es necesaria para el comportamiento solicitado, déjala para un cambio independiente. ## Escribir en la base de datos por lotes pequeños para no frenar el planificador Las funciones que reciben una sesión de base de datos no deben confirmar la transacción de forma implícita. Convierte la sesión en un argumento que solo pueda pasarse por palabra clave cuando el código base siga esa convención, y deja que el propietario de la transacción decida cuándo confirmarla o revertirla. Evita las escrituras masivas sin límite dentro de los bucles del planificador o de mantenimiento: 1. Filtra por columnas indexadas. 2. Procesa un lote de tamaño limitado. 3. Confirma o libera la transacción entre lotes. 4. Continúa hasta que no queden filas aptas. Esto limita la duración de los bloqueos, el crecimiento de la memoria y el riesgo de que otros trabajos del planificador queden sin recursos. Confirma el comportamiento en la base de datos predeterminada y ejecuta pruebas de cobertura con motores alternativos cuando la consulta modificada dependa de una semántica específica del motor. Nunca trates un comando de limpieza destructiva como una medida rutinaria de diagnóstico. Determina el objetivo exacto y obtén la aprobación requerida antes de eliminar bases de datos, volúmenes, cachés o datos de usuarios. ## Escribir primero una prueba que falle y ampliar las pruebas solo si hace falta Empieza con una prueba que exprese el comportamiento exacto que se va a cambiar y confirma que falla sin la implementación. Después realiza el cambio mínimo que haga pasar la prueba. Utiliza el marco de pruebas y las herramientas auxiliares preferidos por el repositorio: - Reproduce la estructura del código fuente en el árbol de pruebas. - Utiliza dobles de prueba sujetos a la especificación para que cualquier desviación de la interfaz produzca un fallo claro. - Utiliza los mecanismos admitidos para sustituir la configuración y controlar el tiempo. - Parametriza las variaciones significativas de entradas y motores. - Marca con precisión las pruebas de base de datos y mantén las demás pruebas independientes de su configuración. - Comprueba nombres y campos estructurados de eventos en lugar de texto de registro renderizado e inestable. No pruebes de forma aislada la biblioteca estándar ni una dependencia de terceros. Prueba el comportamiento de integración que es responsabilidad de este código. Ejecuta primero una prueba específica y después el conjunto de pruebas del paquete afectado, la comprobación estática de tipos y el análisis estático; ejecuta conjuntos más amplios solo cuando la superficie de dependencias lo justifique. ## Actualizar juntas las reglas de CI y la documentación, con notas de versión solo para cambios visibles Cuando cambie el comportamiento selectivo de la integración continua, actualiza al mismo tiempo la lógica de selección, sus pruebas y su documentación. Una regla que solo existe en el código o solo en la explicación escrita está incompleta. Añade metadatos de publicación únicamente para los cambios visibles para el usuario en la distribución que entrega ese comportamiento. Las refactorizaciones internas, el trabajo limitado a pruebas, las herramientas de desarrollo y el mantenimiento no visible para el usuario normalmente no necesitan una nota de publicación. Utiliza los generadores del proyecto para los archivos de bloqueo, las referencias de comandos, los esquemas y demás documentación generada. Revisa las diferencias generadas, pero no modifiques archivos generados para ocultar un problema en la fuente canónica. Antes de la entrega, ejecuta las comprobaciones pertinentes de formato, análisis estático, tipos, pruebas, documentación y selección. Registra toda comprobación omitida intencionadamente y la razón concreta por la que no era aplicable. ## Revisar todo el diff y abrir una solicitud de incorporación desde tu bifurcación Revisa la diferencia completa de la tarea antes de publicar. Confirma que los límites arquitectónicos, las suposiciones de seguridad, las pruebas, las salidas generadas, los metadatos de publicación y las instrucciones locales sean coherentes entre sí. Pregunta antes de realizar una refactorización amplia entre paquetes, añadir una dependencia de gran alcance, cambiar el comportamiento de una migración destructiva o efectuar una publicación externa que todavía no esté autorizada. Nunca expongas secretos, eludas mecanismos de enlace obligatorios, edites a mano archivos generados ni ejecutes comandos destructivos de control de versiones sin aprobación explícita. Antes de cualquier operación remota: - Inspecciona los repositorios remotos configurados y verifica cuál es el repositorio canónico y cuál es la bifurcación del colaborador. - No envíes cambios directamente al repositorio remoto canónico ni a su rama predeterminada protegida. - Pregunta antes de cambiar el nombre o reescribir repositorios remotos cuando sus funciones no estén claras. - Busca una solicitud de incorporación existente para no duplicar el trabajo. - Vuelve a basar los cambios o sincronízalos de otro modo con la rama de destino actual mediante el flujo de trabajo aceptado por el repositorio. Utiliza un título en prosa clara, en modo imperativo y centrado en el impacto para el usuario. Explica en el cuerpo por qué se necesita el cambio, declara la asistencia de IA cuando sea obligatorio e incluye referencias a las incidencias pertinentes. No te añadas como coautor ni etiquetes a personas salvo que el usuario lo haya autorizado o que ya participen en la conversación. Si hay una corrección completa preparada, prioriza la solicitud de incorporación en lugar de abrir una incidencia duplicada. Si el cambio es solo una solución provisional, una medida de mitigación o una corrección parcial, crea o enlaza una incidencia de seguimiento y haz referencia a ella tanto en la solicitud de incorporación como cerca del código temporal.