Melhorar descrições de solicitação de pull usando modelos

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2020 | Azure DevOps Server 2019

Escrever boas descrições de solicitação de pull é uma ótima maneira de ajudar os revisores a saber o que esperar ao revisar o código. Eles também são uma ótima maneira de ajudar a acompanhar as coisas que devem ser feitas para cada alteração, como testar, adicionar testes de unidade e atualizar a documentação. Modelos de solicitação pull podem ajudar seus desenvolvedores a criar ótimas descrições de solicitação de pull que atendam aos padrões da sua organização.

Este artigo mostra como começar a usar modelos de solicitação de pull.

Observação

Modelos de solicitação pull podem fornecer diretrizes, mas são apenas consultivos. Use políticas de branch para impor práticas recomendadas, como exigir solicitações de pull para ramificações de chave como a principal, exigir um build bem-sucedido e impor revisores necessários. Para obter mais informações, consulte as políticas de branch.

O que é um modelo de solicitação pull?

Um modelo de solicitação de pull é um arquivo que contém o texto Markdown que é adicionado à descrição da solicitação de pull quando a solicitação de pull é criada.

Thank you for your contribution to the Fabrikam Fiber repo. 
Before submitting this PR, please make sure:

- [ ] Your code builds clean without any errors or warnings
- [ ] You are using approved terminology
- [ ] You have added unit tests

Azure Repos permite que você crie o seguinte tipo de modelos de solicitação de pull:

  • Um modelo de solicitação de pull padrão que é aplicado automaticamente a todas as novas solicitações de pull no repositório, a menos que seja substituído por um modelo de solicitação de pull específico do branch
  • Modelos de solicitação de pull específicos do branch que são aplicados automaticamente a solicitações de pull direcionadas a um branch específico
  • Modelos de solicitação de pull adicionais que podem ser adicionados opcionalmente pelo criador da solicitação de pull

O tipo de modelo de solicitação de pull é determinado por seu nome de arquivo e local da pasta, conforme abordado nas seções a seguir. Os nomes de arquivo e os locais da pasta não diferenciam maiúsculas de minúsculas, mas devem estar no branch padrão do repositório.

Observação

Todos os arquivos de modelo de solicitação de pull devem estar localizados no branch padrão (normalmente principal) do repositório. Somente arquivos de modelo de solicitação de pull do branch padrão são usados.

Modelos de solicitação de pull padrão

Os modelos de solicitação de pull padrão são aplicados automaticamente ao campo de descrição quando uma nova solicitação de pull é criada. Para configurar o repositório com um modelo de solicitação de pull padrão, crie um arquivo nomeado pull_request_template.md ou pull_request_template.txt salve-o no branch padrão do repositório em uma das pastas a seguir.

  • Uma pasta nomeada .azuredevops que está contida na pasta raiz do repositório
  • Uma pasta nomeada .vsts que está contida na pasta raiz do repositório
  • Uma pasta nomeada docs que está contida na pasta raiz do repositório
  • A pasta raiz do repositório

Vários locais são fornecidos para oferecer flexibilidade no local em que você armazena seus modelos de solicitação de pull. Quando uma solicitação de pull é criada, Azure Repos pesquisa as pastas designadas na ordem fornecida e usa o primeiro modelo de solicitação de pull padrão encontrado.

Quando uma nova solicitação de pull é criada no repositório, a menos que um modelo de solicitação de pull específico do branch se aplique, o conteúdo do modelo de solicitação de pull padrão é usado para preencher previamente o campo de descrição na solicitação pull.

Modelo de solicitação de pull padrão

Você pode editar ou adicionar a essa descrição e acrescentar modelos de solicitação de pull adicionais , se desejar, selecionando-os na lista suspensa Adicionar um modelo .

Observação

Quando um modelo de solicitação de pull específico do branch ou padrão é aplicado automaticamente, ele substitui as mensagens de confirmação padrão que geralmente são usadas para a descrição padrão. Você pode adicioná-los novamente selecionando Adicionar mensagens de confirmação.

