Acuerdo de soporte de versiones

Acuerdo de soporte de versiones

Este documento describe la política de versionado aplicada tanto al Scene Editor en Creator Hub como al marco de scripting (el @dcl/sdk paquete).

El objetivo de esta política de versionado es forjar un contrato entre el equipo del SDK de la Decentraland Foundation y los creadores de contenido, para establecer expectativas claras y permitir que los creadores planifiquen su trabajo en consecuencia.

Definiciones

• Número de versión -- un identificador único para una versión públicamente disponible del software. Este identificador consiste en una versión mayor y una versión menor número, separados por puntos (por ejemplo, 7.2).

• Familia de versiones -- todas las versiones que tienen idéntica versión mayor forman una familia. Llamamos a la versión A sucesora de la versión B si A y B pertenecen a la misma familia y el número menor de A es mayor que el de B (por ejemplo, 7.11 es sucesora de 7.10).

• Cambio incompatible -- un cambio que obliga a un usuario a modificar su código o activos para mantenerlos funcionando. Por ejemplo, una propiedad cambia de nombre y obliga al usuario a cambiar ese nombre de propiedad cada vez que se usa en su código.

• Cambio compatible -- un cambio que no requiere ninguna acción por parte del usuario. El comportamiento y las propiedades del código y los activos del usuario permanecen sin cambios.

• Versión estable -- una versión que prohíbe cambios incompatibles en todas sus sucesoras (las cuales también se consideran estables). Cualquier cambio incompatible debe introducirse solo mediante la creación de una nueva familia de versiones incrementando el número de versión mayor; sin embargo, vea la salvedad en la sección de cambios incompatibles Los cambios compatibles se reflejan incrementando el número de versión menor.

• Versión inestable -- una versión que permite cambios incompatibles en sus sucesoras. Los cambios incompatibles pueden introducirse incrementando el número de versión menor.

Política de soporte

En cada familia de versiones estables, la Decentraland Foundation solo soporta la última versión menor. En cualquier momento debería haber como máximo dos familias soportadas.

Por ejemplo, si la última versión menor de la familia 6.x es 6.11, y la última versión menor de la familia 7.x es 7.3, se espera que los creadores de contenido desarrollen sus escenas en 6.11 o 7.3. Las escenas que se desarrollaron y publicaron con la versión 6.10 o anterior muy probablemente seguirán funcionando y los jugadores podrán disfrutarlas. Sin embargo, si estas escenas antiguas experimentan algún problema, primero deben actualizarse a una versión soportada, y el problema solo será investigado si aún ocurre en una versión soportada.

El Scene Editor actualiza automáticamente el paquete de scripting de todas las escenas dentro de la misma familia de versiones, de modo que todos los desarrolladores usen la última versión soportada al desarrollar sus escenas.

Desarrollo de funciones

Las nuevas funciones solo se lanzarán en la última versión en desarrollo. En cuanto el equipo de desarrollo comience a trabajar en una nueva familia de versiones, las familias de versiones anteriores que permanezcan en soporte solo recibirán correcciones de errores importantes, y no se implementarán funciones adicionales.

Cambios incompatibles

Los cambios incompatibles deben ocurrir solo en lanzamientos mayores. No debería haber cambios incompatibles dentro de los lanzamientos menores estables de la misma familia de versiones, excepto en caso de emergencia cuando no existan otros medios para abordarlo. Los cambios incompatibles dentro de un lanzamiento menor son una medida drástica que los desarrolladores evitarán a toda costa. Los nuevos lanzamientos menores ampliarán las capacidades de la sintaxis existente, pero nunca deberían cambiar lo que produce la sintaxis establecida, excepto al corregir errores.

Cambios aislados

En ocasiones muy raras, puede ser preferible hacer un pequeño cambio incompatible aislado si solo inconvenienta a un subconjunto reducido de usuarios. (Crear una nueva versión mayor incomoda a todos los usuarios.) En este caso, el SDK podría desaprobar una función, pero debe seguir soportándola por un periodo de tiempo razonable.

Cambios de emergencia

