Ir para o conteúdo

Adicionar informações de alterações para as notas de lançamento

Muitas ferramentas do BeeWare utilizam o towncrier para auxiliar na criação das notas de lançamento de cada versão. Quando envia um pedido de puxar para uma das ferramentas aplicáveis, ele precisa de incluir uma nota de alteração - esta nota de alteração vai se tornar na entrada nas notas de lançamento que descrevem a alteração que foi feita.

Todo o pedido de puxar deve incluir pelo menos um ficheiro no diretório changes/ que forneça uma breve descrição da alteração implementada pelo pedido de puxar. A nota de alteração deve estar no formato Markdown, num ficheiro que tenha o nome no formato <id>.<fragment type>.md. Se a alteração que está a propor for corrigir um bug ou implementar uma funcionalidade para o qual há um número de problema existente, o ID deverá ser o número desse bilhete. Se a alteração não tiver um problema correspondente, o número do PR poderá ser usado como ID. Você não vai saber o número do PR até que envie o pedido, portanto, a primeira passagem do CI vai falhar na verificação do towncrier; adicione a nota de alteração e envie uma atualização do PR e o CI deverá ser aprovado.

Há cinco tipos de fragmentos:

  • feature: O PR adiciona um novo comportamento ou capacidade que não era possível anteriormente (ex., adicionar suporte a um novo formato de empacotamento ou uma nova funcionalidade num formato de empacotamento existente);
  • bugfix: O PR corrige um bug na implementação existente;
  • doc: O PR é uma melhoria significativa na documentação;
  • removal; O PR representa uma alteração incompatível com versões anteriores na API BeeWare API; ou
  • misc; Uma alteração menor ou administrativa (ex., correção de um erro de ortográfico, um esclarecimento menor de linguagem ou atualização de uma versão de dependência) que não precisa ser anunciada nas notas de lançamento.

Essa descrição na nota de alteração deve ser um resumo de "publicidade" de alto nível da alteração sob a perspetiva do utilizador, e não uma descrição técnica profunda ou detalhes de implementação. Ela é diferente de uma mensagem de submissão - uma mensagem de submissão descreve o que foi feito para que os futuros desenvolvedores possam acompanhar o raciocínio de uma alteração; a nota de alteração é uma descrição para o benefício dos utilizadores, que podem não ter conhecimento dos aspetos internos.

Por exemplo, se corrigir um bug relacionado com a nomenclatura do projeto, a mensagem de submissão poderá ser a seguinte:

Aplicar uma verificação de expressão regular mais forte para não permitir nomes de projetos que comecem com dígitos.

A nota de alteração correspondente seria algo como:

Os nomes dos projetos não podem mais começar com um número.

Alguns PRs vão introduzir várias funcionalidades e corrigir vários bugs, ou introduzir várias alterações incompatíveis com versões anteriores. Neste caso, o PR pode ter vários ficheiros de notas de alteração. Se precisar associar dois tipos de fragmentos à mesma ID, poderá acrescentar um sufixo numérico. Por exemplo, se o PR 789 adicionou uma funcionalidade descrita pelo bilhete 123, fechou um bug descrito pelo bilhete 234 e também fez duas alterações incompatíveis com versões anteriores, pode ter 4 ficheiros de notas de alteração:

  • 123.feature.md
  • 234.bugfix.md
  • 789.removal.1.md
  • 789.removal.2.md

Para mais informações sobre o towncrier e os tipos de fragmentos, consulte News Fragments. Também pode ver exemplos existentes de fragmentos de notícias no diretório changes do repositório BeeWare. Se essa pasta estiver vazia, provavelmente é porque BeeWare publicou recentemente uma nova versão; os ficheiros de notas de alteração são excluídos e combinados para atualizar as notas de lançamento com cada versão. Pode consultar esse ficheiro para ver o estilo de comentário necessário; pode consultar PRs recentemente fundidos para ver como formatar as suas notas de alteração.