Este documento é destinado a colaboradores do Bazel.
As descrições de confirmação no Bazel incluem uma tag RELNOTES: seguida por uma nota de versã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 bugs? Nesse caso, você não precisa de uma nota de 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 ao usuário, pode ser vantajoso mencioná-la.
Se a mudança for significativa, siga primeiro a política de documentos de design.
Diretrizes
As notas de versão serão lidas pelos nossos usuários. Portanto, 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 de versão precisam 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 ele.
Use acentos graves em torno de códigos, 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 de 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 faz Z". Não queremos que nossas notas de versão pareçam entradas de bugs. Todas as entradas de notas de versão 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 "é removido" ou "foi removido".
Se o Bazel agora faz algo de maneira 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 o novo lançamento.
Se o Bazel agora oferece suporte ou não oferece mais suporte a algo, use "O Bazel agora oferece suporte a / não oferece mais suporte a X".
Explique por que algo foi removido, descontinuado ou alterado. Uma frase é suficiente, mas queremos que o usuário possa avaliar o impacto nas builds.
NÃO faça promessas sobre funcionalidades futuras. Evite "essa flag será removida" ou "isso será alterado". Isso 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 lançamento
processo,
coletamos as tags RELNOTES de cada confirmação. Copiamos tudo em um Documentos
Google
onde revisamos, editamos e organizamos as notas.
O gerente de lançamento envia um e-mail para a bazel-dev lista de e-mails. 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.