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

Azure DevOps Services | Servidor Azure DevOps | Azure DevOps Server 2022 | Azure DevOps Server 2020

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 para cada alteração, como testar, adicionar testes de unidade e atualizar a documentação. Os modelos de solicitação pull podem ajudar os 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 são apenas consultivos. Use políticas de branch para impor práticas recomendadas, como exigir solicitações de pull para branches de chave, como principal, exigir um build bem-sucedido e impor revisores necessários. Para obter mais informações, consulte as políticas de branch.

Pré-requisitos

Categoria	Requirements
Acesso ao Projeto	Membro de um projeto.
Permissões	- Exibir código em projetos privados: pelo menos acesso básico . - Clonar ou contribuir para o código em projetos privados: membro do grupo de segurança Colaboradores ou permissões correspondentes no projeto. - Definir permissões de branch ou repositório: gerenciar permissões de permissões para o branch ou repositório. - Alterar o branch padrão: editar permissões de políticas para o repositório. - Importar um repositório: membro do grupo de segurança Administradores do Projeto ou da permissão Criar repositório no nível do projeto do Git definida como Permitir. Para obter mais informações, consulte Definir permissões de repositório Git.
Serviços	Repositórios habilitados.
Ferramentas	Optional. Use comandos az repos : CLI do Azure DevOps.

Observação

Em projetos públicos, os usuários com acesso ao Stakeholder têm acesso total ao Azure Repos, incluindo exibição, clonagem e contribuição para o código.

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

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 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, 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 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 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 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 seu repositório com um modelo de solicitação de pull específico do branch, crie um arquivo ou .txt um .md arquivo com o nome do branch. O nome deve corresponder ao primeiro nível do nome do branch, como main, , devou releasefeature. 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 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/* branches.

Os 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 no local em que você armazena modelos de solicitação de pull específicos da ramificação. 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 o primeiro encontrado que corresponde 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 de modelos de solicitação de pull padrão anterior.

Modelos de solicitação de pull adicionais

Além dos modelos de solicitação 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. Mesmo que 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 ramificação correspondente acrescentando-se ?template=name.md à querystring.

Consulte também

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