Guía para implementar cambios rotundos

Informar un problema Ver fuente . Por la noche · 7.3 · 7.2 · 7.1 · 7.0 · 6.5

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, necesitamos para garantizar que la comunidad y el ecosistema de Bazel puedan seguirlo. Con ese fin, 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 una interrupción en Bazel para cumplir con esta política.

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

  2. Presenta un problema en GitHub.

  3. Implementa el cambio.

  4. Actualiza etiquetas

  5. Gira la marca incompatible.

Problema con GitHub

Presenta 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 de la marca comenzará con incompatible_).

  • Tú le agregas la etiqueta incompatible-change

  • La descripción contiene una descripción del cambio y un vínculo documentos de diseño.

  • La descripción contiene una receta de migración para explicar a los usuarios cómo deberían actualicen su código. Idealmente, cuando el cambio sea mecánico, debes incluir un vínculo a un 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 desde para 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 fuente marca.

Para la herramienta de migración, considera contribuir a Buildifier. Puede aplicar correcciones automáticas a los archivos BUILD, WORKSPACE y .bzl. También es posible que se generen informes de 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. Además, 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 para que no haya de confirmación en la que el código no es coherente con los documentos. Ya que nuestra la documentación tiene control de versiones, por lo que los cambios en los documentos no se realizarán de forma involuntaria lanzar antes de tiempo.

Etiquetas

Agrega la etiqueta cuando se combine la confirmación y el cambio incompatible esté listo para adoptarse. migration-ready al problema de GitHub.

Si se detecta un problema con la marca y no se espera que los usuarios aún realicen la migración, haz lo siguiente: quita las marcas migration-ready.

Si planeas girar la bandera en la próxima actualizació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 ellas suelen ser las dependencias de otros proyectos de Bazel, por lo que es importante migrarlas 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 de bazelisk-plus-incompatible-flags, comprueba cómo funciona esta canalización aquí.

La migración de proyectos en la canalización descendente NO es responsabilidad exclusiva del autor del cambio incompatible. Sin embargo, puedes hacer lo siguiente para acelerar la migración y facilitarles la vida tanto a los usuarios de Bazel como al equipo de Bazel Green.

  1. Presenta problemas de GitHub para notificar a los propietarios de los proyectos posteriores afectados por el cambio incompatible.
  2. Envía los PR para corregir proyectos descendentes.
  3. Comunícate con la comunidad de Bazel para obtener ayuda con la migración (p.ej., Autores de reglas de Bazel SIG).

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

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

Cuando la marca esté lista para cambiarse en Bazel, pero esté bloqueada en la migración interna en Google, considera establecer el valor de la marca en falso 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 la configuración predeterminada de la marca a true, haz lo siguiente:

  • Usa RELNOTES[INC] en la descripción de la confirmación, con el 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 se cierre el problema de GitHub. cuando se combina la confirmación.
  • Revisa y actualiza la documentación si es necesario.
  • Informa un nuevo problema #abc para hacer un seguimiento de la eliminación de la marca.

Cómo quitar la marca

Después de girar la bandera en el encabezado, se debe quitar de Bazel con el tiempo. Cuando planeas quitar la marca incompatible, haz lo siguiente:

  • Considera dejar más tiempo para que los usuarios migren si se trata de un cambio importante incompatible. Idealmente, la marca debería estar 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.