Guía para implementar cambios rotundos

Es inevitable que hagamos cambios rotundos en Bazel. Tendremos que cambiar nuestros diseños y arreglar las cosas que no funcionan del todo. Sin embargo, debemos asegurarnos de que la comunidad y el ecosistema de Bazel puedan seguir los pasos. Con ese fin, el proyecto de Bazel adoptó una política de retrocompatibilidad. En este documento, se describe el proceso para que los colaboradores de Bazel realicen un cambio rotundo en Bazel para cumplir con esta política.

  1. Sigue la política de documentos de diseño.

  2. Informa problemas en GitHub.

  3. Implementar el cambio.

  4. Cómo actualizar etiquetas

  5. Activa la marca de incompatible.

Problema con GitHub

Informa un problema en GitHub en el repositorio de Bazel. Consulta el ejemplo.

Te recomendamos lo siguiente:

  • El título comienza con el nombre de la marca (el nombre comenzará con incompatible_).

  • Agrega la etiqueta incompatible-change.

  • La descripción contiene una descripción del cambio y un vínculo a 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. Lo ideal es que, cuando el cambio sea mecánico, se incluya 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 migran. Esto permitirá que los motores de búsqueda puedan detectar el problema de GitHub con mayor facilidad. 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 de 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 debe 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: de la siguiente forma: RELNOTES: --incompatible_name_of_flag has been added. See #xyz for details

La confirmación también debe actualizar la documentación relevante para que no haya ninguna ventana de confirmaciones en la que el código no sea coherente con los documentos. Dado que nuestra documentación tiene control de versiones, los cambios en los documentos no se lanzarán de forma prematura de forma involuntaria.

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 piensas girar la marca en la próxima versión importante, 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 a fin de 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 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 de los usuarios de Bazel y el equipo de Bazel Green.

  1. Presenta problemas de GitHub para notificar a los propietarios de los proyectos descendentes dañados por tu cambio incompatible.
  2. Envía los PR para arreglar proyectos descendentes.
  3. Comunícate con la comunidad de Bazel para obtener ayuda durante la migración (p.ej., SIG de autores de reglas de Bazel).

Girando la bandera

Antes de cambiar el valor predeterminado de la marca a verdadero, asegúrate de que:

  • Se migran los repositorios principales del ecosistema.

    En la canalización bazelisk-plus-incompatible-flags, la marca debe aparecer en The 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 girar en Bazel, pero se bloqueó durante la migración interna en Google, considera establecer el valor de la marca como falso en el archivo blazerc interno para desbloquearlo. De esta manera, podemos asegurarnos de que los usuarios de Bazel dependan del nuevo comportamiento de forma predeterminada lo antes posible.

Si cambias la marca predeterminada 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 details. Puedes incluir información adicional en el resto de la descripción de la confirmación.
  • Usa Fixes #xyz en 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.
  • Presenta un problema nuevo #abc para hacer un seguimiento de la eliminación de la marca.

Quita la marca

Después de girar la bandera en el encabezado, se debe quitar de Bazel finalmente. Si tienes pensado quitar la marca incompatible, ten en cuenta lo siguiente:

  • Considera dejar más tiempo para que los usuarios migren si se trata de un cambio importante incompatible. Lo ideal sería que la marca esté disponible en al menos una versión principal.
  • Para la confirmación que quita la marca, usa Fixes #abc en la descripción para que el problema de GitHub se cierre cuando se combine la confirmación.