Si planeas agregar, cambiar o quitar una función para el usuario, o realizar un cambio arquitectónico significativo en Bazel, debes escribir un documento de diseño y enviarlo para su revisión antes de enviar el cambio.
A continuación, presentamos algunos ejemplos de cambios significativos:
- Adición o eliminación de reglas de compilación nativas
- Cambios rotundos en 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 de Bazel o el uso de memoria (para bien o para mal)
- Cambios en las APIs internas más usadas
- Cambios en las marcas y la interfaz de línea de comandos
Razones para 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 principal de Bazel. Por ejemplo, cuando una propuesta agrega, quita o modifica cualquier función o objeto disponible en archivos BUILD, WORKSPACE o bzl, agrega al equipo de Starlark como revisores. Los documentos de diseño se revisan antes del envío 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. Dichas solicitudes deben evaluarse no solo por su viabilidad técnica, sino también por su importancia en relación con otras solicitudes de funciones.
- Con frecuencia, personas ajenas al equipo principal implementan las funciones de Bazel, que tienen niveles muy diferentes de experiencia en Bazel.
- El equipo de Bazel tiene diversos 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 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 atributos obtienen un nivel de análisis de referencia.
- las personas adecuadas evaluarán los diseños antes de invertir 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 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 continuos 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.
Escribir el documento de diseño
Todos los documentos de diseño deben tener un encabezado que incluya:
- author
- fecha del último cambio importante
- lista de revisores, incluido uno (y solo uno) revisor principal
- estado actual (borrador, en revisión, aprobado, rechazado, en proceso de implementación, implementado)
- vínculo a la conversación (se agregará después del anuncio)
El documento se puede redactar como un documento de Google legible en todo el mundo o con Markdown. A continuación, encontrarás información sobre una comparación entre Markdown y Documentos de Google.
Las propuestas que tienen un impacto visible para el usuario deben incluir una sección que 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 de documento a tu RP.
Cuando sea posible, elige a un revisor principal y agrega en el campo Cc a otros revisores. Si no eliges un revisor principal, un encargado de mantenimiento de Bazel asignará uno a tu RR.PP.
Después de crear tu solicitud de extracción, los revisores pueden hacer comentarios preliminares durante la revisión del código. Por ejemplo, el revisor principal puede sugerir revisores adicionales o señalar que falta información. El revisor principal aprueba el informe de RR.PP. cuando considera que el proceso de revisión puede comenzar. Esto no significa que la propuesta sea perfecta o que se apruebe; significa que contiene suficiente información para comenzar el debate.
Anunciar 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-discuss, para obtener comentarios de los usuarios finales de Bazel).
Cómo iterar con los revisores
Cualquier persona interesada puede comentar su propuesta. Intenta responder preguntas, aclarar la propuesta y abordar inquietudes.
El debate debe realizarse en la conversación del anuncio. Si la propuesta está en un documento de Google, se pueden usar comentarios en su lugar (ten en cuenta que se permiten comentarios anónimos).
Actualiza el estado
Crea una solicitud de extracción nueva para actualizar el estado de la propuesta, cuando se complete la iteración. Envía el RR.PP. al mismo revisor principal y agrega en el campo Cc a los demás revisores.
Para aceptar oficialmente la propuesta, el revisor principal aprueba la solicitud de Relaciones Públicas 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 hayan tenido 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 un revisor principal
Un revisor líder debe ser un experto en el dominio que cumpla con los siguientes requisitos:
- Conocer los subsistemas relevantes
- Objetivo y ser capaz de proporcionar comentarios constructivos.
- Disponible durante todo el período de revisión para que lidere el proceso
Considera revisar los contactos en busca de varias etiquetas de equipo.
Markdown vs. Google Docs
Decide qué funciona mejor para ti, ya que se aceptan ambos.
Beneficios de usar Documentos de Google:
- Es eficaz para el intercambio de ideas, ya que es fácil comenzar.
- Edición colaborativa.
- Iteración rápida.
- Es una forma sencilla de sugerir cambios.
Beneficios de usar archivos de Markdown:
- Limpiar URLs para la vinculación
- Registro explícito de las revisiones
- No olvides configurar los derechos de acceso antes de publicar un vínculo.
- Se pueden buscar fácilmente con 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 está presente.
- Se pueden procesar automáticamente (actualizar o detectar vínculos inactivos, recuperar lista de autores, etc.).
Puedes optar por iterar primero en un documento de Google y, luego, convertirlo a Markdown para la posteridad.
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 File > Make a copy o haz clic en este vínculo para hacer una copia de la plantilla de documentos de diseño.
Para que todo el mundo pueda leer el documento, haz clic en Compartir > Avanzado > Cambiar... y selecciona “Activado: Cualquier persona con el vínculo”. Si permites que se hagan 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 Markdown de GitHub (Especificación).
Crea una solicitud de eliminación para actualizar un documento existente. Los revisores del documento deben revisar los cambios significativos. Los cambios triviales (como errores tipográficos o de formato) pueden ser aprobados por cualquier persona.
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, solicitar información adicional si es necesario y aprobar un diseño que apruebe el proceso de revisión.
Cuando recibes una propuesta nueva
- Echa un vistazo rápido al documento.
- Comenta si falta información crítica o si el diseño no se ajusta a los objetivos del proyecto.
- Sugerir más revisores
- Aprueba el documento de relaciones públicas cuando esté listo para su revisión.
Durante el proceso de revisión
- Entabla un diálogo con el autor del diseño sobre los problemas que son problemáticos o que requieren aclaraciones.
- Si corresponde, invita a comentarios de personas que no son revisores que deberían conocer el diseño.
- Decide qué comentarios debe abordar el autor como requisito previo para la aprobación.
- Escribe "LGTM" (Se ve bien para mí) en la conversación de debate 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 del líder
Eres responsable de tomar la decisión de proceder o no sobre la implementación de un diseño pendiente. Si no puedes hacerlo, debes identificar un delegado adecuado (reasignar la PR al delegado) o reasignar el error a un administrador de Bazel para una mayor disposición.
Durante el proceso de revisión
- Asegúrate de que el proceso de iteración de diseño y comentarios avance de manera 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 el RR.PP. actualice el estado.
- Aprobar la solicitud de extracción enviada por el autor de la propuesta
Rechazar diseños
- Asegúrate de que el autor del comunicado de prensa envíe un comunicado de prensa o envíale uno.
- El RR.PP. actualiza el estado del documento.
- Agrega un comentario al documento en el que expliques por qué no se puede aprobar el diseño en su estado actual y que describa los próximos pasos, si los hubiera (como "volver a consultar las suposiciones no válidas y volver a enviarla").