Haz cambios pequeños en una biblioteca de bajo nivel sin romper su API pública

## Haz cambios pequeños y no toques la API ni la ABI públicas salvo que se pida Trata una interfaz pública estable de programación de aplicaciones y una interfaz binaria de aplicaciones como restricciones estrictas. ### Antes de Editar - Lee la documentación del repositorio sobre compilación, pruebas, configuración, contribución y publicación antes de realizar trabajos no triviales. - Identifica el único subsistema o asunto responsable del cambio solicitado. - Sigue las convenciones locales de cada archivo modificado. - Conserva los cambios no relacionados del usuario y los artefactos sin seguimiento. ### Límites del Cambio - Prefiere diferencias mínimas y cambios posteriores incrementales frente a reescrituras amplias. - No renombres, reordenes, reformatees ni limpies código no relacionado. - No añadas una nueva interfaz pública a menos que se solicite explícitamente. - No cambies ni retires una interfaz pública o un contrato binario existente a menos que se solicite explícitamente. - Conserva el comportamiento de las funciones opcionales, las compilaciones con funciones reducidas y las protecciones de compilación condicional. - No cambies silenciosamente los valores predeterminados de compilación o de las funciones. Cuando un código aparentemente incómodo se encuentre en un límite de compatibilidad, supone que puede cubrir un caso límite real hasta que las pruebas, el historial y el comportamiento circundante demuestren lo contrario. ## Compila con el flujo estándar y ejecuta las pruebas del subsistema cambiado Utiliza el flujo estándar del repositorio para configurar, compilar y probar antes de confiar en comprobaciones especializadas. ### Secuencia Predeterminada 1. Configura o vuelve a configurar el directorio de compilación designado. 2. Compila los objetivos afectados. 3. Ejecuta el conjunto de pruebas adecuado para la etapa actual. 4. Confirma que la compilación no introduce nuevas advertencias. Si el directorio de compilación todavía no existe, utiliza la configuración inicial en vez de una ruta exclusiva de reconfiguración. Vuelve a compilar los objetivos modificados después de cada cambio sustancial en el código. ### Comprobaciones Específicas Mínimas - Para la lógica de transformación o modelado de texto, ejecuta su conjunto dedicado de pruebas de comportamiento. - Para trabajos de reducción, creación de subconjuntos o grafos, ejecuta el conjunto correspondiente del subsistema. - Para trabajos sobre interfaces públicas, ejecuta el conjunto de pruebas de la interfaz de programación de aplicaciones. - Para trabajos sobre herramientas de línea de comandos, vuelve a compilar la herramienta pertinente y ejecútala con una pequeña muestra representativa. - Para corregir un error o reforzar un analizador, añade o actualiza, cuando sea práctico, la prueba de regresión, la entrada de fuzzing, el objetivo de fuzzing o el resultado esperado más cercano. Las comprobaciones específicas aceleran la iteración, pero no sustituyen una validación más amplia cuando se ven afectados el comportamiento compartido o la preparación para la publicación. ## Elige dónde cambiar el código según el subsistema y sigue los patrones del proyecto Comprende las responsabilidades adyacentes antes de elegir dónde modificar el código. ### Límites de Responsabilidad - Mantén el comportamiento de la biblioteca principal separado de las herramientas instaladas, las mediciones de rendimiento, la documentación, los enlaces de lenguaje y los componentes experimentales. - Trata los auxiliares de grafos como parte del proceso de reducción cuando participen en su comportamiento. - En unidades de traducción demasiado grandes para rásteres, vectores, gráficos o áreas similares, prefiere extraer auxiliares específicos y dividir por responsabilidad en vez de añadir más bifurcaciones. - Para una integración de lenguaje, examina tanto la definición nativa de compilación como el manifiesto del paquete del lenguaje antes de cambiar la integración de compilación. ### Convenciones Existentes - Utiliza los patrones establecidos por el proyecto para asignación, errores, predicción de bifurcaciones, objetos nulos, contenedores y utilidades. - Prefiere los envoltorios del proyecto a las primitivas directas de la plataforma cuando incorporen comportamiento de portabilidad o seguridad. - No introduzcas una biblioteca externa de contenedores en el código principal cuando el proyecto ya disponga de contenedores y utilidades establecidos. - Añade la documentación de la interfaz pública en la ubicación habitual del repositorio, ya sea en el código fuente o en la documentación. Centraliza la lógica duplicada de análisis, caché o auxiliares cuando la duplicación empiece a extenderse, pero no conviertas una corrección limitada en una reescritura arquitectónica no relacionada. ## Falla con seguridad ante errores de memoria y entradas hostiles en todas las plataformas Trata los fallos de asignación, las entradas hostiles, la diversidad de compiladores y las compilaciones con funciones reducidas como partes normales de la superficie compatible. ### Seguridad de la Asignación y el Analizador - Sigue los patrones existentes de asignación y gestión de errores para que el nuevo código falle de forma segura bajo presión de memoria. - Examina las protecciones existentes del analizador y la infraestructura de fuzzing antes de reforzar el tratamiento de entradas. - Ante un fallo de asignación provocado, el resultado mínimo aceptable es que no se produzcan bloqueos, accesos fuera de límites ni daños en la memoria. - Para componentes experimentales, se acepta un fallo temprano con el mejor esfuerzo posible bajo presión de memoria. - No añadas una lógica compleja de reversión únicamente para conservar trabajo parcial después de un fallo de asignación, a menos que el contrato del componente lo exija. ### Portabilidad - Trata las regresiones de compilador, sistema operativo, anchura de arquitectura, compilación cruzada y compilación con funciones reducidas como errores reales. - Valida las suposiciones en todas las cadenas de herramientas y anchuras de enteros compatibles con el proyecto. - Mantén ejercitadas las protecciones de funciones durante la compilación y las rutas alternativas. - Al simplificar código de bajo nivel, comprueba si la complejidad original gestionaba alineación, desbordamiento, vida útil, aliasing o comportamiento específico de la plataforma. Prefiere una regresión reproducible frente a un cambio que solo corrige el problema sin poder demostrar el fallo original. ## Regenera las tablas generadas desde su generador en vez de editarlas a mano Mantén sincronizadas con el cambio del código fuente todas las descripciones de compilación y los resultados generados. ### Cambios en el Sistema de Compilación - Actualiza conjuntamente las opciones, los resúmenes de configuración, las herramientas instaladas, las pruebas y los objetivos dependientes. - Si el empaquetado o la compilación cruzada se ven afectados, examina todos los sistemas de compilación compatibles en vez de cambiar solo el principal. - Conserva los valores predeterminados de las opciones, a menos que la tarea exija explícitamente un cambio predeterminado. - Valida tanto las formas activadas como las desactivadas de las funciones opcionales afectadas. ### Datos Generados - Modifica el generador, los datos de origen o el flujo de automatización de compilación y, después, vuelve a generar los resultados. - No edites manualmente tablas o índices generados, a menos que la tarea lo exija explícitamente. - No supongas que los resultados generados, los recursos locales de pruebas, las fuentes tipográficas o los artefactos sin seguimiento son desechables. - Revisa las diferencias regeneradas para detectar una amplitud inesperada o cambios no deterministas. Si un cambio en el generador afecta a datos públicos o expectativas de pruebas, actualiza las pruebas y la documentación pertinentes en el mismo cambio limitado. ## Añade API pública solo si se pide, con marca de versión y documentación Trata el comportamiento visible para el usuario como un cambio coordinado de código, documentación, control de versiones e integración de compilación. ### Control de la Interfaz Pública - Mantén las declaraciones públicas en los encabezados o módulos públicos designados, no en archivos internos de implementación. - Añade una nueva superficie pública solo cuando la solicitud lo autorice explícitamente. - Cuando se autorice una nueva interfaz, añade el marcador de versión y la entrada de notas de publicación exigidos por el repositorio. - Actualiza los índices de secciones generados, los manifiestos de documentación o las listas de referencias mediante su flujo aprobado. - Conserva la disposición binaria, la visibilidad de los símbolos, las convenciones de llamada y la compatibilidad del código fuente, a menos que se apruebe explícitamente un cambio incompatible. ### Comportamiento Visible para el Usuario - Actualiza la documentación pertinente cuando una función pase a ser visible mediante una biblioteca o una herramienta instalada. - Mantén la instalación y la integración de compilación sincronizadas con el comportamiento recién expuesto. - Coloca la documentación de la interfaz pública y los índices generados donde exija la práctica local. - No desactives una prueba fallida solo para obtener una ejecución correcta; documenta una excepción justificada y su impacto. ## Encuentra primero la causa raíz y haz commit sin hacer push Demuestra la causa y el resultado antes de presentar un cambio como completado. ### Método de Trabajo 1. Reproduce el problema cuando sea práctico. 2. Comprende la causa raíz antes de escribir la corrección. 3. Si persiste una ambigüedad importante, pregunta en vez de adivinar. 4. Examina el historial antes de simplificar código que parezca inusualmente complejo. 5. Añade o actualiza la cobertura de regresión más cercana. 6. Valida el subsistema modificado, las configuraciones afectadas y el comportamiento más amplio. ### Disciplina de Confirmación - Ejecuta el conjunto completo de pruebas antes de confirmar código, lógica de compilación, resultados generados o entradas de pruebas. - Los cambios exclusivos de documentación o integración continua pueden omitir las pruebas completas solo cuando no puedan afectar a esas áreas; informa de la omisión. - Mantén cada confirmación centrada en un único problema o asunto. - Nunca envíes cambios al repositorio remoto; deja el envío a la persona autorizada. - Utiliza el prefijo de subsistema, las líneas finales de atribución y las convenciones de mensajes del repositorio. - Para un mensaje de confirmación de varias líneas, utiliza un archivo o una entrada respaldada por un editor en vez de secuencias de salto de línea con escape. - Describe la causa raíz, la corrección y las pruebas solo cuando el trabajo realmente realizado las respalde. En la entrega, informa del alcance modificado, las pruebas ejecutadas, las advertencias, las configuraciones no compatibles, los riesgos sin resolver y cualquier validación no realizada.