Si planeas agregar, cambiar o quitar una función para el usuario, o crear una cambio significativo en la arquitectura de Bazel, debes escribir un diseño documento y revisarlo antes de 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 una regla de compilación nativa que afectan el comportamiento de más que una regla única
- 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 la memoria de Bazel (para bien o para mal)
- Cambios en las APIs internas más utilizadas
- 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 pedirle ayuda al equipo central de Bazel. Por ejemplo, cuando una propuesta agrega, quita o modifica cualquier función u objeto disponible en 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; cambios locales aparentemente inocuos pueden tener consecuencias globales importantes.
- El equipo recibe muchas solicitudes de funciones de los usuarios; estas solicitudes deben se evalúa no solo por su viabilidad técnica, sino también por importancia con respecto a otras solicitudes de funciones.
- Personas ajenas al equipo central suelen implementar funciones de Bazel. estos tienen niveles muy variables de experiencia en Bazel.
- El propio equipo de Bazel tiene diversos niveles de experiencia. ningún miembro del equipo comprende a fondo cada rincón de Bazel.
- Los cambios en Bazel deben tener en cuenta la retrocompatibilidad y evitar fallas cambios.
La política de revisión de diseño de Bazel ayuda a maximizar las probabilidades de que ocurra lo siguiente:
- Todas las solicitudes de atributos obtienen un nivel de escrutinio de referencia.
- las personas adecuadas opinarán sobre los diseños antes de invertir en un de implementación que podría no funcionar.
Para ayudarte a comenzar, echa un vistazo a los documentos de diseño en la 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. Ve siempre a la página de inicio de 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.
Escribir el documento de diseño
Todos los documentos de diseño deben tener un encabezado que incluya lo siguiente:
- author
- fecha de la última modificación importante
- lista de revisores, incluido uno (y solo uno) revisor principal
- estado actual (borrador, en revisión, aprobado, rechazado, implementados, implementados)
- vínculo a la conversación (se agregará después del anuncio)
El documento se puede escribir como un documento de Google legible en todo el mundo. o usando Markdown. Sigue leyendo para obtener información sobre un Comparación entre Markdown y Documentos de Google.
Las propuestas que tengan un impacto visible para el usuario deben tener una sección que documente la el impacto en la retrocompatibilidad (y en 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 a el índice de diseño. Agrega el archivo en Markdown o el vínculo del documento a tu comunicado de prensa.
Cuando sea posible, elige un revisor principal. y agrega en Cc a otros revisores. Si no eliges a un revisor principal, Bazel encargado de mantenimiento, asignará una a tu RR.PP.
Luego de crear tu RR.PP., 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 información faltante. El revisor principal aprueba el PR cuando cree que puede comenzar el proceso de revisión. Esto no significa que la propuesta sea perfecta o se aprobará; significa que la propuesta contiene suficiente información comenzar el debate.
Anunciar la nueva propuesta
Enviar un anuncio a bazel-dev cuando se envía la solicitud de extracción.
Puedes copiar otros grupos (por ejemplo, bazel-debate. para obtener comentarios de los usuarios finales de Bazel).
Iterar 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 la conversación del anuncio. Si la propuesta se encuentra en un documento de Google, se pueden usar comentarios (ten en cuenta que los comentarios anónimos se permitida).
Actualiza el estado
Crea un nuevo PR para actualizar el estado de la propuesta cuando se realice la iteración que se completó. Envía el PR al mismo revisor principal y agrega en Cc a los demás revisores.
Para aceptar oficialmente la propuesta, el revisor líder aprueba el RR.PP. después asegurándote 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 preocupaciones.
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 podrás enviar el cambio. antes de completar la revisión.
Cómo elegir un revisor principal
Un revisor principal debe ser un experto en dominios que cumpla con las siguientes características:
- Conoce los subsistemas relevantes.
- Objetivo y capaz de proporcionar comentarios constructivos
- Disponible durante todo el período de revisión para dirigir el proceso
Considera revisar los contactos de varios equipos etiquetas.
Markdown frente a Documentos de Google
Decide qué funciona mejor para ti, ya que se aceptan ambos.
Beneficios de usar Documentos de Google:
- Efectivo para la lluvia de ideas, ya que es fácil comenzar.
- Edición colaborativa.
- Iteración rápida.
- Es una forma sencilla de sugerir ediciones.
Beneficios de usar archivos de Markdown:
- Limpiar las URLs para la vinculación
- Registro explícito de revisiones.
- No olvides configurar los derechos de acceso antes de publicar un vínculo.
- Son fáciles de encontrar con los motores de búsqueda.
- Preparado para el futuro: El texto sin formato no está a merced de ninguna herramienta específica y no requiere conexión a Internet.
- Es posible actualizarlos incluso si el autor ya no está presente.
- Pueden procesarse automáticamente (actualizar o detectar vínculos no inactivos, recuperar lista de autores, etc.).
Puedes elegir primero iterar un documento de Google y, luego, convertirlo a Markdown para la posteridad.
Cómo usar Documentos de Google
Para lograr coherencia, usa la plantilla de documentos de diseño de Bazel. Incluye el encabezado necesario y crea imágenes coherencia con otros documentos relacionados con Bazel. Para ello, haz clic en Archivo > Crea una copia o haz clic en este vínculo para hacer una copia del documento de diseño. plantilla.
Para que todo el mundo pueda leer tu documento, haz clic en Compartir > Avanzado > Cambiar... elige "Activado: Cualquier usuario con el vínculo". Si permites 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 el Variación de Markdown de Markdown (Especificación).
Crea un PR para actualizar un documento existente. Los cambios significativos deben revisados por los revisores de documentos. Cambios triviales (como errores tipográficos o de formato) pueden ser aprobados por cualquiera.
Flujo de trabajo del revisor
Un revisor comenta, revisa y aprueba los documentos de diseño.
Responsabilidades del revisor general
Eres responsable de revisar los documentos de diseño, pedir información información 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 encaja con los objetivos del proyecto.
- Sugiere revisores adicionales.
- Aprueba el comunicado de prensa cuando esté listo para su revisión.
Durante el proceso de revisión
- Entablar un diálogo con el autor del diseño sobre temas problemáticos o requieren una aclaración.
- Si corresponde, invita a personas que no revisores tengan la siguiente información: el diseño.
- Decidir qué comentarios debe abordar el autor como requisito previo para aprobación.
- Escribe "LGTM" (Looks Good to Me) en la conversación de la conversación cuando conforme al estado actual de la propuesta.
Sigue este proceso para todas las solicitudes de revisión de diseño. No aprobar los diseños que afectan a Bazel si no están en el de diseño.
Responsabilidades del revisor principal
Es tu responsabilidad tomar la decisión de proceder o no proceder durante la implementación. de un diseño pendiente. Si no puedes hacerlo, debes identificar un delegado adecuado (reasigna el RR.PP. al delegado) o reasigna el error a un Administrador de Bazel para una mayor disposición.
Durante el proceso de revisión
- Asegurarse de que el proceso de iteración de comentarios y diseño avance constructivamente.
- Antes de la aprobación, asegúrate de que las inquietudes de otros revisores se hayan resuelto.
Luego 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 departamento de RR.PP. actualice el estado.
- Aprueba las solicitudes de prensa que envió el autor de la propuesta.
Rechazar diseños
- Asegurarse de que el autor de RR.PP. la envíe o enviarles un PR.
- El comunicado de prensa actualiza el estado del documento.
- Agrega un comentario al documento que explique por qué no se puede aprobar el diseño en su estado actual y que describa los próximos pasos, si los hubiera (como "revisión no válida, suposiciones y volver a enviarla").