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

Azure DevOps Services | Azure DevOps Server 2022 - 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 coisas que devem ser feitas em cada alteração, como testar, adicionar testes de unidade e atualizar a documentação. Os modelos de solicitação de 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

Os modelos de solicitação de pull podem fornecer diretrizes, mas servem a fins exclusivamente informativos. Use as políticas de branch para impor as práticas recomendadas, como exigir solicitações de pull para branches de chave, como main, exigir um build bem-sucedido e impor revisores necessários. Para saber mais, confira políticas de branch.

O que é um modelo de solicitação de 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

O 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 de 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 o principal) do repositório. Somente os arquivos do 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 chamado 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 chamada .azuredevops que está contida na pasta raiz do repositório
• Uma pasta chamada .vsts que está contida na pasta raiz do repositório
• Uma pasta chamada 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, o 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 seja aplicável, o conteúdo do modelo de solicitação de pull padrão é usado para pré-popular previamente o campo de descrição na solicitação de pull.

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

Observação

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

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

Os modelos de solicitação de pull específicos do branch podem ser configurados nas solicitações de pull direcionadas a um branch específico. Para configurar seu repositório com um modelo de solicitação de pull específico do branch, crie um .txt ou .md com o nome de seu branch. O nome deve corresponder ao primeiro nível do nome do branch, como main, dev, release ou feature. Cada modelo de solicitação de pull específico do branch é aplicado sempre que uma solicitação de pull é direcionada a esse branch ou a quaisquer branches contidos nele. Por exemplo, o modelo de solicitação de pull chamado feature.md seria aplicado se uma solicitação de pull direcionasse o branch feature ou quaisquer branches feature/*.

Os modelos de solicitação de pull específicos do branch devem ser salvos no branch padrão de seu 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 chamada .azuredevops que está contida na pasta raiz do repositório
• Uma pasta chamada .vsts que está contida na pasta raiz do repositório
• Uma pasta chamada 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 branch dev seria nomeado dev.md ou dev.txt e estaria 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 na localização em que você armazena os modelos de solicitação de pull específicos do branch. Quando uma solicitação de pull é criada, o Azure Repos pesquisa as pastas designadas na ordem fornecida para um modelo de solicitação de pull específico do branch, e usa a primeira encontrada que corresponda ao nome do branch. Se nenhum modelo de solicitação de pull específico do branch for encontrado, o Azure Repos procurará um modelo de solicitação de pull padrão, conforme descrito na seção anterior Modelos de solicitação de pull padrão.

Modelos de solicitação de pull adicionais

Além dos modelos de solicitação de pull padrão e específicos do branch, você pode configurar modelos de solicitação de pull adicionais. Eles podem ser arquivos .md ou .txt, 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 de 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 da lista suspensa se baseiam 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 - Esse é um modelo adicional.
• pull_request_template.md - Normalmente, esse é o modelo padrão, mas foi substituído pelo modelo específico do branch dev.md nessa solicitação de pull. Embora não tenha sido adicionado por padrão, ele ainda pode ser aplicado selecionando-o na lista.

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

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 branch correspondente acrescentando ?template=name.md à querystring.

Confira também

• Criar uma solicitação de pull para examinar e mesclar código
• Sobre ramificações e políticas de ramificação