Este documento é direcionado a colaboradores do Bazel.
As descrições de confirmação no Bazel incluem uma tag RELNOTES: seguida por uma nota da versão. Ela é usada pela equipe do Bazel para rastrear as alterações em cada versão e escrever o anúncio da versão.
Visão geral
Sua alteração é 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 adiciona / remove / altera o Bazel de maneira visível para o usuário, pode ser vantajoso menciona-lo.
Se a mudança for significativa, siga a política de documentos de design primeiro.
Diretrizes
As notas da versão serão lidas pelos nossos usuários. Portanto, devem ser curtas (o ideal é uma frase), evitar jargões (terminologia interna do Bazel) e se concentrar no conteúdo da mudança.
Inclua um link para a documentação relevante. Quase todas as notas de lançamento precisam conter um link. Se a descrição mencionar uma sinalização, um recurso ou um nome de comando, é provável que os usuários queiram saber mais sobre ela.
Use aspas duplas ao redor do código, símbolos, sinalizações ou qualquer palavra que contenha um sublinhado.
Não copie e cole apenas as descrições de bugs. Geralmente, 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 por que, em uma linguagem compreensível para o usuário.
Sempre use o tempo presente e o formato "O Bazel agora oferece suporte a Y" ou "X agora oferece Z". Não queremos que nossas notas da versão pareçam entradas de bug. Todas as entradas de notas da versão precisam ser informativas e usar um estilo e linguagem consistentes.
Se algo tiver sido 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 tempo presente. Isso informa ao usuário em detalhes o que esperar ao usar a nova versão.
Se o Bazel for compatível ou não for mais compatível com algo, use "O Bazel agora oferece suporte/não é mais compatível com X".
Explique por que algo foi removido / descontinuado / alterado. Uma frase é suficiente, mas queremos que o usuário possa avaliar o impacto nas versões.
NÃO prometa sobre a funcionalidade futura. Evite "esta sinalização será removida" ou "isso será alterada". Isso gera incerteza. A primeira coisa que o usuário quer saber é "quando?" e não queremos que ele comece a se preocupar com acontecimentos atuais em versões desconhecidas.
Processo
Como parte do processo
de lançamento,
coletamos as tags RELNOTES de cada confirmação. Copiamos tudo em um Google
Doc onde revisamos, editamos e organizamos as anotações.
O gerente da versão envia um e-mail para a lista de e-mails bazel-dev. Os colaboradores do Bazel estão convidados a contribuir para o documento e garantir que as alterações sejam refletidas corretamente no anúncio.
Depois, o anúncio vai ser enviado ao blog do Bazel usando o repositório do blog do Bazel (em inglês).