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 lanzamiento. El equipo de Bazel lo usa para hacer un seguimiento de los cambios en cada versión y escribir
el anuncio de lanzamiento.
Descripción general
¿Tu 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 conveniente mencionarlo.
Si el cambio es significativo, primero sigue la política del documento de diseño.
Lineamientos
Nuestros usuarios leerán las notas de la versión, por lo que deben ser breves (idealmente, una oración), evitar el lenguaje técnico (terminología interna de Bazel) y deben enfocarse en el tema del cambio.
Incluye un vínculo a la documentación relevante. Casi cualquier nota de lanzamiento debe contener un vínculo. Si la descripción menciona una marca, una función o un nombre de comando, es probable que los usuarios quieran saber más al respecto.
Usa acentos graves alrededor del código, los símbolos, las marcas o cualquier palabra que contenga un guion bajo.
No solo copies y pegues las descripciones de los errores. A menudo, son crípticos y solo tienen sentido para nosotros, lo que deja al usuario con la cabeza en la mano. Las notas de la versión se usan para explicar qué cambió y por qué en un lenguaje comprensible para los usuarios.
Usa siempre el tiempo presente y el formato "Bazel ahora admite Y" o "X ahora hace Z". No queremos que nuestras notas de la versión suenen como entradas de errores. Todas las entradas de las notas de lanzamiento deben ser informativas y usar un estilo y un lenguaje coherentes.
Si se da de baja o se quita algo, usa "X se dio de baja" o "X se quitó". No se debe usar "se quita" o "se quitó".
Si Bazel ahora hace algo de manera diferente, usa "X ahora $newBehavior en lugar de $oldBehavior" en tiempo presente. Esto le permite al usuario saber en detalle qué puede esperar cuando usa la nueva versión.
Si Bazel ahora admite o ya no admite algo, usa "Bazel ahora admite/ya no admite X".
Explica por qué se quitó, dejó de estar disponible o se cambió algo. Una oración es suficiente, pero queremos que el usuario pueda evaluar el impacto en sus compilaciones.
NO hagas promesas sobre funciones futuras. Evita usar expresiones como "se quitará esta marca" o "se cambiará esto". Genera incertidumbre. Lo primero que se preguntará el usuario es "¿cuándo?", y no queremos que empiece a preocuparse por que sus compilaciones actuales fallen en algún momento desconocido.
Proceso
Como parte del proceso de lanzamiento, recopilamos las etiquetas RELNOTES de cada confirmación. Copiamos todo en un Documento de Google, donde revisamos, editamos y organizamos las notas.
El administrador de lanzamientos envía un correo electrónico a la lista de distribución bazel-dev. Se invita a los colaboradores de Bazel a contribuir con 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 bazel-blog.