Modelos de solicitação de pull específicos do branch

Modelos de solicitação de pull específicos do branch podem ser configurados para solicitações de pull direcionadas a um branch específico. Para configurar o repositório com um modelo de solicitação de pull específico do branch, crie um arquivo ou .md um .txt arquivo com o nome da ramificação. O nome deve corresponder ao primeiro nível do nome do branch, como main, dev, releaseou feature. Cada modelo de solicitação de pull específico de ramificação é aplicado sempre que uma solicitação de pull é direcionada a esse branch ou a quaisquer ramificações contidas nele. Por exemplo, o modelo de solicitação de pull nomeado feature.md seria aplicado se uma solicitação de pull direcionasse o feature branch ou quaisquer feature/* ramificações.

Modelos de solicitação de pull específicos do branch devem ser salvos no branch padrão do repositório usando a seguinte hierarquia de pastas: pull_request_template/branches/. Essas pastas devem ser baseadas em uma das pastas a seguir em seu repositório.

  • Uma pasta nomeada .azuredevops que está contida na pasta raiz do repositório
  • Uma pasta nomeada .vsts que está contida na pasta raiz do repositório
  • Uma pasta nomeada docs que está contida na pasta raiz do repositório
  • A pasta raiz do repositório

Por exemplo, um modelo de solicitação de pull específico do branch que deve ser aplicado a todas as solicitações de pull no dev branch seria nomeado dev.md ou dev.txt localizado em um dos locais a seguir.

  • <repository root>/.azuredevops/pull_request_template/branches/
  • <repository root>/.vsts/pull_request_template/branches/
  • <repository root>/docs/pull_request_template/branches/
  • <repository root>/pull_request_template/branches/

Assim como os modelos de solicitação de pull padrão, vários locais são fornecidos para oferecer flexibilidade em que você armazena modelos de solicitação de pull específicos do branch. Quando uma solicitação de pull é criada, Azure Repos pesquisa as pastas designadas na ordem fornecida para um modelo de solicitação de pull específico do branch e usa o primeiro que ele encontra que corresponde ao nome do branch. Se nenhum modelo de solicitação de pull específico do branch for encontrado, Azure Repos procurará um modelo de solicitação de pull padrão, conforme descrito na seção de modelos de solicitação de pull padrão anterior.

Modelo de solicitação de pull específico do branch

Modelos de solicitação de pull adicionais

Além dos modelos de solicitação de pull específicos do branch e padrão, você pode configurar modelos de solicitação de pull adicionais. Eles podem ser .md ou .txt arquivos, localizados em uma das pastas a seguir em seu branch padrão.

  • <repository root>/.azuredevops/pull_request_template/
  • <repository root>/.vsts/pull_request_template/
  • <repository root>/docs/pull_request_template/
  • <repository root>/pull_request_template/

Quando uma solicitação pull é criada, você pode acrescentar qualquer um dos modelos de solicitação de pull disponíveis escolhendo-os na lista suspensa Adicionar um modelo . Os nomes na lista suspensa são baseados nos nomes de arquivo dos modelos.

No exemplo a seguir, três modelos são listados.

  • dev.md - Esse é o modelo específico do branch que foi aplicado por padrão a essa solicitação de pull no branch de desenvolvimento, conforme indicado pela mensagem padrão listada após o nome do arquivo.
  • additional.md - Este é um modelo adicional.
  • pull_request_template.md - Normalmente, esse é o modelo padrão, mas foi substituído pelo modelo específico do dev.md branch nesta solicitação de pull. Embora não tenha sido adicionado por padrão, ele ainda pode ser aplicado selecionando-o na lista.

Modelo de solicitação de pull adicional

Selecione o nome do modelo adicional desejado para acrescentar seu conteúdo à descrição da solicitação de pull atual.

Modelo de solicitação de pull adicional acrescentado

Observação

Você pode especificar um modelo de solicitação de pull para substituir qualquer solicitação de pull padrão ou específica de ramificação correspondente acrescentando-se ?template=name.md à querystring.

Confira também