Este documento é destinado aos colaboradores do Bazel.
As descrições de confirmação no Bazel incluem uma tag RELNOTES: seguida por uma nota
de lançamento. Isso é usado pela equipe do Bazel para acompanhar as mudanças em cada versão e escrever
o anúncio de lançamento.
Visão geral
A mudança é uma correção de bug? Nesse caso, você não precisa de uma nota de lançamento. Inclua uma referência ao problema do GitHub.
Se a mudança adicionar / remover / alterar o Bazel de uma forma visível para o usuário, pode ser vantajoso mencioná-la.
Se a mudança for significativa, siga a política do documento de design primeiro.
Diretrizes
As notas da versão serão lidas pelos nossos usuários. Por isso, elas precisam ser curtas (de preferência, uma frase), evitar jargões (terminologia interna do Bazel) e se concentrar no que a mudança significa.
Inclua um link para a documentação relevante. Quase todas as notas de versão precisam conter um link. Se a descrição mencionar uma flag, um recurso ou um nome de comando, os usuários provavelmente vão querer saber mais sobre isso.
Use acentos graves em torno de código, símbolos, flags ou qualquer palavra que contenha um sublinhado.
Não copie e cole as descrições dos bugs. Muitas vezes, elas são enigmáticas e só fazem sentido para nós, deixando o usuário confuso. As notas da versão têm o objetivo de explicar o que mudou e por que isso aconteceu em um idioma que o usuário possa entender.
Sempre use o tempo presente e o formato "Bazel agora oferece suporte a Y" ou "X agora faz Z". Não queremos que as notas da versão pareçam entradas de bugs. Todas as entradas de notas de lançamento precisam ser informativas e usar um estilo e linguagem consistentes.
Se algo foi descontinuado ou removido, use "X foi descontinuado" ou "X foi removido". Não use "is removed" ou "was removed".
Se o Bazel fizer algo diferente agora, use "X agora $newBehavior em vez de $oldBehavior" no tempo 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 faça promessas sobre funcionalidades futuras. Evite "esta flag será removida" ou "esta será alterada". Isso gera incerteza. A primeira coisa que o usuário vai se perguntar é "quando?", e não queremos que ele comece a se preocupar com o fato de que os builds atuais vão falhar em algum momento desconhecido.
Processo
Como parte do processo
de lançamento,
coletamos as tags RELNOTES de cada confirmação. Copiamos tudo em um Documento
Google
para revisar, editar e organizar as anotações.
O gerente de lançamento 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 anúncio.
Mais tarde, o anúncio será enviado ao blog do Bazel, usando o repositório bazel-blog.