¿Cómo deben gestionarse las versiones, los cambios de esquema, la…

Respuesta directa

Cada texto humano, esquema de datos y paquete de archivos publicado lleva una versión. Clasifique por separado un cambio no sustancial como una corrección ortográfica, un campo o explicación nuevos compatibles hacia atrás y un cambio incompatible que altera un campo, una norma o el comportamiento de un consumidor. No sobrescriba silenciosamente una versión anterior con un cambio incompatible. Publique un nuevo esquema con registro de cambios, lista de registros afectados, correspondencia de migración de antiguo a nuevo, prueba de compatibilidad, fecha de obsolescencia y relación de archivo.

En lenguaje claro

Piense en un plano de carreteras. Corregir una errata en el nombre de una calle no es lo mismo que cerrar un puente y abrir una carretera nueva. Quienes utilicen la ruta nueva necesitan una fecha, una alternativa y saber hasta cuándo sigue siendo útil el plano anterior.

Por qué importa

Eliminar silenciosamente un campo o cambiar una norma puede hacer que aplicaciones antiguas lean mal los datos y crear conclusiones distintas entre idiomas. Un número de versión no basta; deben conocerse el efecto y la vía de migración.

No confundir

Una corrección ortográfica es un cambio editorial que no altera el significado relevante.
Una adición compatible hacia atrás ofrece un campo u opción nuevos sin romper consumidores antiguos.
Un cambio de esquema incompatible puede hacer que un consumidor antiguo funcione de forma errónea o incompleta.
Un cambio normativo altera lo exigido o prohibido; no es solo un cambio técnico de esquema.
La obsolescencia es un ciclo de vida con final notificado y vía de migración, no la eliminación inmediata de un campo.

Qué hacer

Defina de forma versionada los campos públicos, registros normativos y contratos de archivo.
Clasifique cada cambio como editorial, compatible hacia atrás, incompatible, normativo o de seguridad.
Indique en el registro de cambios campo modificado, motivo, registros afectados, fecha y responsable de la decisión.
Conecte versiones humana, JSON, esquema, API, PDF y lingüísticas con la misma declaración de publicación.
Para un cambio incompatible, proporcione correspondencia de campos antiguo-nuevo, ejemplo de transformación y herramienta o instrucción de migración.
Anuncie advertencia de obsolescencia, periodo de soporte, fecha de retirada y vía segura alternativa.
Pruebe compatibilidad con ejemplos antiguos, valide esquema y paridad con ejemplos nuevos y archive la publicación de forma inmutable.

Cómo auditarlo

¿Son explícitos la clase de cambio y el efecto relevante?
¿Designa el número de versión la misma publicación en todas las superficies?
¿Se ocultó un cambio incompatible como corrección menor?
¿Están completos el registro de cambios, los registros afectados y la vía de migración?
¿Se probó realmente la compatibilidad con consumidores y archivos antiguos?
¿Tiene un campo obsoleto fecha, advertencia y alternativa?
¿Está disponible de forma inmutable la versión antigua y relacionada con la nueva?

Límite

Patrones como MAJOR.MINOR.PATCH ofrecen una señal útil sobre el cambio; no demuestran compatibilidad. Un mismo cambio puede afectar de forma distinta a libro, regla normativa, conjunto de datos y API. Una necesidad de seguridad o jurídica puede acortar la migración, pero deben registrarse motivo y efecto.