Ir para o conteúdo

Adicionando informações sobre alterações para notas de lançamento

BeeWare Docs Tools utiliza o towncrier para auxiliar na criação das notas de versão de cada versão. Quando você envia uma pull request, ela deve incluir uma change note - essa nota de alteração se tornará a entrada nas notas de versão descrevendo a alteração que foi feita.

Todo pull request deve incluir pelo menos um ficheiro no diretório changes/ que forneça uma breve descrição da alteração implementada pelo pull request. A nota de alteração deve estar no formato Markdown, em um ficheiro que tenha o nome no formato <id>.<fragment type>.md. Se a alteração que você está propondo corrigir um bug ou implementar um recurso para o qual há um número de problema existente, o ID será o número desse tíquete. Se a alteração não tiver um problema correspondente, o número do PR poderá ser usado como ID. Você não saberá o número do PR até que envie o pull request, portanto, a primeira passagem do CI 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 (recurso): O PR adiciona um novo comportamento ou recurso que não era possível anteriormente (por exemplo, adicionar suporte a um novo formato de empacotamento ou um novo recurso em um 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 Docs Tools API; ou
  • misc; Uma alteração menor ou administrativa (por exemplo, correção de um erro de digitação, um esclarecimento de linguagem menor ou atualização de uma versão de dependência) que não precisa ser anunciada nas notas da versão.

Essa descrição na nota de alteração deve ser um resumo de "marketing" de alto nível da alteração sob a perspectiva do utilizador, e não uma descrição técnica profunda ou detalhes de implementação. Ela é diferente de uma mensagem de confirmação - uma mensagem de confirmaçã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 aspectos internos.

Por exemplo, se você corrigir um bug relacionado à nomenclatura do projeto, a mensagem de confirmação poderá ser a seguinte:

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

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

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

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

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

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