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 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
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/alterar o Bazel de uma forma visível para o usuário, pode ser vantajoso mencioná-la.
Se a mudança for significativa, siga o documento de design política.
Diretrizes
As notas da versão serão lidas pelos usuários e, por isso, devem ser curtas (de preferência uma frase), evite jargões (terminologia interna do Bazel), concentre-se no que de 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 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 nossas notas da versão pareçam entradas de bugs. Todas as versões as entradas de nota devem ser informativas e usar 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 tiver suporte ou não houver mais suporte para algo, use a opção "O Bazel agora tem suporte / não é mais compatível com 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 versões envia um e-mail ao bazel-dev (link em inglês). 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.