Modificar una biblioteca de datos multilingüe sin romper sus formatos de archivo ni sus API

## Conocer el núcleo nativo y los enlaces ligeros para otros lenguajes Considera el repositorio como un núcleo nativo con enlaces ligeros para otros lenguajes. El núcleo es responsable del comportamiento del formato de datos, la codificación, la compresión, los archivos, los índices, la E/S, el almacenamiento de objetos, el álgebra lineal, las operaciones con tablas, los dominios opcionales, la infraestructura de pruebas y las herramientas de desarrollo. Los enlaces exponen ese comportamiento sin duplicar la validación ni la lógica de negocio. Conserva las características principales de la arquitectura: E/S asíncrona, memoria columnar nativa, escrituras versionadas con seguimiento mediante manifiestos, codificaciones orientadas a cargas de trabajo y una sola abstracción de almacenamiento para almacenes de objetos locales y remotos. Lee la guía del repositorio y la guía de cada lenguaje o directorio afectado antes de planificar comandos o cambios de código. Las reglas específicas de un directorio concretan el contrato del repositorio, no lo sustituyen. ## Mantener compatibles los formatos estables y cambiar libremente los inestables Considera todo formato declarado estable como un contrato de compatibilidad duradero. Un cambio en datos estables debe preservar tanto la compatibilidad con versiones anteriores como la compatibilidad con versiones posteriores. Considera desechable todo formato declarado inestable. Puede cambiar libremente; no añadas código de compatibilidad, migraciones, alternativas ni pruebas para archivos creados por revisiones inestables anteriores. Evalúa el nuevo trabajo de compatibilidad con respecto a la última versión estable publicada y sigue respetando todos los contratos de formatos estables. Los estados que solo existen en la rama de desarrollo actual no son restricciones de compatibilidad. No debilites un diseño más limpio o completo únicamente para conservar un estado intermedio no publicado. ## Usar los comandos y perfiles de compilación documentados, sin cambiar de cadena de herramientas Localiza los comandos documentados de comprobación, pruebas, análisis estático, formato, cobertura, rendimiento e integración del lenguaje afectado antes de ejecutarlos. Usa los selectores de paquetes y pruebas que proporciona el repositorio en vez de inventar un flujo de trabajo paralelo. No sustituyas el gestor de entornos ni la cadena de herramientas porque parezca que falta un comando, que es lento o que no está disponible. Si un comando específico de un lenguaje falla fuera del flujo documentado, corrige primero el uso del entorno y vuelve a ejecutar el comando prescrito. Solo entonces puedes concluir que una dependencia o herramienta no está disponible. Utiliza los perfiles de compilación definidos por el repositorio en vez de aplicar modificaciones improvisadas de optimización. Realiza pruebas de rendimiento y análisis de perfiles con una compilación optimizada que conserve los símbolos de depuración. Desactiva la optimización en tiempo de enlace únicamente para depuración local, pruebas de rendimiento limitadas por la E/S o investigaciones del tiempo de compilación en las que no pueda afectar al cuello de botella medido. Para las pruebas de integración, inicia solo los servicios de datos de prueba necesarios, establece los valores de entorno documentados y ejecuta el objetivo de integración designado. ## Escribir código centrado que procese los datos en flujo sin acumularlos en memoria Usa inglés en el código, los ejemplos y los comentarios. El código debe optimizar tanto la legibilidad como la ejecución. Añade comentarios únicamente cuando expliquen un motivo que no sea evidente, y elimina las impresiones directas de depuración antes de la revisión en favor del sistema establecido de rastreo o registro. Extrae a una función auxiliar compartida la lógica que se repita en dos o más lugares. Mantén la lógica de un solo uso en el punto donde se invoca. Introduce una función auxiliar solo cuando reduzca de forma sustancial la carga cognitiva o elimine duplicación considerable; no añadas un envoltorio superficial que se limite a cambiar el nombre de una llamada o reenviarla. Mantén los cambios enfocados. Evita refactorizaciones oportunistas, cambios de formato y modificaciones meramente estéticas. Conserva el comportamiento de transmisión en vez de acumular lotes en memoria y, para comprobar la pertenencia de enteros densos, prefiere estructuras compactas de mapas de bits frente a conjuntos hash generales. ## Mantener ligeros los enlaces y marcar como obsoletas las API antiguas en lugar de romperlas Centraliza la validación y la lógica en el núcleo nativo, y mantén cada enlace de lenguaje como un envoltorio ligero. Utiliza los mismos nombres de parámetros en todos los enlaces; cámbialos en todos o no los cambies en ninguno. Nunca rompas una firma pública existente mediante una modificación en el mismo lugar. Marca el método anterior como obsoleto con la anotación compatible del lenguaje y añade un método nuevo. Sustituye los grupos de indicadores booleanos mutuamente excluyentes por un solo parámetro de enumeración o modo. Cuando cambie el comportamiento del núcleo, actualiza a la vez cada enlace aplicable, interfaz generada, ejemplo y prueba de compatibilidad. Un enlace no debe reinterpretar silenciosamente un valor que el núcleo rechaza. ## Nombrar los valores por lo que son y rechazar entradas no válidas con errores claros Nombra una variable según lo que es su valor, no según el uso circunstancial que se le dé. Elimina prefijos redundantes cuando el tipo o módulo contenedor ya indique el dominio. Utiliza de manera coherente una única forma plural aprobada en las API y la documentación, y prefiere nombres neutrales respecto al almacenamiento frente a términos propios de un proveedor. Al cambiar el nombre de un tipo, una estructura o una enumeración, actualiza conjuntamente los métodos, campos, variables, pruebas y documentación. Valida la entrada en los límites de la API y rechaza los valores no válidos con errores descriptivos. Nunca los limites ni ajustes silenciosamente. Rechaza las opciones de constructor o configuración mutuamente excluyentes cuando ambas estén presentes. Incluye en los mensajes de error los nombres, valores, tamaños y tipos de las variables pertinentes. ## Añadir pocas dependencias y mantener sincronizados los archivos de bloqueo Antes de añadir un paquete externo, prefiere la biblioteca estándar o las dependencias existentes del espacio de trabajo. Mantén intencionados los cambios de los archivos de bloqueo, revierte las actualizaciones no relacionadas y fija una dependencia defectuosa únicamente con un comentario que enlace su incidencia de origen. Cuando cambie una dependencia del espacio de trabajo, actualiza el archivo de bloqueo raíz y cada archivo de bloqueo de enlaces excluido mediante las comprobaciones documentadas específicas del manifiesto y, después, confirma todos los cambios correspondientes. Mantén activo el control sin conexión que sincroniza los archivos de bloqueo. Coloca las dependencias opcionales o específicas de un dominio tras flags de funcionalidad. Prefiere un paquete separado para una funcionalidad de dominio importante, de modo que las compilaciones predeterminadas y los consumidores no hereden código innecesario. ## Añadir una prueba a cada corrección de errores y a cada función nueva Toda corrección de un defecto y toda función requieren pruebas correspondientes. No aceptes código sin pruebas. Utiliza el mecanismo de pruebas parametrizadas del lenguaje cuando los casos solo difieran en las entradas, y dales nombres legibles. Sustituye las impresiones en las pruebas por aserciones, porque una salida por sí sola no detecta regresiones. Amplía una prueba existente cuando ya sea responsable del comportamiento, en vez de añadir un archivo de pruebas que se solape. Coloca las ampliaciones en la ubicación de pruebas establecida. Toda prueba omitida debe enlazar a una incidencia de seguimiento; nunca añadas una anotación de omisión aislada sin un motivo duradero. ## Probar con datos nulos o vacíos y con archivos de versiones estables antiguas Incluye situaciones con varios fragmentos para lecturas, índices y recorridos. En las pruebas de índices, cubre elementos nulos, colecciones cuyos elementos sean todos nulos, colecciones vacías y columnas nulas. Las pruebas de índices vectoriales deben afirmar una métrica de exhaustividad (`recall`) de al menos 0,5, no limitarse a comprobar que la creación del índice finaliza correctamente. Para la compatibilidad con versiones anteriores, utiliza conjuntos de datos incluidos en el control de versiones y generados por versiones estables anteriores. Mantén un programa de generación de datos que afirme la versión que los produjo y copia estos datos de prueba en almacenamiento temporal antes de leerlos. No desactives las pruebas de documentación solo para evitar la compilación. Escribe ejemplos que se compilen dentro de un contexto con forma de función. Excluye de la cobertura las utilidades exclusivas de pruebas mediante la anotación de cobertura aprobada por el proyecto, en vez de reducir los umbrales de cobertura del código de producción. ## Documentar cada API pública con un ejemplo que compile Documenta cada API pública e incluye un ejemplo. Enlaza a los tipos y métodos pertinentes, y mantén los ejemplos sincronizados con las firmas reales siempre que se refactorice el código. Utiliza diagramas de árbol ASCII para estructuras jerárquicas como capas de codificación, formatos de archivo y disposiciones de almacenamiento. Respeta el contrato de sangría del sistema de documentación, incluida la sangría de cuatro espacios bajo las directivas de advertencia. Revisa los comentarios y la documentación para detectar erratas antes de la revisión. La documentación que ya no se compila o que nombra una API obsoleta constituye un defecto de compatibilidad, no un problema estético. ## Etiquetar las incidencias y pasar el lint antes de abrir una solicitud de cambio Al crear una incidencia mediante una herramienta de línea de comandos o una API, pasa la etiqueta explícita correspondiente a defecto, función o rendimiento, porque es posible que se omita la automatización de plantillas. Añade al título el prefijo de clasificación coincidente para que la automatización basada en el contenido disponga de una señal alternativa fiable. Utiliza los prefijos convencionales de títulos de cambios del repositorio y añade un ámbito cuando sea útil. Antes de crear o actualizar una solicitud de cambio, ejecuta los análisis estáticos obligatorios para cada superficie de lenguaje afectada, aunque sean costosos. Sigue el flujo de entorno de la guía de cada lenguaje para ejecutar sus comandos de análisis estático. Si no se puede ejecutar una comprobación obligatoria, indica expresamente el bloqueo en el resumen de la solicitud de cambio en vez de dar a entender que la validación está completa. ## Centrar la revisión en los errores graves y los problemas de seguridad La atención de quienes contribuyen y mantienen es limitada. Mantén las revisiones concisas y claras, y céntrate en los defectos de mayor gravedad, las regresiones de rendimiento y los problemas de seguridad. No repitas los cambios detallados ni lo que ya sea correcto. Comprueba la coherencia de los nombres, los patrones establecidos de tratamiento de errores y la cobertura de las pruebas. Cita la ubicación afectada y explica la consecuencia concreta de cada hallazgo bloqueante.