Este documento é destinado aos colaboradores do Bazel.
As descrições de commit no Bazel incluem uma tag RELNOTES: seguida por uma versão.
observação Ela é usada pela equipe do Bazel para rastrear alterações em cada versão e gravar
o anúncio do lançamento.
Visão geral
Sua mudança é uma correção de bug? Nesse caso, você não precisa de uma nota de lançamento. Não se esqueça incluem uma referência ao problema no GitHub.
Se a mudança adicionar / remover / mudar o Bazel de forma visível para o usuário, pode ser vantajoso mencioná-lo.
Se a mudança for significativa, siga o documento de design política.
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 devem conter um link. Se a descrição mencionar uma flag, um recurso, um nome de comando, os usuários provavelmente vão querer saber mais sobre ele.
Use aspas em torno de códigos, símbolos, sinalizações ou qualquer palavra que contenha 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 "foi removido" ou "foi removido".
Se o Bazel fizer algo diferente, use "X now $newBehavior" em vez de $oldBehavior" no presente. Isso permite que o usuário saiba em detalhes o que 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 é o suficiente, mas queremos que o usuário seja capaz de avaliar o impacto em seus builds.
NÃO faça promessas sobre funcionalidades futuras. Evite "esta flag será removida" ou "esta será alterada". Ele gera incerteza. A primeira coisa o usuário perguntará: "quando?" e não queremos que eles comecem a se preocupar os builds atuais falham em um momento desconhecido.
Processo
Como parte do processo
de lançamento,
coletamos as tags RELNOTES de cada confirmação. Nós copiamos tudo de um Google
Documento
onde revisamos, editamos e organizamos 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 Bazel blog, usando a bazel-blog repositório.