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 Ela é usada pela equipe do Bazel para rastrear alterações em cada versão e gravar
o anúncio do lançamento.
Visão geral
Sua mudança é uma correção de bug? Nesse caso, a nota da versão não é necessária. Não se esqueça incluem 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á-lo.
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, um nome de comando, os usuários provavelmente vão querer saber mais sobre ele.
Use aspas em torno de códigos, símbolos, sinalizações ou qualquer palavra que contenha sublinhado.
Não basta copiar e colar descrições de bugs. Muitas vezes, elas são enigmáticas e só fazem sentido para nós e deixam o usuário coçar a cabeça. As notas da versão são explica o que mudou e o porquê com uma linguagem compreensível para o 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 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 passar a oferecer suporte ou não houver mais suporte para algo, use "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 "isso será alterado". 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 lançamento
processo,
coletamos as tags RELNOTES de cada commit. 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 para o documento e garantir que as alterações serão refletidas corretamente no comunicado.
Mais tarde, o anúncio será enviado ao Bazel blog, usando a bazel-blog repositório.