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 usa esta información 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. Por favor, incluir 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, sigue el documento de diseño política primero.
Lineamientos
Los usuarios leerán las notas de la versión, por lo que deben ser breves (idealmente, una oración), evita la jerga (terminología interna de Bazel), debes centrarte en lo que se trata el cambio.
Incluye un vínculo a la documentación relevante. Casi todas las notas de la versión deben contienen 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 te limites a copiar y pegar descripciones de errores. A menudo son crípticos y solo tienen sentido para nosotros y dejar al usuario rascándose la cabeza. Las notas de la versión son para explicar qué cambió y por qué con 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 versiones las entradas de nota deben ser informativas y deben tener un estilo y un lenguaje coherentes.
Si algún elemento se quitó o dejó de estar disponible, usa "X se dio de baja". o "X se ha eliminado". No se debe usar "se quita" o "se quitó".
Si Bazel ahora hace algo de forma diferente, usa "X ahora $newBehavior en lugar de $oldBehavior" en tiempo presente. Esto le permite al usuario saber en detalle qué qué esperar cuando usen el nuevo lanzamiento.
Si Bazel ahora admite o ya no admite algo, usa "Bazel ahora admite/ya no admite X".
Explica por qué algo se quitó, dejó de estar disponible o cambió. Una oración es pero queremos que el usuario pueda evaluar el impacto en sus construcciones.
NO hagas promesas sobre funciones futuras. Evita usar expresiones como "se quitará esta marca" o "se cambiará esto". Genera incertidumbre. Lo primero el usuario se preguntará "¿cuándo?" y no queremos que empiecen a preocuparse por y sus compilaciones actuales fallan en un momento desconocido.
Proceso
Como parte del lanzamiento
,
recopilamos las etiquetas RELNOTES de cada confirmación. Copiamos todo en una página
Documento
para revisar, editar y organizar 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 en el documento y asegurarse de que 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.