En ciertos casos excepcionales, como preocupaciones de seguridad o requisitos regulatorios, cualquier función puede cambiarse de manera incompatible independientemente de su nivel de estabilidad, y en estas situaciones no se promete una desactivación gradual.

Lanzamientos estables e inestables

Alpha

Siempre que se introduce un nuevo lanzamiento mayor, algunas primeras versiones menores pueden ser etiquetadas como inestables alpha versiones. En los lanzamientos alfa se deben permitir y esperar cambios incompatibles, y los usuarios no deben tener expectativas de estabilidad.

Los desarrolladores son libres de experimentar con estas versiones alfa, pero no se les anima a publicar contenido construido con versiones alfa inestables, ya que no hay garantía de que el contenido siga funcionando tras cambios posteriores. Tampoco se recomienda comenzar migraciones grandes y complicadas en este punto, ya que puede ser necesario realizar más cambios antes del siguiente lanzamiento estable.

Beta

Una vez que una familia de versiones alcanza un cierto nivel de madurez, se pone a disposición un lanzamiento beta . Un lanzamiento beta se considera completo y listo para ser declarado estable, sujeto a pruebas públicas.

Las familias de versiones beta deben ser lo más estables posible; sin embargo, se les permite cambiar con el tiempo. Estos cambios deben ser mínimos pero pueden incluir cambios incompatibles. Los cambios incompatibles solo pueden introducirse después de un periodo de desprecación razonable para dar a los creadores de contenido la oportunidad de migrar sus escenas. Este periodo de desprecación debe definirse cuando se introduce el cambio incompatible.

Las familias de versiones beta deben permanecer en beta solo por un periodo de tiempo limitado, especificado al ser marcadas como beta. Deben promoverse a estables si no se encuentran problemas en ese periodo. La duración de este periodo puede variar caso por caso, pero una buena regla práctica es de 90 días.

El contenido escrito con la sintaxis de una versión beta debe ser fácil de migrar a versiones posteriores dentro de esa familia. Aun así, no es recomendable desarrollar contenido para eventos importantes con una versión beta, ya que las pruebas siguen en curso y es probable que haya errores.

Estable

Una vez que el periodo de beta termina sin problemas importantes, la familia de versiones se considera estable y no debería haber más cambios en la sintaxis, aparte de la adición de nuevas funciones. A partir de este punto, la versión se considera la opción recomendada y fomentada para que la usen todos los desarrolladores.

Una familia de versiones estable debe ser totalmente soportada durante su ciclo de vida. No debe haber cambios incompatibles, sujeto a las salvedades descritas a continuación.

Funciones inestables en lanzamientos estables

Características específicas en un lanzamiento pueden tener niveles de estabilidad distintos al del lanzamiento en su conjunto. Esto puede ser porque la característica se introdujo recientemente y requiere más pruebas, o porque está destinada a ser reemplazada pronto.

Por ejemplo, un nuevo tipo de componente podría introducirse como alfa en un lanzamiento del SDK que ya es estable, ya que ese componente en particular puede aún requerir su propio ciclo de pruebas. Luego puede someterse al flujo de versionado descrito arriba, pasando de alfa a beta y luego a estable.

Cualquier función de un lanzamiento estable que no se considere estable debe estar claramente etiquetada como tal en la documentación. Los creadores que utilicen funciones inestables deben ser conscientes de que la función podría potencialmente sufrir cambios incompatibles. Cualquier cambio incompatible será comunicado claramente, incluyendo guías de migración, y habrá un periodo de transición para que los creadores ajusten el código de su escena.

¿Cuánto tiempo soportamos una familia de versiones estable?

Una vez que una nueva familia de versiones se vuelve estable (7.x), el equipo se compromete a soportar (correcciones de errores importantes) la versión anterior (6.x) durante varios meses, para dar a los creadores suficiente tiempo para migrar. La duración se determina caso por caso, dependiendo del esfuerzo de migración requerido.

Versiones pre-lanzadas

Siempre es posible acceder a las adiciones más recientes del marco de scripting instalando la @next versión del @dcl/sdk paquete en una escena.

Las funciones en esta rama pueden ser inestables o no estar documentadas, ya que no se publican como parte de una versión del SDK oficialmente soportada.