Si planeas agregar, cambiar o quitar una función visible para el usuario, o realizar un cambio arquitectónico significativo en Bazel, debes escribir un documento de diseño y hacer que se revise antes de enviar el cambio.
Estos son algunos ejemplos de cambios significativos:
- Se agregaron o borraron 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 APIs que usa Bazel para conectarse a otros sistemas
- Cambios en el lenguaje, la semántica o las APIs de Starlark
- Cambios que podrían tener un efecto generalizado en el rendimiento o el uso de memoria de Bazel (para mejor o para peor)
- Cambios en las APIs internas de uso generalizado
- Se realizaron cambios en las marcas y en la interfaz de línea de comandos.
Motivos para realizar revisiones de diseño
Cuando escribes un documento de diseño, puedes coordinarte con otros desarrolladores de Bazel y buscar orientación del equipo principal de Bazel. Por ejemplo, cuando una propuesta agrega, quita o modifica cualquier función u objeto disponible en los archivos BUILD, MODULE.bazel o bzl, agrega al equipo de Starlark como revisor. Los documentos de diseño se revisan antes de enviarse por los siguientes motivos:
- Bazel es un sistema muy complejo; los cambios locales que parecen inocuos pueden tener consecuencias globales significativas.
- El equipo recibe muchas solicitudes de funciones de los usuarios, y estas solicitudes deben evaluarse no solo en cuanto a la viabilidad técnica, sino también en cuanto a la importancia en relación con otras solicitudes de funciones.
- Las funciones de Bazel suelen ser implementadas por personas ajenas al equipo principal, y estos colaboradores tienen niveles de experiencia en Bazel muy diferentes.
- El equipo de Bazel tiene diferentes niveles de experiencia; ningún miembro del equipo tiene una comprensión completa de cada rincón 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 se someten a un nivel de análisis básico.
- Las personas adecuadas opinarán sobre los diseños antes de que invirtamos en una implementación que podría no funcionar.
Para ayudarte a comenzar, consulta los documentos de diseño en el repositorio de propuestas de Bazel. Los diseños son trabajos en curso, por lo que los detalles de 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 continuos a medida que se implementan los diseños. Siempre consulta la documentación para obtener descripciones de la funcionalidad actual de Bazel.
Flujo de trabajo del colaborador
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 un (y solo un) revisor principal
- Estado actual (borrador, en revisión, aprobado, rechazado, en implementación, implementado)
- Vínculo al hilo de debate (se agregará después del anuncio)
El documento se puede escribir como un documento de Google legible para todo el mundo o con Markdown. A continuación, puedes leer una comparación entre Markdown y Documentos de Google.
Las propuestas que tengan un impacto visible para el usuario deben tener una sección en la que se documente el impacto en la retrocompatibilidad (y un plan de lanzamiento, si es necesario).
Crea una solicitud de extracción
Comparte tu documento de diseño creando una solicitud de extracción (PR) para agregar el documento al índice de diseño. Agrega tu archivo de Markdown o un vínculo al documento en tu PR.
Cuando sea posible, elige un revisor principal y agrega a otros revisores en copia. Si no eliges un revisor principal, un mantenedor de Bazel asignará uno a tu PR.
Después de crear tu PR, los revisores pueden hacer comentarios preliminares durante la revisión de código. Por ejemplo, el revisor principal puede sugerir revisores adicionales o señalar la falta de información. El revisor principal aprueba la RP cuando cree que puede comenzar el proceso de revisión. Esto no significa que la propuesta sea perfecta o que se aprobará, sino que contiene suficiente información para iniciar el debate.
Anuncia la nueva propuesta
Envía un anuncio a bazel-dev cuando se envíe la PR.
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 tu propuesta. Intenta responder preguntas, aclarar la propuesta y abordar las inquietudes.
El debate debe realizarse en el hilo del anuncio. Si la propuesta está en un documento de Google, se pueden usar comentarios (ten en cuenta que se permiten los comentarios anónimos).
Actualiza el estado
Crea una nueva solicitud de extracción para actualizar el estado de la propuesta cuando se complete la iteración. Envía la PR al mismo revisor principal y agrega a los demás revisores en copia.
Para aceptar oficialmente la propuesta, el revisor principal aprueba la PR 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 expresar 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 un revisor principal
Un revisor principal debe ser un experto en el dominio que cumpla con los siguientes requisitos:
- Conocimiento de los subsistemas pertinentes
- Objetivo y capaz de proporcionar comentarios constructivos
- Estar disponible durante todo el período de revisión para dirigir el proceso
Considera consultar los contactos de varias etiquetas de equipo.
Markdown vs. Documentos de Google
Decide qué opción te conviene más, ya que se aceptan ambas.
Beneficios de usar Documentos de Google:
- Es eficaz para intercambiar ideas, ya que es fácil comenzar a usarla.
- Edición colaborativa
- Iteración rápida
- Es una forma sencilla de sugerir cambios.
Beneficios de usar archivos Markdown:
- URLs limpias para la vinculación.
- Registro explícito de las revisiones
- No olvidarás configurar los derechos de acceso antes de publicar un vínculo.
- Se pueden buscar fácilmente con motores de búsqueda.
- A prueba del futuro: El texto sin formato no depende de ninguna herramienta específica y no requiere una conexión a Internet.
- Es posible actualizarlos incluso si el autor ya no está.
- Se pueden procesar automáticamente (actualizar o detectar vínculos rotos, recuperar la lista de autores, etc.).
Puedes optar por iterar primero en un documento de Google y, luego, convertirlo a Markdown para el futuro.
Cómo usar Documentos de Google
Para mantener la coherencia, usa la plantilla de documento 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 del documento de diseño.
Para que tu documento sea legible para todo el mundo, haz clic en Compartir > Configuración avanzada > Cambiar… y elige "Activado: Cualquier usuario con el vínculo". Si permites comentarios en el 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 el formato de GitHub de Markdown (especificación).
Crea una solicitud de extracción para actualizar un documento existente. Los revisores de documentos deben revisar los cambios significativos. Cualquier persona puede aprobar los cambios triviales (como errores tipográficos o de formato).
Flujo de trabajo del revisor
Un revisor comenta, revisa y aprueba los documentos de diseño.
Responsabilidades generales de los revisores
Eres responsable de revisar los documentos de diseño, solicitar información adicional si es necesario y aprobar un diseño que supere el proceso de revisión.
Cuando recibes una propuesta nueva
- Echa un vistazo rápido al documento.
- Comenta si falta información importante o si el diseño no se ajusta a los objetivos del proyecto.
- Sugerir revisores adicionales
- Aprueba la PR cuando esté lista para su revisión.
Durante el proceso de revisión
- Participar en un diálogo con el autor del diseño sobre los problemas que son problemáticos o requieren aclaración
- Si corresponde, invita a comentar a personas que no sean revisores, pero que deban conocer el diseño.
- Decide qué comentarios debe abordar el autor como requisito previo para la aprobación.
- Escribe "LGTM" (Looks Good To Me) en el hilo de discusión cuando estés conforme 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 del revisor principal
Eres responsable de tomar la decisión de implementar o no un diseño pendiente. Si no puedes hacerlo, debes identificar a un delegado adecuado (reasignar la PR al delegado) o reasignar el error a un administrador de Bazel para que tome una decisión.
Durante el proceso de revisión
- Asegúrate de que el proceso de comentarios y de iteración del diseño avance de forma constructiva.
- 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
- Asegúrate de que haya transcurrido al menos 1 semana desde el anuncio en la lista de distribución.
- Asegúrate de que la solicitud de extracción actualice el estado.
- Aprueba la PR que envió el autor de la propuesta.
Rechazar diseños
- Asegúrate de que el autor de la PR envíe una PR o envíale una.
- La PR actualiza el estado del documento.
- Agrega un comentario al documento en el que se explique por qué no se puede aprobar el diseño en su estado actual y se describan los próximos pasos, si los hay (por ejemplo, "revisa las suposiciones no válidas y vuelve a enviar el diseño").