Documentos de diseño

Informa un problema Ver código fuente

Si planeas agregar, modificar 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 antes de enviar el cambio.

Estos son algunos ejemplos de cambios importantes:

  • Agregar o borrar reglas de compilación nativas
  • Cambios rotundos en las reglas nativas
  • Cambios en la semántica de una regla de compilación nativa que afectan el comportamiento de más de una regla
  • Cambios en la API de definición de reglas de Bazel
  • Cambios en las API que Bazel usa para conectarse a otros sistemas
  • Cambios en el lenguaje, la semántica o las API de Starlark
  • Cambios que podrían tener un efecto generalizado en el rendimiento de Bazel o el uso de memoria (para mejor o peor)
  • 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 buscar orientación del equipo central 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 deben evaluarse no solo para la viabilidad técnica, sino también para la importancia con respecto a otras solicitudes de funciones.
  • Las funciones de Bazel son implementadas con frecuencia por personas ajenas al equipo principal, estos colaboradores tienen diferentes niveles de experiencia en Bazel.
  • El equipo de Bazel tiene diferentes niveles de experiencia; ningún miembro del equipo comprende todos los aspectos de Bazel.
  • Los cambios en Bazel deben tener en cuenta la retrocompatibilidad y evitar los cambios rotundos.

La política de revisión de diseño de Bazel ayuda a maximizar la probabilidad de que ocurra lo siguiente:

  • todas las solicitudes de funciones obtienen un nivel de análisis de referencia.
  • Las personas correctas opinan sobre diseños antes de que invirtamos en una implementación que puede no funcionar.

Para ayudarte a comenzar, consulta los documentos de diseño del repositorio de propuestas de Bazel. Los diseños están en desarrollo, por lo que los detalles de la implementación pueden cambiar con el tiempo y con 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. Consulta siempre la documentación para obtener descripciones de la funcionalidad actual 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:

  • author
  • 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 del debate (se agregará después del anuncio)

El documento se puede escribir como un documento de Google legible por todo el mundo o mediante Markdown. Lee a continuación para obtener una comparación de Markdown/Google Docs.

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).

Crear una solicitud de extracción

Comparte tu documento de diseño; para ello, 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 solicitud de extracción.

Cuando sea posible, elige un revisor líder y agrega a otros revisores en copia. Si no eliges un revisor de clientes potenciales, un encargado de mantenimiento de Bazel asignará uno a tu RR.PP.

Después de crear tu PR, los revisores pueden realizar comentarios preliminares durante la revisión del código. Por ejemplo, el revisor principal puede sugerir revisores adicionales o indicar que falta información. El revisor líder aprueba el proceso de Relaciones Públicas cuando cree que puede comenzar el proceso de revisión. Esto no significa que la propuesta sea perfecta o que se apruebe, sino que incluye suficiente información para comenzar el debate.

Anuncia la nueva propuesta

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

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

Itera con los revisores

Cualquier persona interesada puede comentar su propuesta. Intenten responder preguntas, aclarar la propuesta y abordar inquietudes.

Las conversaciones deben tener lugar en la conversación del anuncio. Si la propuesta está en un documento de Google, se pueden usar los comentarios en su lugar (ten en cuenta que se permiten los comentarios anónimos).

Actualizar el estado

Crea una nueva solicitud de extracción para actualizar el estado de la propuesta cuando se complete la iteración. Envíe el área de Relaciones Públicas al mismo revisor principal y agregue en Cc a los demás revisores.

Para aceptar oficialmente la propuesta, el revisor principal aprueba el proceso de Relaciones Públicas luego 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 una prueba de concepto o una experimentación. Sin embargo, no puedes enviar el cambio antes de que se complete la revisión.

Elegir un revisor de clientes potenciales

Los revisores principales deben ser expertos en dominios con las siguientes características:

  • Conozco los subsistemas relevantes
  • Objetivo y capaz de brindar comentarios constructivos
  • Disponible para todo el período de revisión a fin de liderar el proceso

Considera buscar contactos en las diversas etiquetas de equipo.

Diferencias entre Markdown y Documentos de Google

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

Beneficios de usar Google Docs:

  • Efectiva para el intercambio de ideas, ya que es fácil comenzar
  • Edición colaborativa.
  • Iteración rápida.
  • Es una manera fácil de sugerir modificaciones.

Beneficios de usar los archivos de Markdown:

  • URL claras para la vinculación.
  • Registro explícito de las revisiones.
  • Olvídate de configurar los derechos de acceso antes de publicar un vínculo.
  • Se pueden 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 una conexión a Internet.
  • Es posible actualizarlas incluso si el autor ya no existe.
  • Pueden procesarse automáticamente (actualizar o detectar vínculos inactivos, recuperar una lista de autores, etcétera).

Puedes elegir iterar primero en un documento de Google y, luego, convertirlo a Markdown para la posteridad.

Uso de Google Docs

Para mantener la 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 haz clic en este vínculo a fin de crear una copia de la plantilla de documento de diseño.

Para que tu documento sea legible para todo el mundo, haz clic en Compartir > Avanzado > Cambiar... y elige “Activado: cualquier usuario con el vínculo”. Si permites los comentarios en el documento, cualquier persona puede 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 documentos deben revisar los cambios significativos. Cualquiera puede aprobar los cambios triviales (como los errores tipográficos o 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. Mire el documento rápidamente.
  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 RR.PP. cuando esté listo para la revisión.

Durante el proceso de revisión

  1. Participar en el diálogo con el autor del diseño sobre los problemas que sean problemáticos o que requieran aclaración
  2. Si corresponde, invita a los usuarios que no hayan revisado el contenido a publicar comentarios que deban tener en cuenta el diseño.
  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 avanzar o no avanzar en la implementación de un diseño pendiente. Si no puedes hacerlo, debes identificar a un delegado adecuado (reasignar el departamento de Relaciones Públicas al delegado) o reasignar el error a un administrador de Bazel para que lo deseche.

Durante el proceso de revisión

  1. Asegúrate de que el proceso de iteración de comentario 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 en la lista de distribución.
  2. Asegúrese de que el departamento de Relaciones Pública actualice el estado.
  3. Aprobar el PR enviado por el autor de la propuesta

Rechazo de diseños

  1. Asegúrate de que el autor de Relaciones Públicas envíe un mensaje público o
  2. El PR actualiza el estado del documento.
  3. Agrega un comentario al documento en el que expliques por qué el diseño no se puede aprobar en su estado actual y describe los pasos siguientes, si los hay (como "reanudar suposiciones no válidas y volver a enviarlas").