Es inevitable que realicemos cambios rotundos en Bazel. Tendremos que cambiar nuestros diseños y corregir lo que no funciona del todo bien. Sin embargo, debemos asegurarnos de que la comunidad y el ecosistema de Bazel puedan seguir el ritmo. Para ello, el proyecto Bazel adoptó una política de retrocompatibilidad. En este documento, se describe el proceso que deben seguir los colaboradores de Bazel para realizar un cambio drástico en Bazel para cumplir con esta política.
Sigue la política de documentos de diseño.
Error de GitHub
Informa un problema de GitHub en el repositorio de Bazel. Consulta el ejemplo.
Te recomendamos que hagas lo siguiente:
El título comienza con el nombre de la marca (el nombre de la marca comenzará con
incompatible_).Agregas la etiqueta
incompatible-change.La descripción contiene una descripción del cambio y un vínculo a los documentos de diseño relevantes.
La descripción contiene una receta de migración para explicar a los usuarios cómo deben actualizar su código. Idealmente, cuando el cambio sea mecánico, incluye un vínculo a una herramienta de migración.
La descripción incluye un ejemplo del mensaje de error que recibirán los usuarios si no realizan la migración. Esto hará que el problema de GitHub sea más detectable desde los motores de búsqueda. Asegúrate de que el mensaje de error sea útil y práctico. Cuando sea posible, el mensaje de error debe incluir el nombre de la marca incompatible.
Para la herramienta de migración, considera contribuir a Buildifier.
Puede aplicar correcciones automáticas a los archivos BUILD, WORKSPACE y .bzl.
También puede informar advertencias.
Implementación
Crea una marca nueva en Bazel. El valor predeterminado debe ser falso. El texto de ayuda debería contener la URL del problema de GitHub. Como el nombre de la marca comienza con incompatible_, necesita etiquetas de metadatos:
metadataTags = {
OptionMetadataTag.INCOMPATIBLE_CHANGE,
},
En la descripción de la confirmación, agrega un breve resumen de la marca.
También agrega RELNOTES: en el siguiente formato:
RELNOTES: --incompatible_name_of_flag has been added. See #xyz for details
La confirmación también debe actualizar la documentación relevante, de modo que no haya una ventana de confirmaciones en la que el código no sea coherente con la documentación. Dado que nuestra documentación tiene control de versiones, los cambios en los documentos no se lanzarán de forma prematura por error.
Etiquetas
Una vez que se combine la confirmación y el cambio incompatible esté listo para adoptarse, agrega la etiqueta migration-ready al problema de GitHub.
Si se encuentra un problema con la marca y aún no se espera que los usuarios migren, quita las marcas migration-ready.
Si planeas invertir la marca en la próxima versión principal, agrega la etiqueta "breaking-change-X.0" al problema.
Actualizar repositorios
Bazel CI prueba una lista de proyectos importantes en Bazel@HEAD + Downstream. La mayoría de ellos suelen ser dependencias de otros proyectos de Bazel, por lo que es importante migrarlos para desbloquear la migración para la comunidad en general.
Para supervisar el estado de migración de esos proyectos, puedes usar la canalización bazelisk-plus-incompatible-flags. Consulta cómo funciona esta canalización aquí.
La migración de proyectos en la canalización descendente NO es responsabilidad total del autor del cambio incompatible. Sin embargo, puedes hacer lo siguiente para acelerar la migración y facilitar la vida tanto a los usuarios de Bazel como al equipo verde de Bazel.
- Envía problemas de GitHub para notificar a los propietarios de los proyectos descendentes que se dañaron debido a tu cambio incompatible.
- Envía PR para corregir los proyectos descendentes.
- Comunícate con la comunidad de Bazel para obtener ayuda con la migración (p.ej., Bazel Rules Authors SIG).
Cómo voltear la marca
Antes de cambiar el valor predeterminado de la marca a verdadero, asegúrate de lo siguiente:
Se migran los repositorios principales del ecosistema.
En la canalización
bazelisk-plus-incompatible-flags, la marca debería aparecer enThe following flags didn't break any passing Bazel team owned/co-owned projects.Se resolvieron las inquietudes y preguntas de los usuarios.
Cuando la marca esté lista para cambiar en Bazel, pero esté bloqueada en la migración interna de Google, considera establecer el valor de la marca en "false" en el archivo blazerc interno para desbloquear el cambio de marca. De esta manera, podemos asegurarnos de que los usuarios de Bazel dependan del nuevo comportamiento de forma predeterminada lo antes posible.
Cuando cambies el valor predeterminado de la marca a verdadero, haz lo siguiente:
- Usa
RELNOTES[INC]en la descripción de la confirmación, con el siguiente formato:RELNOTES[INC]: --incompatible_name_of_flag is flipped to true. See #xyz for detailsPuedes incluir información adicional en el resto de la descripción de la confirmación. - Usa
Fixes #xyzen la descripción para que el problema de GitHub se cierre cuando se combine la confirmación. - Revisa y actualiza la documentación si es necesario.
- Envía un problema nuevo
#abcpara hacer un seguimiento de la eliminación de la marca.
Cómo quitar la marca
Después de que se invierta la marca en HEAD, se debe quitar de Bazel con el tiempo. Cuando planeas quitar la marca de incompatible, haz lo siguiente:
- Considera dejar más tiempo para que los usuarios realicen la migración si se trata de un cambio incompatible importante. Idealmente, la marca debería estar disponible en, al menos, una versión principal.
- Para la confirmación que quita la marca, usa
Fixes #abcen la descripción para que el problema de GitHub se cierre cuando se combine la confirmación.