Documentos de diseño

Si planeas agregar, cambiar o quitar una característica orientada al usuario o realizar un cambio arquitectónico significativo en Bazel, debes escribir un documento de diseño y revisarlo para poder enviar el cambio.

Estos son algunos ejemplos de cambios significativos:

  • Adición o eliminación de reglas de compilación nativas
  • Cambios rotundos en las reglas nativas
  • Cambios en la semántica de la regla de compilación nativa que afectan el comportamiento de más de una sola regla
  • Cambios en la API de definición de reglas de Bazel
  • Cambios en las API que usa Bazel para conectarse a otros sistemas
  • Cambios en el lenguaje, la semántica o las API de Starlark
  • Cambios que podrían tener un efecto general en el rendimiento de Bazel o el uso de memoria (para bien o para mal)
  • Cambios en las API internas de uso general
  • Cambios en las marcas y la interfaz de línea de comandos.

Motivos de las revisiones de diseño

Cuando escribes un documento de diseño, puedes coordinar con otros desarrolladores de Bazel y obtener orientación del equipo principal de Bazel. Por ejemplo, cuando una propuesta agrega, quita o modifica cualquier función o objeto disponible en los archivos BUILD, WORKSPACE o bzl, agrega el equipo de Starlark como revisores. Los documentos de diseño se revisan antes de su envío por los siguientes motivos:

  • Bazel es un sistema muy complejo; los cambios locales aparentemente inocuos pueden tener consecuencias globales significativas.
  • El equipo recibe muchas solicitudes de funciones de los usuarios, que no solo se deben evaluar para la viabilidad técnica, sino también en relación con otras solicitudes de funciones.
  • Con frecuencia, las personas ajenas al equipo principal implementan las funciones de Bazel, que tienen diferentes niveles de experiencia en Bazel.
  • El equipo de Bazel tiene diferentes niveles de experiencia. Ningún miembro del equipo comprende todas las partes de Bazel.
  • Los cambios en Bazel deben tener en cuenta la retrocompatibilidad y evitar cambios rotundos.

La política de revisión de diseño de Bazel ayuda a maximizar las probabilidades de que:

  • todas las solicitudes de funciones reciben un nivel de análisis minucioso.
  • Las personas correctas ponderarán diseños antes de invertir en una implementación que tal vez no funcione.

Para ayudarte a comenzar, consulta los documentos de diseño en el repositorio de propuestas de Bazel. Los diseños están en proceso, por lo que los detalles de la implementación pueden cambiar con el tiempo y con los comentarios. Los documentos de diseño publicados capturan el diseño inicial y no los cambios en curso a medida que se implementan los diseños. Siempre consulta la documentación para obtener descripciones de las funciones actuales de Bazel.

Flujo de trabajo de Contributor

Como colaborador, puedes escribir un documento de diseño, enviar solicitudes de extracción y solicitar revisores para tu propuesta.

Escribe el documento de diseño

Todos los documentos de diseño deben tener un encabezado que incluya lo siguiente:

  • escritora
  • fecha del último cambio importante
  • lista de revisores, incluido uno (y solo uno) revisor líder
  • estado actual (borrador, en revisión, aprobado, rechazado, implementado, implementado)
  • vínculo a la conversación de debate (que se agregará después del anuncio)

El documento se puede escribir como un documento de Google legible para todo el mundo o con Markdown. Obtén más información sobre una comparación entre Markdown y Documentos de Google.

Las propuestas que tienen un impacto visible para el usuario deben tener una sección que documente el impacto en la retrocompatibilidad (y un plan de lanzamiento si es necesario).

Crea una solicitud de extracción

Para compartir tu documento de diseño, crea una solicitud de extracción (PR) a fin de agregar el documento al índice de diseño. Agrega el archivo de Markdown o un vínculo de documento a tu PR.

Cuando sea posible, elige un revisor de clientes potenciales y copia a otros revisores. Si no seleccionas un revisor de clientes potenciales, un encargado de mantenimiento de Bazel asignará uno a tu RR.PP.

Después de que creas tu PR, los revisores pueden hacer comentarios preliminares durante la revisión. Por ejemplo, el revisor principal puede sugerir revisores adicionales o indicar información faltante. Los revisores principales aprueban las relaciones públicas cuando creen que el proceso de revisión puede comenzar. Esto no significa que la propuesta es perfecta o se aprobará, es decir, que es suficiente para iniciar el debate.

Anuncia la nueva propuesta

Envía un anuncio a bazel-dev cuando se envíe la solicitud de extracción.

Puedes copiar otros grupos (por ejemplo, bazel-analyze) para obtener comentarios de los usuarios finales de Bazel.

Itera con revisores

Cualquier persona interesada puede comentar tu propuesta. Intente responder preguntas, aclarar la propuesta y abordar inquietudes.

La conversación debería ocurrir en la conversación del anuncio. Si la propuesta se encuentra en un Documento de Google, se pueden usar los comentarios (ten en cuenta que se permiten los comentarios anónimos).

Actualiza el estado

Crea una nueva PR para actualizar el estado de la propuesta cuando se complete la iteración. Envíen el RR.PP. al mismo revisor principal y tome la copia de los demás revisores.

