Este documento é destinado aos colaboradores do Bazel.
As descrições de commit no Bazel incluem uma tag RELNOTES: seguida por uma nota de versão. Ela é usada pela equipe do Bazel para rastrear alterações 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, a nota da versão não é necessária. Inclua 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á-la.
Se a mudança for significativa, siga a política de documento de design primeiro.
Diretrizes
As notas da versão serão lidas pelos usuários, portanto, devem ser curtas (de preferência uma frase), evitar jargões (terminologia interna do Bazel) e se concentrar no que é a 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 ele.
Use aspas em torno do código, 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 misteriosas 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 por que, em uma linguagem compreensível ao usuário.
Sempre use o presente e o formato "Bazel agora aceita Y" ou "X agora faz Z". Não queremos que as notas da versão pareçam entradas de bugs. Todas as entradas da nota da versão precisam 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 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 passar a oferecer suporte ou não a mais algo, use "O Bazel agora oferece suporte ou não oferece mais suporte a X".
Explique por que algo foi removido / descontinuado / alterado. Uma frase é suficiente, mas queremos que o usuário seja capaz de avaliar o impacto nos builds.
NÃO faça promessas sobre funcionalidades futuras. Evite "esta sinalização será removida" ou "isso será alterado". Ele gera incerteza. A primeira coisa que o usuário vai se perguntar é "quando?" e não queremos que ele comece a se preocupar com a falha dos builds atuais em um momento desconhecido.
Processo
Como parte do processo de lançamento, coletamos as tags RELNOTES de cada confirmação. Copiamos tudo em um Documentos Google
em que 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 para o documento e garantir que as mudanças sejam refletidas corretamente no anúncio.
Posteriormente, o anúncio será enviado para o blog do Bazel por meio do repositório do bazel-blog (links em inglês).