Guía para implementar cambios rotundos

Es inevitable que realicemos cambios rotundos en Bazel. Tendremos que cambiar nuestros diseños y corregir lo que no funciona del todo. Sin embargo, debemos asegurarnos de que la comunidad y el ecosistema de Bazel puedan seguir el proceso. Para ello, el proyecto de 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 disruptivo en Bazel y cumplir con esta política.

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

2. Informa un problema en GitHub.

3. Implementa el cambio.

4. Actualiza las etiquetas.

5. Actualiza los repositorios.

6. Invierte la marca de incompatibilidad.

Problema 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 pertinentes.

• 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 realizan la migración. Esto hará que el problema de GitHub sea más fácil de encontrar en 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.

En el caso de la herramienta de migración, considera contribuir a Buildifier. Puede aplicar correcciones automáticas a archivos BUILD, WORKSPACE y .bzl. También puede informar advertencias.

Implementación

Crea una nueva marca 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: en el siguiente formulario: RELNOTES: --incompatible_name_of_flag has been added. See #xyz for details

La confirmación también debe actualizar la documentación pertinente para que no haya un período de confirmaciones en el que el código no coincida con la documentación. Dado que nuestra documentación tiene versiones, los cambios en ella no se lanzarán de forma inadvertida antes de tiempo.

Etiquetas

Una vez que se combina la confirmación y el cambio incompatible está listo para adoptarse, agrega la etiqueta migration-ready al problema de GitHub.

Si se detecta un problema con la marca y no se espera que los usuarios migren aún, quita las marcas migration-ready.

Si planeas invertir el valor de la marca en la próxima versión principal, agrega la etiqueta "breaking-change-X.0" al problema.

Actualizar repositorios

La CI de Bazel 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 de 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í.

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 los proyectos descendentes que deben migrarse (consulta el ejemplo).

2. Registra problemas en GitHub para notificar a los propietarios de cada proyecto descendente que se haya dañado por tu cambio incompatible (consulta el ejemplo).

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

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

1. Envía PRs para corregir proyectos downstream.

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

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

• Todos los problemas de la lista de verificación se marcan como corregidos o cerrados.

• Se resolvieron las inquietudes y preguntas de los usuarios.

Cuando la marca esté lista para activarse en Bazel, pero se bloquee en la migración interna en Google, considera establecer el valor de la marca en falso en el archivo blazerc interno para desbloquear la activación de la marca. De esta manera, podemos garantizar 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 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.

Cómo quitar la marca

Después de que se active la marca en HEAD, se debe quitar de Bazel con el tiempo. Cuando planees quitar la marca de incompatible, haz lo siguiente:

• Si se trata de un cambio importante incompatible, considera dejar más tiempo para que los usuarios realicen la migración. Lo ideal es 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.