Para aceptar oficialmente la propuesta, el revisor principal aprueba la RR.PP. después de asegurarse de que los demás revisores estén de acuerdo con la decisión.

Debe haber al menos 1 semana entre el primer anuncio y la aprobación de una propuesta. Esto garantiza que los usuarios tengan tiempo suficiente para leer el documento y compartir sus inquietudes.

La implementación puede comenzar antes de que se acepte la propuesta, por ejemplo, como prueba de concepto o experimentación. Sin embargo, no puedes enviar el cambio antes de que se complete la revisión.

Cómo elegir a un revisor de clientes potenciales

Un revisor de cliente potencial debe ser un experto en dominio que cumpla lo siguiente:

  • Conoce los subsistemas relevantes.
  • Objetivo y capaz de proporcionar comentarios constructivos
  • Disponible durante todo el período de revisión para liderar el proceso

Considera buscar contactos en varias etiquetas de equipo.

Markdown vs. Documentos de Google

Decide qué funciona mejor para ti, ya que ambos se aceptan.

Beneficios de usar Documentos de Google:

  • Son eficaces para intercambiar ideas, ya que es fácil comenzar.
  • Edición colaborativa
  • Iteración rápida.
  • Una forma sencilla de sugerir ediciones.

Beneficios de usar archivos Markdown:

  • Limpiar las URL para vincular
  • Registro explícito de las revisiones.
  • Olvídase de configurar los derechos de acceso antes de publicitar un vínculo.
  • Se puede buscar fácilmente con los motores de búsqueda.
  • Preparado para el futuro: el texto sin formato no depende de ninguna herramienta específica y no requiere conexión a Internet.
  • Se pueden actualizar incluso si el autor ya no existe.
  • Se pueden procesar de forma automática (actualizar o detectar vínculos inactivos, recuperar una lista de autores, etcétera).

Primero puedes iterar en un Documento de Google y, luego, convertirlo en Markdown para la posteridad.

Uso de Documentos de Google

Para obtener coherencia, usa la plantilla de documentos de diseño de Bazel. Incluye el encabezado necesario y crea coherencia visual con otros documentos relacionados con Bazel. Para ello, haz clic en Archivo > Crear una copia o en este vínculo para crear una copia de la plantilla de documento de diseño.

Para que todo el mundo pueda leer tu documento, haz clic en Compartir (Avanzado), Cambiar... y, luego, elige “Activado: Cualquier usuario con el vínculo”. Si permites que se agreguen comentarios al documento, cualquier persona podrá comentar de forma anónima, incluso sin una Cuenta de Google.

Usa Markdown

Los documentos se almacenan en GitHub y usan la variante de GitHub de Markdown (Especificación).

Crea un PR para actualizar un documento existente. Los revisores de los documentos deben revisar los cambios significativos. Cualquier persona puede aprobar los cambios de Trivial (como los errores de ortografía, el formato).

Flujo de trabajo del revisor

Un revisor comenta, revisa y aprueba los documentos de diseño.

Responsabilidades generales del revisor

Eres responsable de revisar los documentos de diseño, pedir información adicional si es necesario y aprobar un diseño que apruebe el proceso de revisión.

Cuando recibe una propuesta nueva

  1. Echa un vistazo rápido al documento.
  2. Comenta si falta información crítica o si el diseño no se ajusta a los objetivos del proyecto.
  3. Sugiere revisores adicionales.
  4. Aprueba el PR cuando esté listo para la revisión.

Durante el proceso de revisión

  1. Participar en un diálogo con el autor de diseño sobre problemas problemáticos o que requieren aclaración.
  2. Si corresponde, invita a los usuarios que no dejan opiniones a revisar los diseños.
  3. Decide qué comentarios debe abordar el autor como requisito previo para su aprobación.
  4. Escribe "LGTM" (Se ve bien para mí) en la conversación de debate cuando estés satisfecho con el estado actual de la propuesta.

Sigue este proceso para todas las solicitudes de revisión de diseño. No apruebes diseños que afecten a Bazel si no están en el índice de diseño.

Responsabilidades de los revisores principales

Eres responsable de tomar la decisión de proceder o no proceder con la implementación de un diseño pendiente. Si no puedes hacerlo, debes identificar a un delegado adecuado (reasignar el departamento de RR.PP. al delegado) o reasignar el error a un administrador de Bazel para obtener más disposición.

Durante el proceso de revisión

  1. Asegúrate de que el proceso de iteración de comentarios y diseño avance de manera constructiva.
  2. Antes de la aprobación, asegúrate de que se hayan resuelto las inquietudes de otros revisores.

Después de la aprobación de todos los revisores

  1. Asegúrate de que haya pasado al menos 1 semana desde el anuncio de la lista de distribución.
  2. Asegúrate de que el PR actualice el estado.
  3. Aprobar el PR que envió el autor de la propuesta

Diseños rechazados

  1. Asegúrate de que el autor de RR.PP. envíe un PR o a este.
  2. El PR actualiza el estado del documento.
  3. Agrega un comentario al documento en el que se explique por qué el diseño no se puede aprobar en su estado actual y describe los próximos pasos, si corresponde (por ejemplo, volver a revisar suposiciones no válidas y volver a enviarlo).