Este documento é voltado aos colaboradores do Bazel.
As descrições de confirmações no Bazel incluem uma tag RELNOTES: seguida por uma nota de
versão. Ele é usado pela equipe do Bazel para rastrear as mudanças em cada versão e escrever
o anúncio de lançamento.
Informações gerais
Sua mudança foi uma correção de bug? Nesse caso, você não precisa de uma nota da versão. Inclua uma referência ao problema do GitHub.
Se a mudança adicionar, remover ou alterar o Bazel de forma visível para o usuário, pode ser vantajoso mencionar isso.
Se a mudança for significativa, siga primeiro a política do documento de design.
Diretrizes
As notas da versão serão lidas pelos usuários. Portanto, precisam ser curtas (o ideal é uma frase), evitar jargões (terminologia interna do Bazel e se concentrar no motivo da mudança).
Inclua um link para a documentação relevante. Quase todas as notas de versão devem conter um link. Se a descrição mencionar uma sinalização, um recurso ou um nome de comando, os usuários provavelmente vão querer saber mais sobre isso.
Use aspas de entrada ao redor de códigos, símbolos, sinalizações ou qualquer palavra que contenha um sublinhado.
Não basta copiar e colar descrições de bugs. Muitas vezes, elas são enigmáticas e só fazem sentido para nós e deixam o usuário coçando a cabeça. As notas da versão servem para explicar o que mudou e o porquê em uma linguagem compreensível para o usuário.
Sempre use o presente e o formato "O Bazel agora é compatível com Y" ou "X agora faz Z". Não queremos que as notas da versão pareçam entradas de bug. Todas as entradas de notas de lançamento precisam ser informativas e usar um estilo e linguagem consistentes.
Se algum item foi descontinuado ou removido, use "X foi descontinuado" ou "X foi removido". Não "foi removido" ou "foi removido".
Se o Bazel agora fizer algo diferente, use "X now $newBehavior em vez de $oldBehavior" no presente. Isso permite que o usuário saiba em detalhes o que esperar ao usar a nova versão.
Se o Bazel agora oferece suporte ou não oferece mais suporte a algo, use "O Bazel agora oferece suporte / não oferece mais suporte a X".
Explique por que algo foi removido / descontinuado / alterado. Uma frase é suficiente, mas queremos que o usuário possa avaliar o impacto nos builds.
NÃO prometa funcionalidades futuras. Evite "esta sinalização será removida" ou "isso será alterado". Ela introduz incerteza. A primeira coisa que o usuário vai se perguntar é "quando?" e não queremos que ele comece a se preocupar com falhas nos builds em um momento desconhecido.
Processo
Como parte do processo
de lançamento,
coletamos as tags RELNOTES de cada confirmação. Copiamos tudo em um Documento Google, onde revisamos, editamos e organizamos as anotações.
O gerenciador de versões envia um e-mail para a lista de e-mails bazel-dev. Os colaboradores do Bazel são convidados a contribuir com o documento e garantir que as mudanças sejam refletidas corretamente no aviso.
Mais tarde, o anúncio será enviado ao blog Bazel usando o repositório bazel-blog (links em inglês).