Guía para implementar cambios rotundos

Informa un problema Ver código fuente

Es inevitable que realicemos cambios importantes en Bazel. Tendremos que cambiar los diseños y corregir los problemas. Sin embargo, debemos asegurarnos de que la comunidad y el ecosistema de Bazel puedan seguirlos. Con ese fin, el proyecto de Bazel adoptó una política de compatibilidad con versiones anteriores. En este documento, se describe el proceso para que los colaboradores de Bazel realicen cambios rotundos en Bazel a fin de cumplir con esta política.

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

  2. Informa sobre un problema en GitHub.

  3. Implemente el cambio.

  4. Actualiza las etiquetas.

  5. Actualiza los repositorios.

  6. Marca la marca incompatible.

Problema con GitHub

Informa el error en GitHub en el repositorio de Bazel. Ver ejemplo.

Te recomendamos lo siguiente:

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

  • Agrega 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. Lo ideal es que, cuando el cambio sea mecánico, incluyas 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 hará que el problema de GitHub sea más detectable de los motores de búsqueda. Asegúrese 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 con Buildifier. Puede aplicar correcciones automáticas a los archivos BUILD, WORKSPACE y .bzl. También puede enviar 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 resumen breve de la marca. También agrega RELNOTES: de la siguiente manera: 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 una ventana de confirmaciones en la que el código no coincida con los documentos. Debido a que nuestra documentación tiene control de versiones, los cambios en los documentos no se publicarán de manera prematura.

Etiquetas

Una vez que la confirmación se combine 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 no se espera que los usuarios migren, quita las marcas migration-ready.

Si planeas lanzar la marca en la próxima versión principal, agrega la etiqueta `breaking-change-X.0" al problema.

Actualizar repositorios

IC de Bazel prueba una lista de proyectos importantes en Bazel@HEAD + Downstream. La mayoría de ellos a menudo dependen 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. Verifica cómo funciona esta canalización aquí.

Nuestro equipo de asistencia para desarrolladores supervisa la etiqueta migration-ready. Una vez que agregues esta etiqueta al problema de GitHub, se encargará de lo siguiente:

  1. Crea un comentario en el problema de GitHub para hacer un seguimiento de la lista de fallas y proyectos descendentes que deben migrarse (ver el ejemplo).

  2. Informa los problemas en GitHub para notificar a los propietarios de cada proyecto descendente que no esté disponible debido a tu cambio incompatible (ver ejemplo)

  3. Haz un seguimiento para asegurarte de que todos los problemas se aborden antes de la fecha de lanzamiento objetivo

La migración de proyectos en la canalización descendente NO es completamente responsabilidad del autor del cambio incompatible, pero puedes hacer lo siguiente para acelerar la migración y facilitar la vida de los usuarios de Bazel y del equipo de Bazel Green.

  1. Enviar relaciones públicas para corregir proyectos descendentes

  2. Comunícate con la comunidad de Bazel para obtener ayuda sobre la migración (p.ej., autor de reglas de Bazel en SIG).

Girando la bandera

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 debe aparecer en The following flags didn't break any passing Bazel team owned/co-owned projects.

  • Todos los problemas en la lista de tareas se marcan como fijos o cerrados.

  • Se resolvieron las inquietudes y las preguntas de los usuarios.

Cuando la marca esté lista para lanzarse en Bazel, pero esté bloqueada en la migración interna de Google, considera establecer el valor de la marca en falso en el archivo blazerc interno para desbloquearla. De esta manera, podemos asegurarnos de que los usuarios de Bazel dependan del nuevo comportamiento de forma predeterminada lo antes posible.

Cuando cambies la marca predeterminada a verdadera, haz lo siguiente:

  • Usa RELNOTES[INC] en la descripción de 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 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 nuevo problema #abc para realizar un seguimiento de la eliminación de la marca.

Quita la marca

Después de que se haya lanzado la bandera en HEAD, se debe quitar de Bazel con el tiempo. Si planeas quitar la marca de productos incompatibles, sigue estos pasos:

  • Considere dejar más tiempo para que los usuarios migren si es un cambio importante incompatible. Lo ideal sería que la marca esté disponible en al menos una actualización principal.
  • En el caso de 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.