Melhores práticas para pull requests

Melhores práticas para criar pull requests

Ao criar uma pull request, siga as melhores práticas para um processo de revisão mais tranquilo. Para obter mais informações sobre a criação de pull requests, confira "Como criar uma solicitação de pull."

Escreva PRs pequenas

Procure criar pull requests pequenas, com foco, que atendam a um propósito único. Pull requests menores são mais fáceis e rápidas de revisar e mesclar, deixam menos espaço para bugs, além de fornecer um histórico mais claro das alterações.

Revise sua própria pull request primeiro

Revise, crie e teste sua própria pull request antes de enviá-la. Isso permitirá que você detecte erros gerais e de digitação que você pode ter deixado passar, antes que outros comecem a revisar.

Forneça contexto e orientação

Escreva títulos e descrições claras para suas pull requests, para que os revisores consigam entender rapidamente o propósito da solicitação. Inclua o seguinte no corpo da pull request:

• A finalidade da pull request
• Uma visão geral das alterações
• Links para algum contexto adicional, como problemas de acompanhamento ou conversas anteriores

Para ajudar os revisores, compartilhe o tipo de feedback necessário. Por exemplo, você precisa de uma olhada rápida ou de uma crítica mais profunda?

Se sua pull request consistir em alterações em vários arquivos, forneça orientação aos revisores sobre a ordem de revisão dos arquivos. Recomende por onde a revisão deve começar e como proceder.

Melhores práticas para gerenciar pull requests

Se você for um mantenedor de repositório, siga estas etapas para gerenciar e padronizar as pull requests que os colaboradores criam em seu repositório.

Usar modelos de solicitação de pull

Os modelos de pull request permitem personalizar e padronizar as informações que você gostaria de incluir quando alguém cria uma pull request em seu repositório. Quando você adicionar um modelo de pull request ao repositório, os contribuidores do projeto verão automaticamente o conteúdo do modelo no texto da pull request. Para obter mais informações, confira "Criar modelos de pull request no repositório".

Você pode usar modelos de pull requests para padronizar o processo de revisão do repositório. Por exemplo, você pode incluir uma lista de tarefas que gostaria que os autores concluíssem antes de mesclar suas pull requests, adicionando uma lista de tarefas ao modelo. Para obter mais informações, confira "Sobre listas de tarefas".

Você pode solicitar que os colaboradores incluam uma referência de problema no corpo da pull request, para que a mesclagem da pull request feche automaticamente o problema. Para obter mais informações, confira "Vinculando uma pull request a um problema".

Definir proprietários de código

Você talvez queira garantir que indivíduos específicos sempre revisem as alterações em determinados códigos ou arquivos em seu repositório. Por exemplo, talvez você queira que um redator técnico em sua equipe sempre revise as alterações no docs diretório.

Você pode definir indivíduos ou equipes que você considera responsáveis pelo código ou arquivos em um repositório como proprietários do código. Quando uma pull request que modifique um código pertencente aos proprietários do código for aberta, eles serão automaticamente solicitados a fazer a revisão. É possível definir proprietários de código para tipos específicos de arquivos ou diretórios, bem como para diferentes branches em um repositório. Para obter mais informações, confira "Sobre os proprietários de código".

Use branches protegidos

É possível usar branches protegidos para impedir que pull requests sejam mescladas em branches importantes, como main, até que determinadas condições sejam atendidas. Por exemplo, você pode exigir a aprovação em testes de CI ou uma revisão de aprovação. Para obter mais informações, confira "Sobre branches protegidos".

Usar conjuntos de regras por push

Com os conjunto de regras por push, é possível bloquear envios por push para um repositório privado ou interno e para toda a rede de bifurcação desse repositório com base em extensões de arquivo, comprimentos de caminho de arquivo, caminhos de arquivo e pasta e tamanhos de arquivo.

As regras de push não exigem nenhum direcionamento de branch porque se aplicam a cada envio por push para o repositório.

Os conjuntos de regras por push permitem:

• Restringir caminhos de arquivo: impedir que confirmações que incluam alterações em caminhos de arquivo especificados sejam enviadas.

  É possível usar a sintaxe fnmatch para essa finalidade. Por exemplo, uma segmentação de restrição test/demo/**/* impede qualquer envio por push para arquivos ou pastas no diretório test/demo/. Uma segmentação de restrição test/docs/pushrules.md impede envios por push especificamente para o arquivo pushrules.md no diretório test/docs/. Para obter mais informações, confira "Criar conjuntos de regras para um repositório".

• Restringir o comprimento do caminho do arquivo: impedir que confirmações que incluam caminhos de arquivo que excedam um limite de caracteres especificado sejam enviadas.

• Restringir extensões de arquivo: impedir que confirmações que incluam arquivos com extensões de arquivo especificadas sejam enviadas.

• Restringir o tamanho do arquivo: impedir que confirmações que excedam um limite de tamanho de arquivo especificado sejam enviadas.

Sobre os conjuntos de regras por push para repositórios bifurcados

As regras de push se aplicam a toda a rede de bifurcação de um repositório, garantindo que cada ponto de entrada do repositório esteja protegido. Por exemplo, se você bifurcar um repositório que tenha conjuntos de regras por push habilitados, os mesmos conjuntos de regras por push também se aplicarão ao repositório bifurcado.

Para um repositório bifurcado, as únicas pessoas que têm permissões de bypass para uma regra de push são as pessoas que têm permissões de bypass no repositório raiz.

Para obter mais informações, confira "Sobre os conjuntos de regras".

Use ferramentas automatizadas para revisar o estilo do código

Use ferramentas automatizadas, como linters, nas pull requests do repositório para manter o estilo consistente e tornar o código mais compreensível. O uso de ferramentas automatizadas para detectar problemas menores, como erros de digitação ou estilo, deixa mais tempo para os revisores se concentrarem na substância de uma pull request.

Por exemplo, você pode usar GitHub Actions para configurar linters de código que possam ser executados em pull requests como parte do fluxo de trabalho de integração contínua (CI). Para obter mais informações, confira "Sobre a integração contínua com o GitHub Actions".