Este documento é destinado a colaboradores do Bazel.
As descrições de commit no Bazel incluem uma tag RELNOTES: seguida de uma nota
da versão. Usado pela equipe do Bazel para acompanhar as mudanças em cada versão e escrever
o anúncio da versão.
Visão geral
Sua mudança é uma correção de bug? Nesse caso, não é necessário ter uma nota da versão. Inclua uma referência ao problema do GitHub.
Se a mudança adicionar, remover ou alterar o Bazel de uma forma visível para o usuário, pode ser vantajoso mencionar isso.
Se a mudança for significativa, siga primeiro a política de documentos de design.
Diretrizes
As notas da versão serão lidas pelos nossos usuários. Por isso, elas precisam ser curtas (idealmente uma frase), evitar jargões (terminologia interna do Bazel) e se concentrar no que a mudança representa.
Inclua um link para a documentação relevante. Quase todas as notas da versão precisam ter 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 descrições de bugs. Elas costumam ser enigmáticas e só fazem sentido para nós, deixando o usuário confuso. As notas da versão explicam o que mudou e por quê em uma linguagem que os usuários entendem.
Sempre use o tempo presente e o formato "O Bazel agora é compatível com Y" ou "X agora faz Z". Não queremos que nossas notas da versão pareçam entradas de bugs. Todas as entradas das notas de versão precisam ser informativas e usar um estilo e uma linguagem consistentes.
Se algo foi descontinuado ou removido, use "X foi descontinuado" ou "X foi removido". Não use "foi removido" ou "será removido".
Se o Bazel fizer algo diferente, 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 ou não oferece mais suporte a algo, use "O Bazel agora oferece/não oferece mais suporte a X".
Explique por que algo foi removido, descontinuado ou mudou. Uma frase é suficiente, mas queremos que o usuário possa avaliar o impacto nos builds.
NÃO faça promessas sobre funcionalidades futuras. Evite frases como "esta flag será removida" ou "isso será mudado". Ela introduz incerteza. A primeira coisa que o usuário vai se perguntar é "quando?", e não queremos que ele comece a se preocupar com a quebra das builds atuais em algum momento desconhecido.
Processo
Como parte do processo de
lançamento,
coletamos as tags RELNOTES de cada commit. Copiamos tudo para um Documento Google, 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.
Depois, o anúncio será enviado ao blog do Bazel (link em inglês), usando o repositório bazel-blog (link em inglês).