Este documento está dirigido a los colaboradores de Bazel.
Las descripciones de confirmación en Bazel incluyen una etiqueta RELNOTES: seguida de una nota de la
versión. El equipo de Bazel usa esta información para hacer un seguimiento de los cambios en cada versión y escribir el anuncio de lanzamiento.
Descripción general
¿El cambio es una corrección de errores? En ese caso, no necesitas una nota de la versión. Incluye una referencia al problema de GitHub.
Si el cambio agrega, quita o cambia Bazel de una manera visible para el usuario, puede ser beneficioso mencionarlo.
Si el cambio es significativo, primero sigue la política de documentos de diseño.
Lineamientos
Los usuarios leerán las notas de la versión, por lo que deben ser breves (idealmente una oración), evitar la jerga (terminología interna de Bazel) y centrarse en el tema del cambio.
Incluye un vínculo a la documentación relevante. Casi todas las notas de la versión deben contener un vínculo. Si la descripción menciona una marca, una función y un nombre de comando, es probable que los usuarios quieran saber más al respecto.
Usa comillas inversas en código, símbolos, marcas o cualquier palabra que contenga un guion bajo.
No te limites a copiar y pegar descripciones de errores. A menudo son crípticos, solo tienen sentido para nosotros y dejan al usuario rascándose la cabeza. Las notas de la versión están diseñadas para explicar qué cambió y por qué en un lenguaje comprensible para el usuario.
Usa siempre el presente y el formato “Bazel ahora admite Y” o “X ahora incluye Z”. No queremos que nuestras notas de la versión suenen como entradas de errores. Todas las entradas de notas de la versión deben ser informativas y deben usar un lenguaje y un estilo coherentes.
Si algo dejó de estar disponible o se quitó, usa "X dejó de estar disponible" o "X se quitó". No "se quitó" ni "se quitó".
Si Bazel hace algo diferente ahora, usa "X now $newBehavior en lugar de $oldBehavior" en tiempo presente. Esto le permite al usuario saber en detalle qué esperar cuando use la versión nueva.
Si Bazel ahora admite o ya no admite algo, usa “Bazel ahora admite o ya no admite X”.
Explica por qué algo se quitó, dejó de estar disponible o cambió. Una oración es suficiente, pero queremos que el usuario pueda evaluar el impacto en sus compilaciones.
NO hagas promesas sobre funcionalidades futuras. Evita "esta marca se quitará" o "esto se cambiará". Genera incertidumbre. Lo primero que el usuario se preguntará es “¿cuándo?”, y no queremos que comiencen a preocuparse por la falla de sus compilaciones actuales en un momento desconocido.
Procesos
Como parte del proceso de lanzamiento, recopilamos las etiquetas RELNOTES de cada confirmación. Copiamos todo en un Documento de Google en el que revisamos, editamos y organizamos las notas.
El administrador de versiones envía un correo electrónico a la lista de distribución de bazel-dev. Se invita a los colaboradores de Bazel a contribuir en el documento y asegurarse de que sus cambios se reflejen correctamente en el anuncio.
Más adelante, el anuncio se enviará al blog de Bazel con el repositorio de bazel-blog.