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 lo usa para realizar un seguimiento de los cambios en cada versión y escribir
el anuncio de la versión.
Descripción general
¿Se corrigió el error? 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, podría ser beneficioso mencionarlo.
Si el cambio es significativo, primero sigue la política de documento de diseño.
Guías
Los usuarios leerán las notas de la versión, por lo que debe ser breve (idealmente una oración), evitar la jerga (terminología interna de Bazel), enfocarse en el tema.
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 o un nombre de comando, es probable que los usuarios quieran saber más sobre ella.
Usa comillas para indicar el código, los símbolos, las marcas o cualquier palabra que contenga un guion bajo.
No copies y pegues las descripciones de errores. Suelen ser crípticos y solo tienen sentido para nosotros y dejan al usuario rascándose la cabeza. Las notas de la versión deben explicar qué cambió y por qué en un lenguaje fácil de entender para los usuarios.
Usa siempre el tiempo presente y el formato “Bazel now support Y” o “X now does Z”. No queremos que nuestras notas de la versión suenen como entradas de error. Todas las entradas de las notas de la versión deben ser informativas y usar un estilo y un lenguaje coherentes.
Si algo quedó obsoleto o se quitó, usa "X quedó obsoleto" o "X se quitó". No "se quitó" o "se quitó".
Si Bazel ahora hace algo diferente, usa "X ahora $newBehavior", en lugar de $oldBehavior, en el presente. Esto le permite al usuario saber en detalle qué esperar cuando usa la versión nueva.
Si Bazel ahora admite o ya no admite algo, usa “Bazel now supported/o already longer X”.
Explica por qué algo se quitó, se dio de baja o se modificó. Una oración es suficiente, pero queremos que el usuario pueda evaluar el impacto en sus compilaciones.
NO hagas promesas sobre la funcionalidad futura. Evita "esta marca se quitará" o "esto se cambiará". Presenta incertidumbre. Lo primero que el usuario se preguntará es "cuándo" y no queremos que empiece a preocuparse por que sus compilaciones actuales dejen de funcionar en un momento desconocido.
Proceso
Como parte del proceso de actualización, 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 bazel-dev. Invitamos a los colaboradores de Bazel a que colaboren con el documento y se aseguren de que sus cambios se reflejen de forma correcta en el anuncio.
Más tarde, el anuncio se enviará al blog de Bazel mediante el repositorio de bazel-blog.