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 redactar el anuncio de la versión.
Descripción general
¿El cambio que realizaste 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 modifica Bazel de una manera visible para el usuario, puede ser ventajoso mencionarlo.
Si el cambio es significativo, primero sigue la política de documentos 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 la jerga (terminología interna de Bazel) y centrarse en el cambio.
Incluye un vínculo a la documentación pertinente. 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 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, lo que deja al usuario perplejo. Las notas de la versión tienen como objetivo explicar qué cambió y por qué en un lenguaje que los usuarios puedan entender.
Siempre usa 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 la versión deben ser informativas y usar un estilo y un lenguaje coherentes.
Si algo dejó de estar disponible o se quitó, usa "X dejó de estar disponible" o "Se quitó X". No debe decir "se quitó" o "se quitó".
Si Bazel ahora hace algo diferente, usa "X ahora $newBehavior en lugar de $oldBehavior" en tiempo presente. Esto permite que el usuario sepa en detalle qué esperar cuando use 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 cambió algo. 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 usar frases como "Se quitará esta marca" o "Esto cambiará". Introduce incertidumbre. Lo primero que se preguntará el usuario es "¿cuándo?", y no queremos que se preocupe por que sus compilaciones actuales se interrumpan 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 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 que contribuyan con el documento y se aseguren 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.