Melhore as descrições de pull request usando modelos

Serviços de DevOps do Azure | Azure DevOps Server | Azure DevOps Server 2022 | Azure DevOps Server 2020

Escrever boas descrições de pull request é 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 controlar as coisas que devem ser feitas para cada alteração, como testes, adição de testes de unidade e atualização de documentação. Os modelos de solicitação pull podem ajudar seus desenvolvedores a criar ótimas descrições de pull request que atendam aos padrões da sua organização.

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

Observação

Os modelos de solicitação pull podem fornecer orientação, mas são apenas consultivos. Use políticas de ramificação para aplicar práticas recomendadas, como exigir pedidos de pull para ramificações importantes, como main, exigir que a compilação seja bem-sucedida e impor revisores obrigatórios. Para mais informações, consulte as políticas da branch .

Pré-requisitos

Categoria	Requerimentos
Acesso ao projeto	Membro de um projeto .
Permissões	- Ver código em projetos privados: Acesso pelo menos Básico. - Clone ou contribua para o código em projetos privados: Membro do grupo de segurança Contributors ou permissões correspondentes no projeto. - Definir permissões de ramo ou repositório: Gerir permissões para o ramo ou repositório. - Alterar ramificação padrão: Editar políticas e permissões para o repositório. - Importar um repositório: Membro do grupo de segurança Administradores de Projeto ou com permissão de Criar repositório ao nível do projeto Git definida como Permitir. Para obter mais informações, consulte Definir permissões do repositório Git.
Serviços	Repos ativado.
Ferramentas	Opcional. Utilize os comandos az repos: Azure DevOps CLI.

Observação

Em projetos públicos, os usuários com acesso Partes Interessadas têm acesso total aos repositórios do Azure, incluindo visualização, clonagem e contribuição para o código.

O que é um modelo de pull request?

Um modelo de pull request é um ficheiro que contém texto em Markdown e que é adicionado à descrição do seu pull request quando o pull request é criado.

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 os seguintes tipos de modelos de solicitação pull:

• Um modelo padrão para solicitação de pull 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 para uma ramificação.
• Modelos de solicitação pull específicos de ramificação que são aplicados automaticamente a solicitações pull direcionadas a uma ramificação específica
• Modelos adicionais de pull request que podem ser adicionados opcionalmente pelo criador do pull request

O tipo de modelo de solicitação pull é determinado pelo nome do arquivo e pelo local da pasta, conforme abordado nas seções a seguir. Os nomes de arquivos e as localizações de pastas não são sensíveis a maiúsculas e minúsculas, mas devem estar na ramificação padrão do seu repositório.

Observação

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

Modelos de pull request padrão

Os modelos de solicitação pull padrão são aplicados automaticamente ao campo de descrição quando uma nova solicitação pull é criada. Para configurar seu repositório com um modelo de solicitação pull padrão, crie um arquivo chamado pull_request_template.md ou pull_request_template.txt e salve-o na ramificação padrão do repositório em uma das seguintes pastas.

• 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 lhe dar flexibilidade em onde você armazena seus modelos de solicitação pull. Quando uma solicitação pull é criada, o Azure Repos pesquisa as pastas designadas na ordem dada e usa o primeiro modelo de pull request padrão encontrado.

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

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

Observação

Quando um modelo de solicitação pull padrão ou específico de ramificaçã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 pull request específicos para cada ramificação

Os modelos de pull request específicos de ramo podem ser configurados para pull requests que têm como alvo um ramo específico. Para configurar o seu repositório com um modelo de pull request específico da ramificação, crie um arquivo .txt ou .md com o nome da sua ramificação. O nome deve corresponder ao primeiro nível do nome da filial, como main, dev, releaseou feature. Cada modelo de solicitação pull específico de ramificação é aplicado sempre que uma solicitação pull tem como alvo essa ramificação ou quaisquer ramificações contidas nela. Por exemplo, o modelo de solicitação pull chamado feature.md seria aplicado se uma solicitação pull tivesse como alvo a ramificação feature ou qualquer ramificação feature/*.

Os modelos de pull request específicos de uma ramificação devem ser guardados na ramificação padrão do seu repositório, seguindo a seguinte hierarquia de pastas: pull_request_template/branches/. Essas pastas devem ser baseadas em uma das seguintes pastas no 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 pedido pull específico de uma ramificação que deveria ser aplicado a todos os pedidos pull na ramificação dev seria chamado dev.md ou dev.txt e estaria localizado em um dos seguintes locais.

• <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 padrão de pedido de pull, são fornecidos vários locais que oferecem flexibilidade para armazenar modelos de pedidos de pull específicos de ramo. Quando um pull request é criado, o Azure Repos procura as pastas designadas na ordem dada por um modelo de pull request específico do branch e usa o primeiro que encontrar que corresponda ao nome do branch. Se não for encontrado um modelo de solicitação pull específico da ramificação, o Azure Repos procurará um modelo de solicitação pull padrão, conforme descrito na seção Modelos de solicitação pull padrão anterior.

Modelos adicionais de solicitação de pull

Além dos modelos de solicitação pull padrão e específicos de ramificação, você pode configurar modelos de solicitação pull adicionais. Estes podem ser ficheiros .md ou .txt, localizados numa das seguintes pastas na sua ramificação predefinida.

• <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 pull request é criada, pode-se acrescentar qualquer um dos modelos de pull request disponíveis, escolhendo-os na lista suspensa Adicionar um modelo. Os nomes na lista suspensa baseiam-se nos nomes dos ficheiros dos modelos.

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

• dev.md - Este é o modelo específico da ramificação que foi aplicado por padrão a este pull request na ramificação 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 - Este é normalmente o modelo padrão, mas foi substituído pelo modelo específico da ramificação dev.md nesta solicitação 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 anexar seu conteúdo à descrição atual da solicitação pull.

Observação

Você pode especificar um modelo de pedido de pull para substituir qualquer padrão correspondente ou pedido de pull específico de ramificação anexando ?template=name.md à string de consulta.

Ver também

• Criar uma solicitação pull para revisar e mesclar código
• Sobre filiais e políticas de filiais